diff --git a/CHANGES b/CHANGES deleted file mode 100644 --- a/CHANGES +++ /dev/null @@ -1,1308 +0,0 @@ -User-visible changes in the hledger command line tool (and hledger-lib). - - -# 1.12.1 (2018/12/03) - -* roi: use math-functions lib instead of statistics, - be more stackage nightly compatible - - -# 1.12 (2018/12/02) - -* install script: ensure a new-enough version of stack; more informative output - -* build with GHC 8.6/base-4.12 (Peter Simons) - -* add required upper bound for statistics (Samuel May) - -* --anon anonymises more thoroughly (including linked original postings) (Moritz Kiefer) - -* unbalanced transaction errors now include location info (Mykola Orliuk) - -* accounts command: --drop also affects the default flat output, without needing an explicit --flat flag - -* accounts command: the --codes flag has been dropped - -* accounts command: filtering by non-account-name queries now works - -* add command: fix transaction rendering regression during data entry and in journal file - -* balance command: fix wrongful eliding of zero-balance parent accounts in tree mode (Dmitry Astapov) - -* journal format, bs/bse/cf/is commands: account directives can declare account types (#877) - Previously you had to use one of the standard english account names - (assets, liabilities..) for top-level accounts, if you wanted them to - appear in the right place in the balancesheet, balancesheetequity, - cashflow or incomestatement reports. - - Now you can use your preferred account names, and use account directives - to declare which accounting class (Asset, Liability, Equity, Revenue or - eXpense) an account (and its subaccounts) belongs to, by writing one of - the letters A, L, E, R, X after the account name, after two or more - spaces. This syntax may change (see issue). Experimental. - - Currently we allow unlimited account type declarations anywhere in the - account tree. So you could declare a liability account somewhere under - assets, and maybe a revenue account under that, and another asset account - even further down. In such cases you start to see oddities like accounts - appearing in multiple places in a tree-mode report. I have left it this - way for now in case it helps with, eg, modelling contra accounts, or - combining multiple files each with their own account type - declarations. (In that scenario, if we only allowed type declarations on - top-level accounts, or only allowed a single account of each type, - complications seem likely.) - -* journal format: periodic transaction rules now require a double space separator. - In periodic transaction rules which specify a transaction description or - same-line transaction comment, this must be separated from the period - expression by two or more spaces, to prevent ambiguous parsing. Eg - this will parse correctly as "monthly" thanks to the double space: - - ~ monthly In 2020 we'll end this monthly transaction. - -* journal format: exact/complete balance assertions (Samuel May). - A stronger kind of balance assertion, written with a double equals sign, - asserts an account's complete account balance, not just the balance in - one commodity. (But only if it is a single-commodity balance, for now.) - Eg: - - 1/1 - (a) A 1 - (a) B 1 - (a) 0 = A 1 ; commodity A balance assertion, succeeds - (a) 0 == A 1 ; complete balance assertion, fails - -* journal format: account directives now allow whitespace or a comment after the account name - -* journal format: using ~ for home directory in include directives now works (#896) (Mykola Orliuk) - -* journal format: prevent misleading parse error messages with cyclic include directives (#853) (Alex Chen) - -* journal format: transaction modifier multipliers handle total-priced amounts correctly (#928). - Multipliers (*N) in transaction modifier rules did not multiply - total-priced amounts properly. Now the total prices are also multiplied, - keeping the transaction balanced. - -* journal format: do amount inference/balance assignments/assertions before transaction modifiers (#893, #908) (Jesse Rosenthal) - Previously, transaction modifier (auto postings) rules were applied - before missing amounts were inferred. This meant amount multipliers could - generate too many missing-amount postings, making the transaction - unbalanceable (#893). - - Now, missing amount inference (and balance assignments, and balance - assertions, which are interdependent) are done earlier, before - transaction modifier rules are applied (#900, #903). - - Also, we now disallow the combination of balance assignments and - transaction modifier rules which both affect the same account, which - could otherwise cause confusing balance assertion failures (#912). - (Because assignments now generate amounts to satisfy balance assertions - before transaction modifier rules are applied (#908).) - -* journal format: periodic transaction rules are now aware of Y default year directives. (#892) - Ie when a default year Y is in effect, they resolve partial or relative - dates using Y/1/1 as the reference date, rather than today's date. - - -# 1.11.1 (2018/10/06) - -* fix wrong transaction rendering in balance assertion errors and when - using the add command - - -# 1.11 (2018/9/30) - -* The default display order of accounts is now influenced by - the order of account directives. Accounts declared by account - directives are displayed first (top-most), in declaration order, - followed by undeclared accounts in alphabetical order. Numeric - account codes are no longer used, and are ignored and considered - deprecated. - - So if your accounts are displaying in a weird order after upgrading, - and you want them alphabetical like before, just sort your account - directives alphabetically. - -* Account sorting (by name, by declaration, by amount) is now more - robust and supported consistently by all commands (accounts, - balance, bs..) in all modes (tree & flat, tabular & non-tabular). - -* close: new --opening/--closing flags to print only the opening or - closing transaction - -* files: a new command to list included files - -* prices: query arguments are now supported. Prices can be filtered by - date, and postings providing transaction prices can also be filtered. - -* rewrite: help clarifies relation to print --auto (#745) - -* roi: a new command to compute return on investment, based on hledger-irr - -* test: has more verbose output, more informative failure messages, - and no longer tries to read the journal - -* csv: We use a more robust CSV lib (cassava) and now support - non-comma separators, eg --separator ';' (experimental, this flag - will probably become a CSV rule) (#829) - -* csv: interpolated field names in values are now properly case insensitive, so - this works: - - fields ...,Transaction_Date,... - date %Transaction_Date - -* journal: D (default commodity) directives no longer break multiplier - amounts in transaction modifiers (AKA automated postings) (#860) - -* journal: "Automated Postings" have been renamed to "Transaction Modifiers". - -* journal: transaction comments in transaction modifier rules are now parsed correctly. (#745) - -* journal: when include files form a cycle, we give an error instead - of hanging. - -* upper-case day/month names in period expressions no longer give an error (#847, #852) - - -# 1.10 (2018/6/30) - -* journal: many parse error messages have become more informative, and - some now show the source line and error location. - -* journal: ;tag: is no longer parsed as a tag named ";tag" (#655) - -* journal: transaction price amounts having their own price amounts is - now a parse error - -* journal: amounts with space as digit group separator and trailing whitespace - now parse correctly (#780) - -* journal: in amounts containing digits and a single space, the space - is now interpreted as a digit group separator, not a decimal separator (#749) - -* journal: in commodity/format/D directives, the amount must now include a decimal separator. - - When more precise control is needed over number parsing, our - recommended solution is commodity directives. Commodity directives - that don't specify the decimal separator leave things ambiguous, - increasing the chance of misparsing numbers. In some cases it could - cause amounts with a decimal point to be parsed as if with a digit - group separator, so 1.234 became 1234. - - It seems the simple and really only way to do this reliably is to require - an explicit decimal point character. Most folks probably do this already. - Unfortunately, it makes another potential incompatiblity with ledger and - beancount journals. But the error message will be clear and easy to - work around. - -* journal: directives currently have diverse and somewhat tricky - semantics, especially with multiple files. The manual now describes - their behaviour precisely. - -* journal: `alias` and `apply account` directives now affect `account` directives (#825) - -* journal: periodic transactions can now have all the usual transaction fields - (status mark, code, description, comment), for generating more expressive - forecast transactions. - -* journal: forecast transactions now have the generating period - expression attached as a tag named "recur". - -* journal: periodic transactions now start on the first instance of the - recurring date, rather than the day after the last regular transaction (#750) - -* journal: periodic transaction rules now allow period expressions relative to today's date - -* csv: amount-in/amount-out errors are more detailed - -* balance: --drop is now ignored when not in flat mode, - rather than producing a corrupted report (#754) - -* budget: --drop now preserves the top-level account in --budget reports - -* register: in CSV output, the code field is now included (#746) - -* smart dates now allow the YYYYMM format, and are better documented - -* use hledger-lib 1.10 - - -# 1.9.1 (2018/4/30) - -* use hledger-lib 1.9.1 - -* budget (balance --budget): monthly columns are displayed in the - proper order. This fixes a regression in 1.9. - -* budget: budgets can be built from periodic transactions with - different intervals again. In 1.9, budgets were restricted to a - single interval, but this was a mistake. This restores the 1.5 - behaviour. - -* budget: budget reports are more intuitive and much less likely to - produce no output. - -* budget: when no report interval is specified, a budget report for - the whole journal period is shown. - -* budget: periodic transactions and the requested report period can - each have their own start/end dates, and the resulting report will - span the union of those periods, showing zeroes where data is - missing. - -* budget: total row and total/average columns are now calculated correctly - -* budget: actual, percentage, and goal amounts are now aligned in - columns for better readability (usually, unless numbers get huge). - -* budget: combining --budget and --sort-amount is not yet supported - and now gives an error. - -* csv: handle "-%amount" in a rule when the CSV amount is parenthesised (#736) - -* journal: automated postings are now generated early, before journal finalisation, - so they are present for amount inference, transaction balancing, and balance assertions - (#729) - -* journal: automated postings are now inserted right after the posting that triggered them - (#729) - -* cli: command-line account aliases are now applied early, before journal finalisation, - so they are equivalent to alias directives in the journal (#730) - -* journal: inferred amounts now have the appropriate standard amount style applied - (setting the precision correctly, eg). (#737) - -* journal: when checking for balanced transactions, amount styles declared with - commodity directives are also used (previously only inferred amount styles were). - - -# 1.9 (2018/3/31) - -* support ghc 8.4, latest deps - -* journal: account directives can define a numeric account code to -customize sorting. bal/bs/cf/is will sort accounts by account code, -if any, then account name. - -* journal: support scientific number notation (#704, #706) - -* csv: reading a CSV file containing no records is no longer an error - -* cli: when the system text encoding is UTF-8, ignore any UTF-8 BOM -prefix found when reading files. (Paypal's new CSV has this BOM -prefix, causing a confusing parse error.) - -* cli: tabular reports no longer have a trailing blank line added. -(This allows omitting the ">=0" delimiters in our functional tests, -making them easier to read and maintain.) - -* acc: the accounts command now has --declared and --used flags - -* bal: the --invert flag flips all signs - -* bal: --drop now works with CSV output - -* bal/bs/bse/cf/is: show overall report span in title - -* bal/bs/bse/cf/is: show short month names as headings in monthly reports - -* bal/bs/bse/cf/is: these commands can now generate HTML output - -* bal/bs/is/cf: drop short name and indent fields from multicolumn CSV - -* bs/bse/cf/is: these, the "financial statement" commands, now show -normal income, liability and equity balances as positive numbers. -Negative numbers now indicate a contra-balance (eg an overdrawn -checking account), a net loss, or a negative net worth. This makes -these reports more like conventional financial statements, and easier -to read and share with others. (Other commands, like balance, have not -changed.) (experimental) - -* bs/cf/is: always show a tabular report, even with no report -interval. Previously you would get a simple borderless report like -the original balance command. Less code, fewer bugs. - -* bs/bse/cf/is: in CSV output, don't repeat the headings row for each subreport - -* budget: warn that CSV output with bal --budget is unimplemented - -* budget: bal --budget shows budget goals even with no or zero actual amounts. -Makes budget reports more intuitive, at the cost of a temporary hack -which may misorder columns in some cases (if actual and budget -activity occur in a different range of columns). - -* budget: --budget uses only periodic txns with the selected interval. -Budgets with different interval, eg a daily and weekly budget, are independent. - -* budget: show mostly fixed-width columns for readability - -* budget: fix bug where a budget report could include budget goals -ending on the day before the report start date (splitSpan issue) - -* close: the equity command has been renamed to close. It now ignores -any begin date (it always closes historical end balances). It also -ignores --date2. - - -# 1.5 (2017/12/31) - -* --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) - -* cli: a @FILE argument reads flags & args from FILE, one per line - -* cli: reorganized commands list, added some new command aliases: - accounts: a - balance: b - print: p, txns - register: r - -* cli: accept -NUM as a shortcut for --depth=NUM (eg: -2) - -* cli: improve command-line help for --date2 (#604) - -* cli: make --help and -h the same, drop --man and --info for now (#579) - -* help: offers multiple formats, accepts topic substrings. - The separate info/man commands have been dropped. help now - chooses an appropriate documentation format as follows: - - it uses info if available, - - otherwise man if available, - - otherwise $PAGER if defined, - - otherwise less if available, - - otherwise it prints on stdout - - (and it always prints on stdout when piped). - You can override this with the `--info`/`--man`/`--pager`/`--cat` flags. - (#579) - -* bal/bs/cf/is: --sort-amount/-S sorts by largest amount instead of - account name - -* bs/cf/is: support --output-file and --output-format=txt|csv - The CSV output should be reasonably ok for dragging into a - spreadsheet and reformatting. - -* bal/bs/cf/is: consistent double space between columns, consistent - single final blank line. Previously, amounts wider than the column - headings would be separated by only a single space. - -* bs/is: don't let an empty subreport disable the grand totals (fixes #588) - -* cf: exclude asset accounts with ":fixed" in their name (Christian G. Warden, Simon Michael, #584) - -* new balancesheetequity command: like balancesheet but also shows - equity accounts (Nicholas Niro) - -* new import command: adds new transactions seen in one or more input - files to the main journal file - -* print: --new shows only transactions added since last time - (saves state in .latest.JOURNALFILE file) - -* new tags command: lists tags in matched transactions - -* most addons formerly shipped in bin/ are now builtin commands. These - include: check-dates, check-dupes, equity, prices, print-unique, - register-match, rewrite. - -* refactor: new Commands module and subdirectory. - Builtin commands are now gathered more tightly in a single module, - Hledger.Cli.Commands, facilitating change. The legacy "convert" - command has been dropped. - -* refactor: BalanceView -> CompoundBalanceCommand - -* deps: drop support for directory < 1.2 - -* deps: allow ansi-terminal 0.7 - -* deps: drop oldtime flag, require time 1.5+ - -* deps: simplify shakespeare bounds - -* deps: remove ghc < 7.6 support - - -# 1.3.1 (2017/8/25) - -* bs/is: don't let an empty subreport disable the grand totals (#588) - -* allow megaparsec 6 (#594) - -* allow megaparsec-6.1 (Hans-Peter Deifel) - -* restore upper bounds on hledger packages - - -# 1.3 (2017/6/30) - -The "uncleared" transaction/posting status, and associated UI flags -and keys, have been renamed to "unmarked" to remove ambiguity and -confusion. This means that we have dropped the `--uncleared` flag, -and our `-U` flag now matches only unmarked things and not pending -ones. See the issue and linked mail list discussion for more -background. (#564) - -Also the -P short flag has been added for --pending, and the -U/-P/-C -flags can be combined. - -bs/is: fix "Ratio has zero denominator" error (#535) - -bs/is/cf: fix --flat (#552) (Justin Le, Simon Michael) - -bal/bs/is/cf: show negative amounts in red (Simon Michael, Justin Le). -These commands now shows negative amounts in red, when hledger detects -that ANSI codes are supported, (ie when TERM is not "dumb" and stdout -is not being redirected or piped). - -print: show pending mark on postings (fixes #563). -A pending mark on postings is now displayed, just like a cleared mark. -Also there will now be a space between the mark and account name. - -print: amounts are now better aligned, eg when there are posting -status marks or virtual postings - - -# 1.2 (2017/3/31) - -## CLI - -"hledger" and "hledger -h" now print a better organised commands list -and general usage message respectively (#297). - -The common reporting flags can now be used anywhere on the command line. - -Fixed deduplication of addons in commands list. - -Fixed ugly stack traces in command line parse error messages. - -The -V/--value flag is now a global report flag, so it works with -balance, print, register, balancesheet, incomestatement, cashflow, -etc. (Justin Le) - -The `--pivot` global reporting option replaces all account names with -the value of some other field or tag. It has been improved, eg: - -- we don't add the field/tag name name as a prefix -- when pivoting on a tag, if the tag is missing we show a blank - (rather than showing mixed tag values and account names) -- a pipe character delimiter may be used in descriptions to get a more accurate - and useful payee report (`hledger balance --pivot payee`) - -options cleanups - -## Addons - -Easier installation: -move add-ons and example scripts to bin/, -convert to stack scripts, -add a build script to install all deps, -add some functional tests, -test add-ons with Travis CI, -add installation docs to download page. - -Improved docs: -all addons now contain their own documentation. Most of them (all but -hledger-budget) use a new reduced-boilerplate declaration format -and can show short (-h) and long (--help) command line help. -(Long help is declared with pre and postambles to the generated -options help, short help is that truncated at the start of the hledger -common flags.) - -`hledger` now shows a cleaner list of addon commands, showing only the -compiled version of an addon when both source and compiled versions -are in $PATH. (Addons with .exe extension or no extension are -considered compiled. Modification time is not checked, ie, an old -compiled addon will override a newer source version. If there are -three or more versions of an addon, all are shown. ) - -New addons added/included: - -- autosync - example symlink to ledger-autosync -- budget - experimental budget reporting command supporting Ledger-like periodic transactions and automated transactions (Mykola Orliuk) -- chart - pie-chart-generating prototype, a repackaging of the old hledger-chart tool -- check - more powerful balance assertions (Michael Walker) -- check-dupes - find accounts sharing the same leaf name (Stefano Rodighiero) -- prices - show all market price records (Mykola Orliuk) -- register-match - a helper for ledger-autosync's deduplication, finds best match for a transaction description - -The equity command now always generates a valid journal transaction, -handles prices better, and adds balance assertions (Mykola Orliuk). - -The rewrite command is more robust and powerful (Mykola Orliuk): - -- in addition to command-line rewrite options, it understands rewrite rules - defined in the journal, similar to Ledger's automated transactions (#99). - Eg: - ```journal - = ^income - (liabilities:tax) *.33 - - = expenses:gifts - budget:gifts *-1 - assets:budget *1 - ``` - -- it can generate diff output, allowing easier review of the proposed - changes, and safe modification of original journal files (preserving - file-level comments and directives). Eg: - ``` - hledger-rewrite --diff Agency --add-posting 'Expenses:Taxes *0.17' | patch - ``` - -- rewrites can affect multiple postings in a transaction, not just one. - -- posting-specific dates are handled better - -## balance - -A new --pretty-tables option uses unicode characters for rendering -table borders in multicolumn reports (#522) (Moritz Kiefer) - -## balancesheet/cashflow/incomestatement - -These commands are now more powerful, able to show multicolumn reports -and generally having the same features as the balance command. (Justin Le) - -balancesheet has always ignored a begin date specified with a `-b` or -`-p` option; now it also ignores a begin date specified with a `date:` -query. (Related discussion at #531) - -## print - -The output of print is now always a valid journal (fixes #465) (Mykola Orliuk). - -print now tries to preserves the format of implicit/explicit balancing -amounts and prices, by default. To print with all amounts explicit, -use the new `--explicit/-x` flag (fixes #442). (Mykola Orliuk) - -Don't lose the commodity of zero amounts/zero balance assertions (fixes #475) (Mykola Orliuk) - -## Misc - -Fix a regression in the readability of option parsing errors (#478) (Hans-Peter Deifel) - -Fix an example in Cli/Main.hs (Steven R. Baker) - -Allow megaparsec 5.2 (#503) - - -# 1.1 (2016/12/31) - -## balance - -- with -V, don't ignore market prices in the future (#453, #403) - -- with -V and multiple same-date market prices, use the last parsed not the highest price (#403) - -## misc - -- fix non-existent "oldtime" dependency (#431) - -- extra/hledger-equity.hs now generates valid journal format when there are multiple commodities - - -# 1.0.1 (2016/10/27) - -- allow megaparsec 5.0 or 5.1 - -- fix benchmark build failure (#423) - - -# 1.0 (2016/10/26) - -## add - -- suggest only one commodity at a time as default amount (#383) - - (since we currently can't input more than one at a time) - -## balance - -- added --change flag for consistency - -- -H/--historical now also affects single-column balance reports with a start date (#392). - - This has the same effect as just omitting the start date, but adds consistency. - -- in CSV output, render amounts in one-line format (#336) - -## balancesheet - -- fix an infinite loop (#393) - -## print - -- in CSV output, fix and rename the transaction id field - -## register - -- fix a sorting regression with --date2 (#326) - -- --average/-A is now affected by --historical/-H - -- added --cumulative flag for consistency - -- in CSV output, include the transaction id and rename the total field (#391) - -## stats - -- fixed an issue with ordering of include files - -## misc - -- --pivot option added, groups postings by tag instead of account (#323) (Malte Brandy) - -- --anon option added, obfuscates account names and descriptions (#265) (Brian Scott) - - (Only affects the hledger tool, for now.) - -- try to clarify balance/register's various report modes, - - kinds of "balance" displayed, and related options and language. - -- with multiple --change/--cumulative/--historical flags, use the last one instead of complaining - -- don't add the "d" suffix when displaying day periods - -- stack-ify extra/hledger-rewrite.hs - -## misc - -- added GHC 8 support, dropped GHC 7.6 and 7.8 support. - - GHC 7.8 support could be restored with small code changes and a maintainer. - -- a cabal.project file has been added (Moritz Kiefer) - -- use hpack for maintaining cabal files (#371). - - Instead of editing cabal files directly, we now edit the less - verbose and less redundant package.yaml files and let stack (or - hpack) update the cabal files. We commit both the .yaml and - .cabal files. - -- clean up some old cabal flags - -- tools/simplebench has been spun off as the quickbench package. - -- add Appveyor CI builds, provide up-to-date binaries for Windows - -- extra: add a bunch of CSV rules examples - -## docs - -- the website is simpler, clearer, and more mobile-friendly. - - Docs are now collected on a single page and organised by type: getting started, reference, more. - -- reference docs have been split into one manual for each executable and file format. - - This helps with maintenance and packaging and also should make it - easier to see what's available and to read just what you need. - -- manuals are now provided in html, plain text, man and info formats - - generated from the same source by a new Shake-based docs build system. (#292) - -- versioned manuals are provided on the website, covering recent releases and the latest dev version (#385, #387) - -- manuals are built in to the hledger executables, allowing easy offline reading on all platforms. - - PROG -h shows PROG's command-line usage - PROG --help shows PROG's manual (fixed width) - PROG --man shows PROG's manual with man (formatted/paged) - PROG --info shows PROG's manual with info (hypertext) - hledger help [TOPIC] shows any manual - hledger man [TOPIC] shows any manual with man - hledger info [TOPIC] shows any manual with info - -- the general and reporting options are now listed in all executable manuals. - - We assume any of them which are unsupported are harmlessly ignored. - -- demo.hledger.org is using beancount's example journal. - - This is the somewhat realistic example journal from the beancount - project, tweaked for hledger. - -- minor copyedits (jungle-boogie) - -## cli - -- parsing multiple input files is now robust. - - When multiple -f options are provided, we now parse each file - individually rather than just concatenating them, so they can - have different formats (#320). Note this also means that - directives (like \`Y\` or \`alias\`) no longer carry over from one - file to the next. - -- -I has been added as the short flag for --ignore-assertions - - (this is different from Ledger's CLI, but useful for hledger-ui). - -- parsing an argument-less --debug option is more robust - - - - -0.27 (2015/10/30) - -Account aliases: - -- Regular expression account aliases are now fast enough that you can - use lots of them without slowing things down. They now take - O(aliases x accounts) time, instead of O(aliases x transactions); - also, regular expressions are no longer recompiled unnecessarily. - -Documentation: - -- Each hledger package now includes one or more man pages, generated - from markdown by the mighty pandoc. Currently there are six: one - for each main executable and each input file format. Currently these - somewhat duplicate the manual on the website; this will be resolved - somehow. (#282). - -- The site is now built with hakyll-std, a generic hakyll script. - -- hledger once again has a HCAR entry. - -Tools: - -- The hledger cabal files are now generated from package.yaml files by - hpack, in principle, removing a lot of error-prone duplication and - boilerplate. (In practice, both files are being updated manually - for the moment, until hpack supports flags and conditional blocks.) - -- Time/allocation and heap profiling is working again, and easier: - - - `make quickprof-CMD` generates a profile for CMD, which runs - against one of the sample journals. (CMD must be one word, - enclosing in double quotes isn't working here for some reason). - - - `make quickheap-CMD` generates a heap profile for CMD, in - hledgerprof.ps, and tries to open it in a viewer (currently the - mac-friendly "open" executable, so you may need to adjust this in - the makefile). As with quickprof, CMD must be one word and runs - against one of the sample journals. - - - `make hledgerprof` builds the hledgerprof executable used for - time/allocation profiling. `make hledgercov` builds the hledgercov - executable used for coverage reports. - -- Travis CI now tests the build on each github push and announces - status changes by email and on #hledger. - -Journal format: - -- Dates must now begin with a digit (not /, eg). - -- The comment directive longer requires an end comment, and will - extend to the end of the file(s) without it. - -Command-line interface: - -- Output (balance reports, register reports, print output etc.) - containing wide characters, eg chinese/japanese/korean characters, - should now align correctly, when viewed in apps and fonts that show - wide characters as double width (#242). - -- The argument for --depth or depth: must now be positive. - -add: - -- Journal entries are now written with all amounts explicit, to avoid - losing price info (#283). - -- Fixed a bug which sometimes (when the same letter pair was repeated) - caused it not to pick the most similar past transaction for defaults. - -balance: - -- There is now a -V/--value flag to report current market value (as in Ledger). - It converts all reported amounts using their "default market price". - "Market price" is the new name for "historical prices", defined with the P directive. - The default market price for a commodity is the most recent one found in the journal on or before the report end date. - - Unlike Ledger, hledger's -V uses only the market prices recorded - with P directives; it does not use the "transaction prices" - recorded as part of posting amounts (which are used by -B/--cost). - Also, using both -B and -V at the same time is supported. - -- Fixed a bug in amount normalization which caused amount styles - (commodity symbol placement, decimal point character, etc.) to be - lost in certain cases (#230, #276). - -- The balance command's --format option can now adjust the rendering - style of multi-commodity amounts, if you begin the format string - with one of: - - %_ - renders amounts on multiple lines, bottom-aligned (the default) - %^ - renders amounts on multiple lines, top-aligned - %, - renders amounts on one line, comma-separated - -- The balance report's final total (and the line above it) now adapt - themselves to a custom --format. - -print: - -- The --match option prints the journal entry that best matches a - description (ie whose description field is most similar to the value - given, and if there are several equally similar, the most recent). - This was originally an add-on I used to guess account names for - ledger-autosync. It's nice for quickly looking up a recent - transaction from a guessed or partial description. - -- print now always right-aligns the amounts in an entry, even when - they are wider than 12 characters. (If there is a price, it's - considered part of the amount for right-alignment.) - -register: - -- Amount columns now resize automatically, using more space if it's - needed and available. - - -0.26 (2015/7/12) - -Account aliases: - -- Account aliases are once again non-regular-expression-based, by default. (#252) - - The regex account aliases added in 0.24 trip up people switching between - hledger and Ledger. (Also they are currently slow). - - This change makes the old non-regex aliases the default; they are - unsurprising, useful, and pretty close in functionality to Ledger's. - - The new regex aliases are still available; they must be enclosed - in forward slashes. (Ledger effectively ignores these.) - -Journal format: - -- We now parse, and also print, journal entries with no postings, as - proposed on the mail lists. These are not well-formed General - Journal entries/transactions, but here is my rationale: - - - Ledger and beancount parse them - - if they are parsed, they should be printed - - they provide a convenient way to record (and report) non-transaction events - - they permit more gradual introduction and learning of the concepts. - So eg a beginner can keep a simple journal before learning about accounts and postings. - -- Trailing whitespace after a `comment` directive is now ignored. - -Command-line interface: - -- The -f/file option may now be used multiple times. - This is equivalent to concatenating the input files before running hledger. - The add command adds entries to the first file specified. - -Queries: - -- real: (no argument) is now a synonym for real:1 - -- tag: now matches tag names with a regular expression, like most other queries - -- empty: is no longer supported, as it overlaps a bit confusingly with - amt:0. The --empty flag is still available. - -- You can now match on pending status (#250) - - A transaction/posting status of ! (pending) was effectively equivalent - to * (cleared). Now it's a separate state, not matched by --cleared. - The new Ledger-compatible --pending flag matches it, and so does - --uncleared. - - The relevant search query terms are now status:*, status:! and - status: (the old status:1 and status:0 spellings are deprecated). - - Since we interpret --uncleared and status: as "any state except cleared", - it's not currently possible to match things which are neither cleared - nor pending. - -activity: -- activity no longer excludes 0-amount postings by default. - -add: -- Don't show quotes around the journal file path in the "Creating..." - message, for consistency with the subsequent "Adding..." message. - -balancesheet: -- Accounts beginning with "debt" or now also recognised as liabilities. - -print: -- We now limit the display precision of inferred prices. (#262) - - When a transaction posts to two commodities without specifying the - conversion price, we generate a price which makes it balance (cf - http://hledger.org/manual.html#prices). The print command showed - this with full precision (so that manual calculations with the - displayed numbers would look right), but this sometimes meant we - showed 255 digits (when there are multiple postings in the - commodity being priced, and the averaged unit price is an - irrational number). In this case we now set the price's display - precision to the sum of the (max) display precisions of the - commodities involved. An example: - - hledgerdev -f- print - <<< - 1/1 - c C 10.00 - c C 11.00 - d D -320.00 - >>> - 2015/01/01 - c C 10.00 @ D 15.2381 - c C 11.00 @ D 15.2381 - d D -320.00 - - >>>=0 - - There might still be cases where this will show more price decimal - places than necessary. - -- We now show inferred unit prices with at least 2 decimal places. - - When inferring prices, if the commodities involved have low - display precisions, we don't do a good job of rendering - accurate-looking unit prices. Eg if the journal doesn't use any - decimal places, any inferred unit prices are also displayed with - no decimal places, which makes them look wrong to the user. Now, - we always give inferred unit prices a minimum display precision of - 2, which helps a bit. - -register: -- Postings with no amounts could give a runtime error in some obscure case, now fixed. - -stats: -- stats now supports -o/--outputfile, like register/balance/print. -- An O(n^2) performance slowdown has been fixed, it's now much faster on large journals. - - +--------------------------------------++--------+--------+ - | || 0.25 | 0.26 | - +======================================++========+========+ - | -f data/100x100x10.journal stats || 0.10 | 0.16 | - | -f data/1000x1000x10.journal stats || 0.45 | 0.21 | - | -f data/10000x1000x10.journal stats || 58.92 | 2.16 | - +--------------------------------------++--------+--------+ - -Miscellaneous: - -- The June 30 day span was not being rendered correctly; fixed. (#272) - -- The bench script invoked by "cabal bench" or "stack bench" now runs - some simple benchmarks. - - You can get more accurate benchmark times by running with --criterion. - This will usually give much the same numbers and takes much longer. - - Or with --simplebench, it benchmarks whatever commands are - configured in bench/default.bench. This mode uses the first - "hledger" executable in $PATH. - -- The deprecated shakespeare-text dependency has been removed more thoroughly. - - -0.25.1 (2015/4/29) - -- timelog: support the description field (#247) - - -0.25 (2015/4/7) - -- GHC 7.10 compatibility (#239) - -- build with terminfo support on POSIX systems by default - - On non-windows systems, we now build with terminfo support by - default, useful for detecting terminal width and other things. - - This requires the C curses dev libaries, which makes POSIX - installation slightly harder; if it causes problems you can - disable terminfo support with the new `curses` cabal flag, eg: - cabal install -f-curses ... (or cabal might try this - automatically, I'm not sure). - -- register: use the full terminal width, respect COLUMNS, allow column width adjustment - - On POSIX systems, register now uses the full terminal width by - default. Specifically, the output width is set from: - - 1. a --width option - 2. or a COLUMNS environment variable (NB: not the same as a bash shell var) - 3. or on POSIX (non-windows) systems, the current terminal width - 4. or the default, 80 characters. - - Also, register's --width option now accepts an optional - description column width following the overall width (--width - WIDTH[,DESCWIDTH]). This also sets the account column width, since - the available space (WIDTH-41) is divided up between these two - columns. Here's a diagram: - - <--------------------------------- width (W) ----------------------------------> - date (10) description (D) account (W-41-D) amount (12) balance (12) - DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - Examples: - $ hledger reg # use terminal width on posix - $ hledger reg -w 100 # width 100, equal description/account widths - $ hledger reg -w 100,40 # width 100, wider description - $ hledger reg -w $COLUMNS,100 # terminal width and set description width - -- balance: new -T/--row-total and -A/--average options - - In multicolumn balance reports, -T/--row-total now shows a row totals - column and -A/--average shows a row averages column. - This helps eg to see monthly average expenses (hledger bal ^expenses -MA). - - NB our use of -T deviates from Ledger's UI, where -T sets a custom - final total expression. - -- balance: -N is now short for --no-total -- balance: fix partially-visible totals row with --no-total - - A periodic (not using --cumulative or --historical) balance report - with --no-total now hides the totals row properly. - -- journal, csv: comment lines can also start with * - - As in Ledger. This means you can embed emacs org/outline-mode nodes in - your journal file and manipulate it like an outline. - -0.24.1 (2015/3/15) - -- journal: fix balance accumulation across assertions (#195) - - A sequence of balance assertions asserting first one commodity, then - another, then the first again, was not working. - -- timelog: show hours with two decimal places instead of one (#237) -- in weekly reports, simplify week 52's heading like the others -- disallow trailing garbage in a number of parsers - - Trailing garbage is no longer ignored when parsing the following: - balance --format option, register --width option, hledger-rewrite - options, hledger add's inputs, CSV amounts, posting amounts, - posting dates in tags. - -- allow utf8-string-1 (fpco/stackage/#426) - -0.24 (2014/12/25) - -General: -- fix redundant compilation when cabal installing the hledger packages -- switch to Decimal for representing amounts (#118) -- report interval headings (eg in balance, register reports) are shown - compactly when possible -- general speedups - -Journal format: -- detect decimal point and digit groups more robustly (#196) -- check that transaction dates are followed by whitespace or newline -- check that dates use a consistent separator character -- balance assertions now are specific to a single commodity, like - Ledger (#195) -- support multi-line comments using "comment", "end comment" - directives, like Ledger - -CSV format: -- reading CSV data from stdin now works better -- the rules file include directive is now relative to the current - file's directory (#198) -- the original order of same-day transactions is now usually preserved - (if the records appear to be in reverse date order, we reverse them - before finally sorting by transaction date) -- CSV output is now built in to the balance, print, and register - commands, controlled by -O/--output-format (and -o/--output-file, - see below) - -CLI: -- the --width and --debug options now require their argument (#149) -- when an option is repeated, the last value takes precedence (#219). - This is helpful eg for customising your reporting command aliases on - the fly. -- smart dates (used in -p/-b/-e/date:/date2:) now must use a - consistent separator character, and must be parseable to the end -- output destination and format selection is now built in to the - balance, print and register commands, controlled by -o/--output-file - and -O/--output-format options. Notes: - - -o - means stdout - - an output file name suffix matching a supported format will also - set the output format, unless overridden by --output-format - - commands' supported output formats are listed in their - command-line help. Two formats are currently available: - txt (the default) and csv. -- balance assertions can be disabled with --ignore-assertions - -Account aliases: -- all matching account aliases are now applied, not just one directive - and one option -- account aliases now match by case insensitive regular expressions - matching anywhere in the account name -- account aliases can replace multiple occurrences of the pattern - within an account name -- an account alias replacement pattern can reference matched groups - with \N - -Queries: -- date:/date2: with a malformed date now reports an error instead of - being ignored -- amt: now supports >= or <= -- clarify status: docs and behaviour; "*" is no longer a synonym for - "1" (fixes #227) - -balance: -- fix: in tree mode, --drop is ignored instead of showing empty account names -- a depth limit of 0 now shows summary items with account name "...", - instead of an empty report (#206) -- in multicolumn balance reports, -E now also shows posting-less - accounts with a non-zero balance during the period (in addition to - showing leading & trailing empty columns) -- in multicolumn reports, multi-commodity amounts are rendered on one - line for better layout (#186) -- multicolumn reports' title now includes the report span - -register: -- runs faster with large output -- supports date2:, and date:/date2: combined with --date2, better (fixes - #201, #221, #222) -- a depth limit of 0 now shows summary items (see balance) -- -A/--average now implies -E/--empty -- postings with multi-commodity amounts are now top-aligned, like - Ledger - -Extra commands: -- hledger-equity: fix end date in title; print closing entry too -- hledger-check-dates: added - -0.23.3 (2014/9/12) - -- allow text 1.2+ (#207) - -0.23.2 (2014/5/8) - -- register: also fix date sorting of postings (#184) - -0.23.1 (2014/5/7) - -- register: fix a refactoring-related regression that the tests - missed: if transactions were not ordered by date in the journal, - register could include postings before the report start date in the - output. (#184) -- add: don't apply a default commodity to amounts on entry (#138) -- cli: options before the add-on command name are now also passed to it (#182) -- csv: allow the first name in a fields list to be empty (#178) -- csv: don't validate fields count in skipped lines (#177) - - -0.23 (2014/5/1) - -Journal format: -- A # (hash) in column 0 is now also supported for starting a top-level journal comment, like Ledger. -- The "too many missing amounts" error now reminds about the 2-space rule. -- Fix: . (period) is no longer parsed as a valid amount. -- Fix: default commodity directives no longer limit the maximum display precision (#169). -- Fix: + before an amount is no longer parsed as part of the commodity (#181). - -CLI: -- Command-line help cleanups, layout improvements. -- Descriptions are shown for known add-ons in the command list. -- Command aliases have been simplified. -- Add-ons can now have any of these file extensions: - none, hs, lhs, pl, py, rb, rkt, sh, bat, com, exe. -- Add-ons are displayed without their file extensions when possible. -- Add-ons with the same name as a built-in command or alias are ignored. -- Fix: add-on detection and invocation now works on windows. -- Fix: add-ons with digits in the name are now found. -- Fix: add-on arguments containing a single quote now work. -- Fix: when -- is used to hide add-on options from the main program, - it is no longer passed through as an add-on argument. - -Queries: -- The currency/commodity query prefix (sym:) has been renamed to cur:. -- Currency/commodity queries are applied more strongly in register and - balance reports, filtering out unwanted currencies entirely. Eg - hledger balance cur:'\$' now reports only the dollar amounts even if - there are multi-currency transactions or postings. -- Amount queries like amt:N, amt:N, where N is not 0, now do an unsigned - comparison of the amount and N. That is, they compare the absolute magnitude. - To do a signed comparison instead, write N with its sign (eg amt:+N, amt:<+N, amt:>-N). -- Fix: amount queries no longer give false positives on multi-commodity amounts. - -accounts: -- An accounts command has been added, similar to Ledger's, for listing account names - in flat or hierarchical mode. - -add: -- Tab completion now works at all prompts, and will insert the default if the input area is empty. -- Account and amount defaults are more robust and useful. -- Transactions may also be completed by the enter key, when there are no more default postings. -- Input prompts are displayed in a different colour when supported. - -balance: -- Balance reports in flat mode now always show exclusive (subaccount-excluding) balances. -- Balance reports in flat mode with --depth now aggregate deeper accounts at the depth limit instead of excluding them. -- Multicolumn reports in flat mode now support --drop. -- Multicolumn balance reports can now show the account hierarchy with --tree. -- Multicolumn report start/end dates are adjusted to encompass the displayed - report periods, so the first and last periods are "full" and comparable to the others. -- Fix: zero-balance leaf accounts below a non-zero-balance parent are no longer always shown (#170). -- Fix: multicolumn reports now support --date2 (cf #174). - -balancesheet, cashflow, incomestatement: -- These commands now support --flat and --drop. - -print: -- Tag queries (tag:) will now match a transaction if any of its postings match. - -register: -- The --display option has been dropped. To see an accurate running total which - includes the prior starting balance, use --historical/-H (like balance). -- With a report interval, report start/end dates are adjusted to encompass the displayed - periods, so the first and last periods are "full" and comparable to the others. -- Fix: --date2 now works with report intervals (fixes #174). - -Miscellaneous: -- Default report dates now derive from the secondary dates when --date2 is in effect. -- Default report dates now notice any posting dates outside the transaction dates' span. -- Debug output improvements. -- New add-on example: extra/hledger-rewrite.hs, adds postings to matched entries. -- Compatible with GHC 7.2 (#155) - GHC 7.8, shakespeare 2 - - -0.22.2 (2014/4/16) - -- display years before 1000 with four digits, not three -- avoid pretty-show to build with GHC < 7.4 -- allow text 1.1, drop data-pprint to build with GHC 7.8.x - - -0.22.1 (2014/1/6) and older: see http://hledger.org/release-notes or doc/release-notes.md. diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,1369 @@ +User-visible changes in the hledger command line tool and library. + + +# 1.13 (2019/02/01) + +- cli: reorganised commands list. Addons now have a + prefix. + +- cli: the command line help and manual section for all hledger's + commands are now consistent, and generated from the same source. + +- cli: comprehensive bash completion support is now provided (in + shell-completion/). See how-to in the Cookbook. (Jakob Schöttl) + +- balance --budget: budget amounts now aggregate hierarchically, like + account balances. Unbudgeted accounts can be shown with -E/--empty + (along with zero-balance accounts), and the --show-budgeted flag has + been dropped. (Dmitry Astapov) + +- balance: new --transpose flag switches the rows and columns of + tabular balance reports (in txt and csv output formats). (Dmitry + Astapov) + +- close: generated balance assertions now have exact amounts with all + decimal digits, ignoring display precision. Also, balance assertion + amounts will no longer contain prices. (#941, #824, #958) + +- files: now shows up in the commands list + +- import: be silent when there's nothing to import + +- roi: percentages smaller than 0.01% are displayed as zero (Dmitry + Astapov) + +- stats, ui: correct file order is preserved when using --auto (#949) + +- journal: account directive: the account name can now be followed by + a comment on the same line + +- journal: account directive: account types for the bs/bse/cf/is + commands can now be set with a `type:` tag, whose value is `Asset`, + `Liability`, `Equity`, `Revenue`, `Expense`, `A`, `L`, `E`, `R` or + `X` (case-insensitive). The previous syntax (`account assets A`) is + now deprecated. + +- journal: account directive: account sort codes like `account 1000` + (introduced in 1.9, deprecated in 1.11) are no longer supported. + +- journal: transaction modifiers (auto postings) can affect periodic + transactions (--auto can add postings to transactions generated with + --forecast). (Dmitry Astapov) + +- journal: balance assertion errors now show exact amounts with all + decimal digits. Previously it was possible, in case of a commodity + directive limiting the display precision, to have a balance + assertion error with asserted and actual amounts looking the + same. (#941) + +- journal: fixed a periodic transaction parsing failure (#942) (Dmitry + Astapov) + +# 1.12.1 (2018/12/03) + +- roi: use math-functions lib instead of statistics, + be more stackage nightly compatible + +# 1.12 (2018/12/02) + +- install script: ensure a new-enough version of stack; more informative output + +- build with GHC 8.6/base-4.12 (Peter Simons) + +- add required upper bound for statistics (Samuel May) + +- --anon anonymises more thoroughly (including linked original postings) (Moritz Kiefer) + +- unbalanced transaction errors now include location info (Mykola Orliuk) + +- accounts command: --drop also affects the default flat output, without needing an explicit --flat flag + +- accounts command: the --codes flag has been dropped + +- accounts command: filtering by non-account-name queries now works + +- add command: fix transaction rendering regression during data entry and in journal file + +- balance command: fix wrongful eliding of zero-balance parent accounts in tree mode (Dmitry Astapov) + +- journal format, bs/bse/cf/is commands: account directives can declare account types (#877) + Previously you had to use one of the standard english account names + (assets, liabilities..) for top-level accounts, if you wanted them to + appear in the right place in the balancesheet, balancesheetequity, + cashflow or incomestatement reports. + + Now you can use your preferred account names, and use account directives + to declare which accounting class (Asset, Liability, Equity, Revenue or + eXpense) an account (and its subaccounts) belongs to, by writing one of + the letters A, L, E, R, X after the account name, after two or more + spaces. This syntax may change (see issue). Experimental. + + Currently we allow unlimited account type declarations anywhere in the + account tree. So you could declare a liability account somewhere under + assets, and maybe a revenue account under that, and another asset account + even further down. In such cases you start to see oddities like accounts + appearing in multiple places in a tree-mode report. I have left it this + way for now in case it helps with, eg, modelling contra accounts, or + combining multiple files each with their own account type + declarations. (In that scenario, if we only allowed type declarations on + top-level accounts, or only allowed a single account of each type, + complications seem likely.) + +- journal format: periodic transaction rules now require a double space separator. + In periodic transaction rules which specify a transaction description or + same-line transaction comment, this must be separated from the period + expression by two or more spaces, to prevent ambiguous parsing. Eg + this will parse correctly as "monthly" thanks to the double space: + + ~ monthly In 2020 we'll end this monthly transaction. + +- journal format: exact/complete balance assertions (Samuel May). + A stronger kind of balance assertion, written with a double equals sign, + asserts an account's complete account balance, not just the balance in + one commodity. (But only if it is a single-commodity balance, for now.) + Eg: + + 1/1 + (a) A 1 + (a) B 1 + (a) 0 = A 1 ; commodity A balance assertion, succeeds + (a) 0 == A 1 ; complete balance assertion, fails + +- journal format: account directives now allow whitespace or a comment after the account name + +- journal format: using \~ for home directory in include directives now works (#896) (Mykola Orliuk) + +- journal format: prevent misleading parse error messages with cyclic include directives (#853) (Alex Chen) + +- journal format: transaction modifier multipliers handle total-priced amounts correctly (#928). + Multipliers (*N) in transaction modifier rules did not multiply + total-priced amounts properly. Now the total prices are also multiplied, + keeping the transaction balanced. + +- journal format: do amount inference/balance assignments/assertions before transaction modifiers (#893, #908) (Jesse Rosenthal) + Previously, transaction modifier (auto postings) rules were applied + before missing amounts were inferred. This meant amount multipliers could + generate too many missing-amount postings, making the transaction + unbalanceable (#893). + + Now, missing amount inference (and balance assignments, and balance + assertions, which are interdependent) are done earlier, before + transaction modifier rules are applied (#900, #903). + + Also, we now disallow the combination of balance assignments and + transaction modifier rules which both affect the same account, which + could otherwise cause confusing balance assertion failures (#912). + (Because assignments now generate amounts to satisfy balance assertions + before transaction modifier rules are applied (#908).) + +- journal format: periodic transaction rules are now aware of Y default year directives. (#892) + Ie when a default year Y is in effect, they resolve partial or relative + dates using Y/1/1 as the reference date, rather than today's date. + +# 1.11.1 (2018/10/06) + +- fix wrong transaction rendering in balance assertion errors and when + using the add command + +# 1.11 (2018/9/30) + +- The default display order of accounts is now influenced by + the order of account directives. Accounts declared by account + directives are displayed first (top-most), in declaration order, + followed by undeclared accounts in alphabetical order. Numeric + account codes are no longer used, and are ignored and considered + deprecated. + + So if your accounts are displaying in a weird order after upgrading, + and you want them alphabetical like before, just sort your account + directives alphabetically. + +- Account sorting (by name, by declaration, by amount) is now more + robust and supported consistently by all commands (accounts, + balance, bs..) in all modes (tree & flat, tabular & non-tabular). + +- close: new --opening/--closing flags to print only the opening or + closing transaction + +- files: a new command to list included files + +- prices: query arguments are now supported. Prices can be filtered by + date, and postings providing transaction prices can also be filtered. + +- rewrite: help clarifies relation to print --auto (#745) + +- roi: a new command to compute return on investment, based on hledger-irr + +- test: has more verbose output, more informative failure messages, + and no longer tries to read the journal + +- csv: We use a more robust CSV lib (cassava) and now support + non-comma separators, eg --separator ';' (experimental, this flag + will probably become a CSV rule) (#829) + +- csv: interpolated field names in values are now properly case insensitive, so + this works: + + fields ...,Transaction_Date,... + date %Transaction_Date + +- journal: D (default commodity) directives no longer break multiplier + amounts in transaction modifiers (AKA automated postings) (#860) + +- journal: "Automated Postings" have been renamed to "Transaction Modifiers". + +- journal: transaction comments in transaction modifier rules are now parsed correctly. (#745) + +- journal: when include files form a cycle, we give an error instead + of hanging. + +- upper-case day/month names in period expressions no longer give an error (#847, #852) + +# 1.10 (2018/6/30) + +- journal: many parse error messages have become more informative, and + some now show the source line and error location. + +- journal: ;tag: is no longer parsed as a tag named ";tag" (#655) + +- journal: transaction price amounts having their own price amounts is + now a parse error + +- journal: amounts with space as digit group separator and trailing whitespace + now parse correctly (#780) + +- journal: in amounts containing digits and a single space, the space + is now interpreted as a digit group separator, not a decimal separator (#749) + +- journal: in commodity/format/D directives, the amount must now include a decimal separator. + + When more precise control is needed over number parsing, our + recommended solution is commodity directives. Commodity directives + that don't specify the decimal separator leave things ambiguous, + increasing the chance of misparsing numbers. In some cases it could + cause amounts with a decimal point to be parsed as if with a digit + group separator, so 1.234 became 1234. + + It seems the simple and really only way to do this reliably is to require + an explicit decimal point character. Most folks probably do this already. + Unfortunately, it makes another potential incompatiblity with ledger and + beancount journals. But the error message will be clear and easy to + work around. + +- journal: directives currently have diverse and somewhat tricky + semantics, especially with multiple files. The manual now describes + their behaviour precisely. + +- journal: `alias` and `apply account` directives now affect `account` directives (#825) + +- journal: periodic transactions can now have all the usual transaction fields + (status mark, code, description, comment), for generating more expressive + forecast transactions. + +- journal: forecast transactions now have the generating period + expression attached as a tag named "recur". + +- journal: periodic transactions now start on the first instance of the + recurring date, rather than the day after the last regular transaction (#750) + +- journal: periodic transaction rules now allow period expressions relative to today's date + +- csv: amount-in/amount-out errors are more detailed + +- balance: --drop is now ignored when not in flat mode, + rather than producing a corrupted report (#754) + +- budget: --drop now preserves the top-level account in --budget reports + +- register: in CSV output, the code field is now included (#746) + +- smart dates now allow the YYYYMM format, and are better documented + +- use hledger-lib 1.10 + +# 1.9.1 (2018/4/30) + +- use hledger-lib 1.9.1 + +- budget (balance --budget): monthly columns are displayed in the + proper order. This fixes a regression in 1.9. + +- budget: budgets can be built from periodic transactions with + different intervals again. In 1.9, budgets were restricted to a + single interval, but this was a mistake. This restores the 1.5 + behaviour. + +- budget: budget reports are more intuitive and much less likely to + produce no output. + +- budget: when no report interval is specified, a budget report for + the whole journal period is shown. + +- budget: periodic transactions and the requested report period can + each have their own start/end dates, and the resulting report will + span the union of those periods, showing zeroes where data is + missing. + +- budget: total row and total/average columns are now calculated correctly + +- budget: actual, percentage, and goal amounts are now aligned in + columns for better readability (usually, unless numbers get huge). + +- budget: combining --budget and --sort-amount is not yet supported + and now gives an error. + +- csv: handle "-%amount" in a rule when the CSV amount is parenthesised (#736) + +- journal: automated postings are now generated early, before journal finalisation, + so they are present for amount inference, transaction balancing, and balance assertions + (#729) + +- journal: automated postings are now inserted right after the posting that triggered them + (#729) + +- cli: command-line account aliases are now applied early, before journal finalisation, + so they are equivalent to alias directives in the journal (#730) + +- journal: inferred amounts now have the appropriate standard amount style applied + (setting the precision correctly, eg). (#737) + +- journal: when checking for balanced transactions, amount styles declared with + commodity directives are also used (previously only inferred amount styles were). + +# 1.9 (2018/3/31) + +- support ghc 8.4, latest deps + +- journal: account directives can define a numeric account code to + customize sorting. bal/bs/cf/is will sort accounts by account code, + if any, then account name. + +- journal: support scientific number notation (#704, #706) + +- csv: reading a CSV file containing no records is no longer an error + +- cli: when the system text encoding is UTF-8, ignore any UTF-8 BOM + prefix found when reading files. (Paypal's new CSV has this BOM + prefix, causing a confusing parse error.) + +- cli: tabular reports no longer have a trailing blank line added. + (This allows omitting the ">=0" delimiters in our functional tests, + making them easier to read and maintain.) + +- acc: the accounts command now has --declared and --used flags + +- bal: the --invert flag flips all signs + +- bal: --drop now works with CSV output + +- bal/bs/bse/cf/is: show overall report span in title + +- bal/bs/bse/cf/is: show short month names as headings in monthly reports + +- bal/bs/bse/cf/is: these commands can now generate HTML output + +- bal/bs/is/cf: drop short name and indent fields from multicolumn CSV + +- bs/bse/cf/is: these, the "financial statement" commands, now show + normal income, liability and equity balances as positive numbers. + Negative numbers now indicate a contra-balance (eg an overdrawn + checking account), a net loss, or a negative net worth. This makes + these reports more like conventional financial statements, and easier + to read and share with others. (Other commands, like balance, have not + changed.) (experimental) + +- bs/cf/is: always show a tabular report, even with no report + interval. Previously you would get a simple borderless report like + the original balance command. Less code, fewer bugs. + +- bs/bse/cf/is: in CSV output, don't repeat the headings row for each subreport + +- budget: warn that CSV output with bal --budget is unimplemented + +- budget: bal --budget shows budget goals even with no or zero actual amounts. + Makes budget reports more intuitive, at the cost of a temporary hack + which may misorder columns in some cases (if actual and budget + activity occur in a different range of columns). + +- budget: --budget uses only periodic txns with the selected interval.\ + Budgets with different interval, eg a daily and weekly budget, are independent. + +- budget: show mostly fixed-width columns for readability + +- budget: fix bug where a budget report could include budget goals + ending on the day before the report start date (splitSpan issue) + +- close: the equity command has been renamed to close. It now ignores + any begin date (it always closes historical end balances). It also + ignores --date2. + +# 1.5 (2017/12/31) + +- --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) + +- cli: a @FILE argument reads flags & args from FILE, one per line + +- cli: reorganized commands list, added some new command aliases: + + - accounts: a + - balance: b + - print: p, txns + - register: r + +- cli: accept -NUM as a shortcut for --depth=NUM (eg: -2) + +- cli: improve command-line help for --date2 (#604) + +- cli: make --help and -h the same, drop --man and --info for now (#579) + +- help: offers multiple formats, accepts topic substrings. + The separate info/man commands have been dropped. help now + chooses an appropriate documentation format as follows: + + - it uses info if available, + - otherwise man if available, + - otherwise $PAGER if defined, + - otherwise less if available, + - otherwise it prints on stdout + - (and it always prints on stdout when piped). + + You can override this with the `--info`/`--man`/`--pager`/`--cat` flags. + (#579) + +- bal/bs/cf/is: --sort-amount/-S sorts by largest amount instead of + account name + +- bs/cf/is: support --output-file and --output-format=txt\|csv + The CSV output should be reasonably ok for dragging into a + spreadsheet and reformatting. + +- bal/bs/cf/is: consistent double space between columns, consistent + single final blank line. Previously, amounts wider than the column + headings would be separated by only a single space. + +- bs/is: don't let an empty subreport disable the grand totals (fixes #588) + +- cf: exclude asset accounts with ":fixed" in their name (Christian G. Warden, Simon Michael, #584) + +- new balancesheetequity command: like balancesheet but also shows + equity accounts (Nicholas Niro) + +- new import command: adds new transactions seen in one or more input + files to the main journal file + +- print: --new shows only transactions added since last time + (saves state in .latest.JOURNALFILE file) + +- new tags command: lists tags in matched transactions + +- most addons formerly shipped in bin/ are now builtin commands. These + include: check-dates, check-dupes, equity, prices, print-unique, + register-match, rewrite. + +- refactor: new Commands module and subdirectory. + Builtin commands are now gathered more tightly in a single module, + Hledger.Cli.Commands, facilitating change. The legacy "convert" + command has been dropped. + +- refactor: BalanceView -> CompoundBalanceCommand + +- deps: drop support for directory < 1.2 + +- deps: allow ansi-terminal 0.7 + +- deps: drop oldtime flag, require time 1.5+ + +- deps: simplify shakespeare bounds + +- deps: remove ghc < 7.6 support + +# 1.3.1 (2017/8/25) + +- bs/is: don't let an empty subreport disable the grand totals (#588) + +- allow megaparsec 6 (#594) + +- allow megaparsec-6.1 (Hans-Peter Deifel) + +- restore upper bounds on hledger packages + +# 1.3 (2017/6/30) + +The "uncleared" transaction/posting status, and associated UI flags +and keys, have been renamed to "unmarked" to remove ambiguity and +confusion. This means that we have dropped the `--uncleared` flag, +and our `-U` flag now matches only unmarked things and not pending +ones. See the issue and linked mail list discussion for more +background. (#564) + +Also the -P short flag has been added for --pending, and the -U/-P/-C +flags can be combined. + +bs/is: fix "Ratio has zero denominator" error (#535) + +bs/is/cf: fix --flat (#552) (Justin Le, Simon Michael) + +bal/bs/is/cf: show negative amounts in red (Simon Michael, Justin Le). +These commands now shows negative amounts in red, when hledger detects +that ANSI codes are supported, (ie when TERM is not "dumb" and stdout +is not being redirected or piped). + +print: show pending mark on postings (fixes #563). +A pending mark on postings is now displayed, just like a cleared mark. +Also there will now be a space between the mark and account name. + +print: amounts are now better aligned, eg when there are posting +status marks or virtual postings + +# 1.2 (2017/3/31) + +## CLI + +"hledger" and "hledger -h" now print a better organised commands list +and general usage message respectively (#297). + +The common reporting flags can now be used anywhere on the command line. + +Fixed deduplication of addons in commands list. + +Fixed ugly stack traces in command line parse error messages. + +The -V/--value flag is now a global report flag, so it works with +balance, print, register, balancesheet, incomestatement, cashflow, +etc. (Justin Le) + +The `--pivot` global reporting option replaces all account names with +the value of some other field or tag. It has been improved, eg: + +- we don't add the field/tag name name as a prefix +- when pivoting on a tag, if the tag is missing we show a blank + (rather than showing mixed tag values and account names) +- a pipe character delimiter may be used in descriptions to get a more accurate + and useful payee report (`hledger balance --pivot payee`) + +options cleanups + +## Addons + +Easier installation: +move add-ons and example scripts to bin/, +convert to stack scripts, +add a build script to install all deps, +add some functional tests, +test add-ons with Travis CI, +add installation docs to download page. + +Improved docs: +all addons now contain their own documentation. Most of them (all but +hledger-budget) use a new reduced-boilerplate declaration format +and can show short (-h) and long (--help) command line help. +(Long help is declared with pre and postambles to the generated +options help, short help is that truncated at the start of the hledger +common flags.) + +`hledger` now shows a cleaner list of addon commands, showing only the +compiled version of an addon when both source and compiled versions +are in $PATH. (Addons with .exe extension or no extension are +considered compiled. Modification time is not checked, ie, an old +compiled addon will override a newer source version. If there are +three or more versions of an addon, all are shown. ) + +New addons added/included: + +- autosync - example symlink to ledger-autosync +- budget - experimental budget reporting command supporting Ledger-like periodic transactions and automated transactions (Mykola Orliuk) +- chart - pie-chart-generating prototype, a repackaging of the old hledger-chart tool +- check - more powerful balance assertions (Michael Walker) +- check-dupes - find accounts sharing the same leaf name (Stefano Rodighiero) +- prices - show all market price records (Mykola Orliuk) +- register-match - a helper for ledger-autosync's deduplication, finds best match for a transaction description + +The equity command now always generates a valid journal transaction, +handles prices better, and adds balance assertions (Mykola Orliuk). + +The rewrite command is more robust and powerful (Mykola Orliuk): + +- in addition to command-line rewrite options, it understands rewrite rules + defined in the journal, similar to Ledger's automated transactions (#99). + Eg: + + = ^income + (liabilities:tax) *.33 + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + +- it can generate diff output, allowing easier review of the proposed + changes, and safe modification of original journal files (preserving + file-level comments and directives). Eg: + + hledger-rewrite --diff Agency --add-posting 'Expenses:Taxes *0.17' | patch + +- rewrites can affect multiple postings in a transaction, not just one. + +- posting-specific dates are handled better + +## balance + +A new --pretty-tables option uses unicode characters for rendering +table borders in multicolumn reports (#522) (Moritz Kiefer) + +## balancesheet/cashflow/incomestatement + +These commands are now more powerful, able to show multicolumn reports +and generally having the same features as the balance command. (Justin Le) + +balancesheet has always ignored a begin date specified with a `-b` or +`-p` option; now it also ignores a begin date specified with a `date:` +query. (Related discussion at #531) + +## print + +The output of print is now always a valid journal (fixes #465) (Mykola Orliuk). + +print now tries to preserves the format of implicit/explicit balancing +amounts and prices, by default. To print with all amounts explicit, +use the new `--explicit/-x` flag (fixes #442). (Mykola Orliuk) + +Don't lose the commodity of zero amounts/zero balance assertions (fixes #475) (Mykola Orliuk) + +## Misc + +Fix a regression in the readability of option parsing errors (#478) (Hans-Peter Deifel) + +Fix an example in Cli/Main.hs (Steven R. Baker) + +Allow megaparsec 5.2 (#503) + +# 1.1 (2016/12/31) + +## balance + +- with -V, don't ignore market prices in the future (#453, #403) + +- with -V and multiple same-date market prices, use the last parsed not the highest price (#403) + +## misc + +- fix non-existent "oldtime" dependency (#431) + +- extra/hledger-equity.hs now generates valid journal format when there are multiple commodities + +# 1.0.1 (2016/10/27) + +- allow megaparsec 5.0 or 5.1 + +- fix benchmark build failure (#423) + +# 1.0 (2016/10/26) + +## add + +- suggest only one commodity at a time as default amount (#383) + + (since we currently can't input more than one at a time) + +## balance + +- added --change flag for consistency + +- -H/--historical now also affects single-column balance reports with a start date (#392). + + This has the same effect as just omitting the start date, but adds consistency. + +- in CSV output, render amounts in one-line format (#336) + +## balancesheet + +- fix an infinite loop (#393) + +## print + +- in CSV output, fix and rename the transaction id field + +## register + +- fix a sorting regression with --date2 (#326) + +- --average/-A is now affected by --historical/-H + +- added --cumulative flag for consistency + +- in CSV output, include the transaction id and rename the total field (#391) + +## stats + +- fixed an issue with ordering of include files + +## misc + +- --pivot option added, groups postings by tag instead of account (#323) (Malte Brandy) + +- --anon option added, obfuscates account names and descriptions (#265) (Brian Scott) + + (Only affects the hledger tool, for now.) + +- try to clarify balance/register's various report modes, + + kinds of "balance" displayed, and related options and language. + +- with multiple --change/--cumulative/--historical flags, use the last one instead of complaining + +- don't add the "d" suffix when displaying day periods + +- stack-ify extra/hledger-rewrite.hs + +## misc + +- added GHC 8 support, dropped GHC 7.6 and 7.8 support. + + GHC 7.8 support could be restored with small code changes and a maintainer. + +- a cabal.project file has been added (Moritz Kiefer) + +- use hpack for maintaining cabal files (#371). + + Instead of editing cabal files directly, we now edit the less + verbose and less redundant package.yaml files and let stack (or + hpack) update the cabal files. We commit both the .yaml and + .cabal files. + +- clean up some old cabal flags + +- tools/simplebench has been spun off as the quickbench package. + +- add Appveyor CI builds, provide up-to-date binaries for Windows + +- extra: add a bunch of CSV rules examples + +## docs + +- the website is simpler, clearer, and more mobile-friendly. + + Docs are now collected on a single page and organised by type: getting started, reference, more. + +- reference docs have been split into one manual for each executable and file format. + + This helps with maintenance and packaging and also should make it + easier to see what's available and to read just what you need. + +- manuals are now provided in html, plain text, man and info formats + + generated from the same source by a new Shake-based docs build system. (#292) + +- versioned manuals are provided on the website, covering recent releases and the latest dev version (#385, #387) + +- manuals are built in to the hledger executables, allowing easy offline reading on all platforms. + + PROG -h shows PROG's command-line usage + PROG --help shows PROG's manual (fixed width) + PROG --man shows PROG's manual with man (formatted/paged) + PROG --info shows PROG's manual with info (hypertext) + hledger help [TOPIC] shows any manual + hledger man [TOPIC] shows any manual with man + hledger info [TOPIC] shows any manual with info + +- the general and reporting options are now listed in all executable manuals. + + We assume any of them which are unsupported are harmlessly ignored. + +- demo.hledger.org is using beancount's example journal. + + This is the somewhat realistic example journal from the beancount + project, tweaked for hledger. + +- minor copyedits (jungle-boogie) + +## cli + +- parsing multiple input files is now robust. + + When multiple -f options are provided, we now parse each file + individually rather than just concatenating them, so they can + have different formats (#320). Note this also means that + directives (like \`Y\` or \`alias\`) no longer carry over from one + file to the next. + +- -I has been added as the short flag for --ignore-assertions + + (this is different from Ledger's CLI, but useful for hledger-ui). + +- parsing an argument-less --debug option is more robust + +0.27 (2015/10/30) + +Account aliases: + +- Regular expression account aliases are now fast enough that you can + use lots of them without slowing things down. They now take + O(aliases x accounts) time, instead of O(aliases x transactions); + also, regular expressions are no longer recompiled unnecessarily. + +Documentation: + +- Each hledger package now includes one or more man pages, generated + from markdown by the mighty pandoc. Currently there are six: one + for each main executable and each input file format. Currently these + somewhat duplicate the manual on the website; this will be resolved + somehow. (#282). + +- The site is now built with hakyll-std, a generic hakyll script. + +- hledger once again has a HCAR entry. + +Tools: + +- The hledger cabal files are now generated from package.yaml files by + hpack, in principle, removing a lot of error-prone duplication and + boilerplate. (In practice, both files are being updated manually + for the moment, until hpack supports flags and conditional blocks.) + +- Time/allocation and heap profiling is working again, and easier: + + - `make quickprof-CMD` generates a profile for CMD, which runs + against one of the sample journals. (CMD must be one word, + enclosing in double quotes isn't working here for some reason). + + - `make quickheap-CMD` generates a heap profile for CMD, in + hledgerprof.ps, and tries to open it in a viewer (currently the + mac-friendly "open" executable, so you may need to adjust this in + the makefile). As with quickprof, CMD must be one word and runs + against one of the sample journals. + + - `make hledgerprof` builds the hledgerprof executable used for + time/allocation profiling. `make hledgercov` builds the hledgercov + executable used for coverage reports. + +- Travis CI now tests the build on each github push and announces + status changes by email and on #hledger. + +Journal format: + +- Dates must now begin with a digit (not /, eg). + +- The comment directive longer requires an end comment, and will + extend to the end of the file(s) without it. + +Command-line interface: + +- Output (balance reports, register reports, print output etc.) + containing wide characters, eg chinese/japanese/korean characters, + should now align correctly, when viewed in apps and fonts that show + wide characters as double width (#242). + +- The argument for --depth or depth: must now be positive. + +add: + +- Journal entries are now written with all amounts explicit, to avoid + losing price info (#283). + +- Fixed a bug which sometimes (when the same letter pair was repeated) + caused it not to pick the most similar past transaction for defaults. + +balance: + +- There is now a -V/--value flag to report current market value (as in Ledger). + It converts all reported amounts using their "default market price". + "Market price" is the new name for "historical prices", defined with the P directive. + The default market price for a commodity is the most recent one found in the journal on or before the report end date. + + Unlike Ledger, hledger's -V uses only the market prices recorded + with P directives; it does not use the "transaction prices" + recorded as part of posting amounts (which are used by -B/--cost). + Also, using both -B and -V at the same time is supported. + +- Fixed a bug in amount normalization which caused amount styles + (commodity symbol placement, decimal point character, etc.) to be + lost in certain cases (#230, #276). + +- The balance command's --format option can now adjust the rendering + style of multi-commodity amounts, if you begin the format string + with one of: + + %_ - renders amounts on multiple lines, bottom-aligned (the default) + %^ - renders amounts on multiple lines, top-aligned + %, - renders amounts on one line, comma-separated + +- The balance report's final total (and the line above it) now adapt + themselves to a custom --format. + +print: + +- The --match option prints the journal entry that best matches a + description (ie whose description field is most similar to the value + given, and if there are several equally similar, the most recent). + This was originally an add-on I used to guess account names for + ledger-autosync. It's nice for quickly looking up a recent + transaction from a guessed or partial description. + +- print now always right-aligns the amounts in an entry, even when + they are wider than 12 characters. (If there is a price, it's + considered part of the amount for right-alignment.) + +register: + +- Amount columns now resize automatically, using more space if it's + needed and available. + +0.26 (2015/7/12) + +Account aliases: + +- Account aliases are once again non-regular-expression-based, by default. (#252) + + The regex account aliases added in 0.24 trip up people switching between + hledger and Ledger. (Also they are currently slow). + + This change makes the old non-regex aliases the default; they are + unsurprising, useful, and pretty close in functionality to Ledger's. + + The new regex aliases are still available; they must be enclosed + in forward slashes. (Ledger effectively ignores these.) + +Journal format: + +- We now parse, and also print, journal entries with no postings, as + proposed on the mail lists. These are not well-formed General + Journal entries/transactions, but here is my rationale: + + - Ledger and beancount parse them + - if they are parsed, they should be printed + - they provide a convenient way to record (and report) non-transaction events + - they permit more gradual introduction and learning of the concepts. + So eg a beginner can keep a simple journal before learning about accounts and postings. + +- Trailing whitespace after a `comment` directive is now ignored. + +Command-line interface: + +- The -f/file option may now be used multiple times. + This is equivalent to concatenating the input files before running hledger. + The add command adds entries to the first file specified. + +Queries: + +- real: (no argument) is now a synonym for real:1 + +- tag: now matches tag names with a regular expression, like most other queries + +- empty: is no longer supported, as it overlaps a bit confusingly with + amt:0. The --empty flag is still available. + +- You can now match on pending status (#250) + + A transaction/posting status of ! (pending) was effectively equivalent + to * (cleared). Now it's a separate state, not matched by --cleared. + The new Ledger-compatible --pending flag matches it, and so does + --uncleared. + + The relevant search query terms are now status:*, status:! and + status: (the old status:1 and status:0 spellings are deprecated). + + Since we interpret --uncleared and status: as "any state except cleared", + it's not currently possible to match things which are neither cleared + nor pending. + +activity: + +- activity no longer excludes 0-amount postings by default. + +add: + +- Don't show quotes around the journal file path in the "Creating..." + message, for consistency with the subsequent "Adding..." message. + +balancesheet: + +- Accounts beginning with "debt" or now also recognised as liabilities. + +print: + +- We now limit the display precision of inferred prices. (#262) + + When a transaction posts to two commodities without specifying the + conversion price, we generate a price which makes it balance (cf + http://hledger.org/manual.html#prices). The print command showed + this with full precision (so that manual calculations with the + displayed numbers would look right), but this sometimes meant we + showed 255 digits (when there are multiple postings in the + commodity being priced, and the averaged unit price is an + irrational number). In this case we now set the price's display + precision to the sum of the (max) display precisions of the + commodities involved. An example: + + hledgerdev -f- print + <<< + 1/1 + c C 10.00 + c C 11.00 + d D -320.00 + >>> + 2015/01/01 + c C 10.00 @ D 15.2381 + c C 11.00 @ D 15.2381 + d D -320.00 + + >>>=0 + + There might still be cases where this will show more price decimal + places than necessary. + +- We now show inferred unit prices with at least 2 decimal places. + + When inferring prices, if the commodities involved have low + display precisions, we don't do a good job of rendering + accurate-looking unit prices. Eg if the journal doesn't use any + decimal places, any inferred unit prices are also displayed with + no decimal places, which makes them look wrong to the user. Now, + we always give inferred unit prices a minimum display precision of + 2, which helps a bit. + +register: + +- Postings with no amounts could give a runtime error in some obscure case, now fixed. + +stats: + +- stats now supports -o/--outputfile, like register/balance/print. +- An O(n\^2) performance slowdown has been fixed, it's now much faster on large journals. + + +--------------------------------------++--------+--------+ + | || 0.25 | 0.26 | + +======================================++========+========+ + | -f data/100x100x10.journal stats || 0.10 | 0.16 | + | -f data/1000x1000x10.journal stats || 0.45 | 0.21 | + | -f data/10000x1000x10.journal stats || 58.92 | 2.16 | + +--------------------------------------++--------+--------+ + +Miscellaneous: + +- The June 30 day span was not being rendered correctly; fixed. (#272) + +- The bench script invoked by "cabal bench" or "stack bench" now runs + some simple benchmarks. + + You can get more accurate benchmark times by running with --criterion. + This will usually give much the same numbers and takes much longer. + + Or with --simplebench, it benchmarks whatever commands are + configured in bench/default.bench. This mode uses the first + "hledger" executable in $PATH. + +- The deprecated shakespeare-text dependency has been removed more thoroughly. + +0.25.1 (2015/4/29) + +- timelog: support the description field (#247) + +0.25 (2015/4/7) + +- GHC 7.10 compatibility (#239) + +- build with terminfo support on POSIX systems by default + + On non-windows systems, we now build with terminfo support by + default, useful for detecting terminal width and other things. + + This requires the C curses dev libaries, which makes POSIX + installation slightly harder; if it causes problems you can + disable terminfo support with the new `curses` cabal flag, eg: + cabal install -f-curses ... (or cabal might try this + automatically, I'm not sure). + +- register: use the full terminal width, respect COLUMNS, allow column width adjustment + + On POSIX systems, register now uses the full terminal width by + default. Specifically, the output width is set from: + + 1. a --width option + 2. or a COLUMNS environment variable (NB: not the same as a bash shell var) + 3. or on POSIX (non-windows) systems, the current terminal width + 4. or the default, 80 characters. + + Also, register's --width option now accepts an optional + description column width following the overall width (--width + WIDTH\[,DESCWIDTH\]). This also sets the account column width, since + the available space (WIDTH-41) is divided up between these two + columns. Here's a diagram: + + <--------------------------------- width (W) ----------------------------------> + date (10) description (D) account (W-41-D) amount (12) balance (12) + DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + Examples: + + $ hledger reg # use terminal width on posix + $ hledger reg -w 100 # width 100, equal description/account widths + $ hledger reg -w 100,40 # width 100, wider description + $ hledger reg -w $COLUMNS,100 # terminal width and set description width + +- balance: new -T/--row-total and -A/--average options + + In multicolumn balance reports, -T/--row-total now shows a row totals + column and -A/--average shows a row averages column. + This helps eg to see monthly average expenses (hledger bal \^expenses -MA). + + NB our use of -T deviates from Ledger's UI, where -T sets a custom + final total expression. + +- balance: -N is now short for --no-total +- balance: fix partially-visible totals row with --no-total + + A periodic (not using --cumulative or --historical) balance report + with --no-total now hides the totals row properly. + +- journal, csv: comment lines can also start with * + + As in Ledger. This means you can embed emacs org/outline-mode nodes in + your journal file and manipulate it like an outline. + +0.24.1 (2015/3/15) + +- journal: fix balance accumulation across assertions (#195) + + A sequence of balance assertions asserting first one commodity, then + another, then the first again, was not working. + +- timelog: show hours with two decimal places instead of one (#237) +- in weekly reports, simplify week 52's heading like the others +- disallow trailing garbage in a number of parsers + + Trailing garbage is no longer ignored when parsing the following: + balance --format option, register --width option, hledger-rewrite + options, hledger add's inputs, CSV amounts, posting amounts, + posting dates in tags. + +- allow utf8-string-1 (fpco/stackage/#426) + +0.24 (2014/12/25) + +General: + +- fix redundant compilation when cabal installing the hledger packages +- switch to Decimal for representing amounts (#118) +- report interval headings (eg in balance, register reports) are shown + compactly when possible +- general speedups + +Journal format: + +- detect decimal point and digit groups more robustly (#196) +- check that transaction dates are followed by whitespace or newline +- check that dates use a consistent separator character +- balance assertions now are specific to a single commodity, like + Ledger (#195) +- support multi-line comments using "comment", "end comment" + directives, like Ledger + +CSV format: + +- reading CSV data from stdin now works better +- the rules file include directive is now relative to the current + file's directory (#198) +- the original order of same-day transactions is now usually preserved + (if the records appear to be in reverse date order, we reverse them + before finally sorting by transaction date) +- CSV output is now built in to the balance, print, and register + commands, controlled by -O/--output-format (and -o/--output-file, + see below) + +CLI: + +- the --width and --debug options now require their argument (#149) +- when an option is repeated, the last value takes precedence (#219). + This is helpful eg for customising your reporting command aliases on + the fly. +- smart dates (used in -p/-b/-e/date:/date2:) now must use a + consistent separator character, and must be parseable to the end +- output destination and format selection is now built in to the + balance, print and register commands, controlled by -o/--output-file + and -O/--output-format options. Notes: + - -o - means stdout + - an output file name suffix matching a supported format will also + set the output format, unless overridden by --output-format + - commands' supported output formats are listed in their + command-line help. Two formats are currently available: + txt (the default) and csv. +- balance assertions can be disabled with --ignore-assertions + +Account aliases: + +- all matching account aliases are now applied, not just one directive + and one option +- account aliases now match by case insensitive regular expressions + matching anywhere in the account name +- account aliases can replace multiple occurrences of the pattern + within an account name +- an account alias replacement pattern can reference matched groups + with \N + +Queries: + +- date:/date2: with a malformed date now reports an error instead of + being ignored +- amt: now supports >= or <= +- clarify status: docs and behaviour; \"*\" is no longer a synonym for + "1" (fixes #227) + +balance: + +- fix: in tree mode, --drop is ignored instead of showing empty account names +- a depth limit of 0 now shows summary items with account name "...", + instead of an empty report (#206) +- in multicolumn balance reports, -E now also shows posting-less + accounts with a non-zero balance during the period (in addition to + showing leading & trailing empty columns) +- in multicolumn reports, multi-commodity amounts are rendered on one + line for better layout (#186) +- multicolumn reports' title now includes the report span + +register: + +- runs faster with large output +- supports date2:, and date:/date2: combined with --date2, better (fixes + #201, #221, #222) +- a depth limit of 0 now shows summary items (see balance) +- -A/--average now implies -E/--empty +- postings with multi-commodity amounts are now top-aligned, like + Ledger + +Extra commands: + +- hledger-equity: fix end date in title; print closing entry too +- hledger-check-dates: added + +0.23.3 (2014/9/12) + +- allow text 1.2+ (#207) + +0.23.2 (2014/5/8) + +- register: also fix date sorting of postings (#184) + +0.23.1 (2014/5/7) + +- register: fix a refactoring-related regression that the tests + missed: if transactions were not ordered by date in the journal, + register could include postings before the report start date in the + output. (#184) +- add: don't apply a default commodity to amounts on entry (#138) +- cli: options before the add-on command name are now also passed to it (#182) +- csv: allow the first name in a fields list to be empty (#178) +- csv: don't validate fields count in skipped lines (#177) + +0.23 (2014/5/1) + +Journal format: + +- A # (hash) in column 0 is now also supported for starting a top-level journal comment, like Ledger. +- The "too many missing amounts" error now reminds about the 2-space rule. +- Fix: . (period) is no longer parsed as a valid amount. +- Fix: default commodity directives no longer limit the maximum display precision (#169). +- Fix: + before an amount is no longer parsed as part of the commodity (#181). + +CLI: + +- Command-line help cleanups, layout improvements. +- Descriptions are shown for known add-ons in the command list. +- Command aliases have been simplified. +- Add-ons can now have any of these file extensions: + none, hs, lhs, pl, py, rb, rkt, sh, bat, com, exe. +- Add-ons are displayed without their file extensions when possible. +- Add-ons with the same name as a built-in command or alias are ignored. +- Fix: add-on detection and invocation now works on windows. +- Fix: add-ons with digits in the name are now found. +- Fix: add-on arguments containing a single quote now work. +- Fix: when -- is used to hide add-on options from the main program, + it is no longer passed through as an add-on argument. + +Queries: + +- The currency/commodity query prefix (sym:) has been renamed to cur:. +- Currency/commodity queries are applied more strongly in register and + balance reports, filtering out unwanted currencies entirely. Eg + hledger balance cur:'$' now reports only the dollar amounts even if + there are multi-currency transactions or postings. +- Amount queries like amt:N, amt:N, where N is not 0, now do an unsigned + comparison of the amount and N. That is, they compare the absolute magnitude. + To do a signed comparison instead, write N with its sign (eg amt:+N, amt:<+N, amt:>-N). +- Fix: amount queries no longer give false positives on multi-commodity amounts. + +accounts: + +- An accounts command has been added, similar to Ledger's, for listing account names + in flat or hierarchical mode. + +add: + +- Tab completion now works at all prompts, and will insert the default if the input area is empty. +- Account and amount defaults are more robust and useful. +- Transactions may also be completed by the enter key, when there are no more default postings. +- Input prompts are displayed in a different colour when supported. + +balance: + +- Balance reports in flat mode now always show exclusive (subaccount-excluding) balances. +- Balance reports in flat mode with --depth now aggregate deeper accounts at the depth limit instead of excluding them. +- Multicolumn reports in flat mode now support --drop. +- Multicolumn balance reports can now show the account hierarchy with --tree. +- Multicolumn report start/end dates are adjusted to encompass the displayed + report periods, so the first and last periods are "full" and comparable to the others. +- Fix: zero-balance leaf accounts below a non-zero-balance parent are no longer always shown (#170). +- Fix: multicolumn reports now support --date2 (cf #174). + +balancesheet, cashflow, incomestatement: + +- These commands now support --flat and --drop. + +print: + +- Tag queries (tag:) will now match a transaction if any of its postings match. + +register: + +- The --display option has been dropped. To see an accurate running total which + includes the prior starting balance, use --historical/-H (like balance). +- With a report interval, report start/end dates are adjusted to encompass the displayed + periods, so the first and last periods are "full" and comparable to the others. +- Fix: --date2 now works with report intervals (fixes #174). + +Miscellaneous: + +- Default report dates now derive from the secondary dates when --date2 is in effect. +- Default report dates now notice any posting dates outside the transaction dates' span. +- Debug output improvements. +- New add-on example: extra/hledger-rewrite.hs, adds postings to matched entries. +- Compatible with GHC 7.2 (#155) - GHC 7.8, shakespeare 2 + +0.22.2 (2014/4/16) + +- display years before 1000 with four digits, not three +- avoid pretty-show to build with GHC < 7.4 +- allow text 1.1, drop data-pprint to build with GHC 7.8.x + +0.22.1 (2014/1/6) and older: see http://hledger.org/release-notes or doc/release-notes.md. diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs --- a/Hledger/Cli/CliOptions.hs +++ b/Hledger/Cli/CliOptions.hs @@ -22,7 +22,7 @@ generalflagsgroup3, defMode, defCommandMode, - quickAddonCommandMode, + addonCommandMode, hledgerCommandMode, argsFlag, showModeUsage, @@ -40,6 +40,7 @@ outputFormats, defaultOutputFormat, defaultBalanceLineFormat, + CommandDoc, -- possibly these should move into argsToCliOpts -- * CLI option accessors @@ -194,7 +195,6 @@ -- | A cmdargs mode suitable for a hledger built-in command -- with the given names (primary name + optional aliases). --- The default flags are short and long help (-h and --help). -- The usage message shows [QUERY] as argument. defCommandMode :: [Name] -> Mode RawOpts defCommandMode names = defMode { @@ -211,14 +211,24 @@ ,modeValue=[("command", headDef "" names)] } --- | A cmdargs mode representing the hledger add-on command with the given name. --- Like defCommandMode, but adds a appropriate short help message if the addon name --- is recognised, and includes hledger's common input/reporting/help flags as default. --- Just used by hledger for generating the commands list I think (or possibly for --- invoking the addons as well ?) -quickAddonCommandMode :: Name -> Mode RawOpts -quickAddonCommandMode name = (defCommandMode [name]) { - modeHelp = fromMaybe "" $ lookup (stripAddonExtension name) standardAddonsHelp +-- | A cmdargs mode representing the hledger add-on command with the +-- given name, providing hledger's common input/reporting/help flags. +-- Just used when invoking addons. +addonCommandMode :: Name -> Mode RawOpts +addonCommandMode name = (defCommandMode [name]) { + modeHelp = "" + -- XXX not needed ? + -- fromMaybe "" $ lookup (stripAddonExtension name) [ + -- ("addon" , "dummy add-on command for testing") + -- ,("addon2" , "dummy add-on command for testing") + -- ,("addon3" , "dummy add-on command for testing") + -- ,("addon4" , "dummy add-on command for testing") + -- ,("addon5" , "dummy add-on command for testing") + -- ,("addon6" , "dummy add-on command for testing") + -- ,("addon7" , "dummy add-on command for testing") + -- ,("addon8" , "dummy add-on command for testing") + -- ,("addon9" , "dummy add-on command for testing") + -- ] ,modeGroupFlags = Group { groupUnnamed = [] ,groupHidden = [] @@ -226,74 +236,54 @@ } } --- | A template for a command's CLI help, influencing the content and layout --- of the usage text generated by a cmdargs mode. --- It is a multiline string structured like so: --- The first line defines the command name (first word) and aliases (any other words). --- From the second line up to a line containing just "FLAGS", or the end, is the preamble, --- displayed above the flags list generated by cmdargs. Short help goes here. --- Any lines after the FLAGS line are the postamble, displayed below the flags list. --- Long help/full manual goes here. -type HelpTemplate = String - --- | Parse a help template into command names, help preamble, and help postamble lines. -parseHelpTemplate :: HelpTemplate -> Maybe ([Name], String, [String]) -parseHelpTemplate t = - case lines t of - [] -> Nothing - (l:ls) -> Just (names, preamble, postamblelines) - where - names = words l - (preamblels, postamblels) = break (== "FLAGS") ls - preamble = unlines $ reverse $ dropWhile null $ reverse preamblels - postamblelines = dropWhile null $ drop 1 postamblels +-- | A command's documentation. Used both as part of CLI help, and as +-- part of the hledger manual. See parseCommandDoc. +type CommandDoc = String -- | Build a cmdarg mode for a hledger command, -- from a help template and flag/argument specifications. -- Reduces boilerplate a little, though the complicated cmdargs -- flag and argument specs are still required. -hledgerCommandMode :: HelpTemplate -> [Flag RawOpts] -> [(Help, [Flag RawOpts])] +hledgerCommandMode :: CommandDoc -> [Flag RawOpts] -> [(String, [Flag RawOpts])] -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts -hledgerCommandMode tmpl ungroupedflags groupedflags hiddenflags args = - case parseHelpTemplate tmpl of - Nothing -> error' $ "Could not parse help template:\n"++tmpl++"\n" - Just (names, preamble, postamblelines) -> +hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr = + case parseCommandDoc doc of + Nothing -> error' $ "Could not parse command doc:\n"++doc++"\n" + Just (names, shorthelp, longhelplines) -> (defCommandMode names) { - modeHelp = preamble - ,modeHelpSuffix = postamblelines - ,modeGroupFlags = Group { - groupUnnamed = ungroupedflags - ,groupNamed = groupedflags - ,groupHidden = hiddenflags + modeHelp = shorthelp + ,modeHelpSuffix = longhelplines + ,modeGroupFlags = Group { + groupUnnamed = unnamedflaggroup + ,groupNamed = namedflaggroups + ,groupHidden = hiddenflaggroup } - ,modeArgs = args + ,modeArgs = argsdescr } --- | Built-in descriptions for some of the known addons. -standardAddonsHelp :: [(String,String)] -standardAddonsHelp = [ - ("chart", "generate simple balance pie charts") - ,("interest", "generate interest transaction entries") - ,("irr", "calculate internal rate of return") - ,("vty", "start the curses-style interface") - ,("web", "start the web interface") - ,("accounts", "list account names") - ,("files", "list included files") - ,("balance-csv", "output a balance report as CSV") - ,("close", "show a transaction entry zeroing all accounts") - ,("print-unique", "print only transactions with unique descriptions") - ,("register-csv", "output a register report as CSV") - ,("rewrite", "add specified postings to matched transaction entries") - ,("addon", "dummy add-on command for testing") - ,("addon2", "dummy add-on command for testing") - ,("addon3", "dummy add-on command for testing") - ,("addon4", "dummy add-on command for testing") - ,("addon5", "dummy add-on command for testing") - ,("addon6", "dummy add-on command for testing") - ,("addon7", "dummy add-on command for testing") - ,("addon8", "dummy add-on command for testing") - ,("addon9", "dummy add-on command for testing") - ] +-- | Parse a command's documentation, as follows: +-- +-- - First line: the command name then any aliases, as one or more space or comma-separated words +-- +-- - Second line to a line containing just _FLAGS_, or the end: the short help +-- +-- - Any lines after _FLAGS_: the long help (split into lines for cmdargs) +-- +-- The CLI help displays the short help, then the cmdargs-generated +-- flags list, then the long help (which some day we might make +-- optional again). The manual displays the short help followed by +-- the long help, with no flags list. +-- +parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String]) +parseCommandDoc t = + case lines t of + [] -> Nothing + (l:ls) -> Just (names, shorthelp, longhelplines) + where + names = words $ map (\c -> if c `elem` [',','\\'] then ' ' else c) l + (shorthelpls, longhelpls) = break (== "_FLAGS_") ls + shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls + longhelplines = dropWhile null $ drop 1 longhelpls -- | Get a mode's usage message as a nicely wrapped string. showModeUsage :: Mode a -> String @@ -667,8 +657,8 @@ optional (string "." >> choice' (map (string . T.pack) addonExtensions)) eof -stripAddonExtension :: String -> String -stripAddonExtension = regexReplace re "" where re = "\\.(" ++ intercalate "|" addonExtensions ++ ")$" +-- stripAddonExtension :: String -> String +-- stripAddonExtension = regexReplace re "" where re = "\\.(" ++ intercalate "|" addonExtensions ++ ")$" addonExtensions :: [String] addonExtensions = diff --git a/Hledger/Cli/Commands.hs b/Hledger/Cli/Commands.hs --- a/Hledger/Cli/Commands.hs +++ b/Hledger/Cli/Commands.hs @@ -1,10 +1,14 @@ {-| hledger's built-in commands, and helpers for printing the commands list. + +New built-in commands should be added in four places below: +the export list, the import list, builtinCommands, commandsList. -} +{-# LANGUAGE CPP #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE QuasiQuotes #-} -{-# LANGUAGE CPP #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands ( findCommand @@ -37,9 +41,9 @@ ) where +import Data.Char (isSpace) import Data.Default import Data.List -import Data.List.Split (splitOn) #if !(MIN_VERSION_base(4,11,0)) import Data.Monoid ((<>)) #endif @@ -78,8 +82,8 @@ import Hledger.Cli.Commands.Stats import Hledger.Cli.Commands.Tags - --- | The cmdargs subcommand mode and IO action for each builtin command. +-- | The cmdargs subcommand mode (for command-line parsing) +-- and IO action (for doing the command's work) for each builtin command. -- Command actions take parsed CLI options and a (lazy) finalised journal. builtinCommands :: [(Mode RawOpts, CliOpts -> Journal -> IO ())] builtinCommands = [ @@ -109,83 +113,104 @@ ,(testmode , testcmd) ] --- | All names and aliases of builtin commands. -builtinCommandNames :: [String] -builtinCommandNames = concatMap (modeNames . fst) builtinCommands - --- | Look up a builtin command's mode and action by exact command name or alias. -findCommand :: String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ()) -findCommand cmdname = find (elem cmdname . modeNames . fst) builtinCommands - --- | A template for the commands list, containing entries (indented lines) --- for all known and some hypothetical builtin and addon commands. --- These will be filtered based on the commands found at runtime, --- except those beginning with "hledger", which are not filtered. +-- | The commands list, showing command names, standard aliases, +-- and short descriptions. This is modified at runtime, as follows: +-- -- PROGVERSION is replaced with the program name and version. --- OTHER is replaced with an entry for each unknown addon command found. --- --- The command descriptions here should be kept synced with --- each command's builtin help and with hledger manual's command list. -- +-- Lines beginning with a space represent builtin commands, with format: +-- COMMAND (ALIASES) DESCRIPTION +-- These should be kept synced with builtinCommands above, and +-- their docs (Commands/\*.md). +-- +-- Lines beginning with + represent known addon commands. These lines +-- will be suppressed if hledger-CMD is not found in $PATH at runtime. +-- +-- OTHER is replaced with additional command lines (without descriptions) +-- for any unknown addon commands found in $PATH at runtime. +-- +-- TODO: generate more of this automatically. +-- commandsList :: String commandsList = [here| ------------------------------------------------------------------------------- -PROGVERSION, commands available: +PROGVERSION +Usage: hledger COMMAND [OPTIONS] [-- ADDONCMDOPTIONS] +Commands (+ addons found in $PATH): -Data entry: - add add transactions using console ui - iadd add transactions using curses ui - import add new transactions from one or more import files - edit open a text editor on some part of the journal +Data entry (these commands modify the journal file): + add add transactions using guided prompts ++iadd add transactions using curses ui + import add any new transactions from other files (eg csv) -Statements: - balancesheet (bs) show a simple balance sheet with net worth - balancesheetequity (bse) show a detailed balance sheet with equity - cashflow (cf) show a cashflow statement - incomestatement (is) show an income statement +Data management: ++autosync download/deduplicate/convert OFX data ++check check more powerful balance assertions + check-dates check transactions are ordered by date + check-dupes check for accounts with the same leaf name + close (equity) generate balance-resetting transactions ++diff compare account transactions in two journal files ++interest generate interest transactions + rewrite generate automated postings/diffs (old, use --auto) -Basic reports: +Financial reports: + balancesheet (bs) show assets, liabilities and net worth + balancesheetequity (bse) show assets, liabilities and equity + cashflow (cf) show changes in liquid assets + incomestatement (is) show revenues and expenses ++irr calculate internal rate of return (old, use roi) + roi show return on investments + +Low-level reports: accounts (a) show account names - activity show a chart of posting counts per interval - aregister (ar, areg) show transactions in a single account - balance (b, bal) show account balance changes or ending balances + activity show postings-per-interval bar charts + balance (b, bal) show balance changes/end balances/budgets in accounts + files show input file paths prices show market price records - print (p, txns) show transactions/journal entries - register (r, reg) show postings to one or more accounts + print (p, txns) show transactions (journal entries) + print-unique show only transactions with unique descriptions + register (r, reg) show postings in one or more accounts & running total + register-match show a recent posting that best matches a description stats show journal statistics tags show tag names - -UIs: - ui start curses ui - web start web ui + test run self tests -Generating data: - close generate balance-resetting transactions - interest generate interest transactions - rewrite generate automated postings on matched transactions +Alternate user interfaces: ++ui run curses ui ++web run web ui ++api run http api server -Other/experimental: - api start web api server - autosync download/deduplicate/convert OFX data - budget add automated postings/txns/bucket accts - chart generate simple balance pie charts - check check more powerful balance assertions - check-dates check transactions are ordered by date - check-dupes check for accounts with the same leaf name - diff compare account transactions in two journal files - irr calculate internal rate of return of an investment - print-unique show only transactions with unique descriptions - register-match show best matching transaction for a description - roi calculate return on investments - test run self tests +Other: OTHER Help: - help show any of the hledger manuals in various formats - hledger CMD -h show command usage - hledger -h show general usage -------------------------------------------------------------------------------- + (no arguments) show this commands list + -h show general flags + COMMAND -h show flags & docs for COMMAND + help [MANUAL] show hledger manuals in various formats + |] +-- commands show brief commands list +-- edit open a text editor on some part of the journal +-- aregister (ar, areg) show transactions in a single account + +-- | All names and aliases of builtin commands. +builtinCommandNames :: [String] +builtinCommandNames = concatMap (modeNames . fst) builtinCommands + +-- | Look up a builtin command's mode and action by exact command name or alias. +findCommand :: String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ()) +findCommand cmdname = find (elem cmdname . modeNames . fst) builtinCommands + +-- | Extract the command names from commandsList: the first word +-- of lines beginning with a space or + sign. +commandsFromCommandsList :: String -> [String] +commandsFromCommandsList s = + [w | c:l <- lines s, c `elem` [' ','+'], let w:_ = words l] + +knownCommands :: [String] +knownCommands = sort $ commandsFromCommandsList commandsList + -- | Print the commands list, modifying the template above based on -- the currently available addons. Missing addons will be removed, and -- extra addons will be added under Misc. @@ -193,55 +218,34 @@ printCommandsList addonsFound = putStr $ regexReplace "PROGVERSION" (prognameandversion) $ - regexReplace "OTHER" (unlines $ map (' ':) unknownCommandsFound) $ - -- regexReplace "COUNT" (show cmdcount) $ + regexReplace "OTHER" (unlines $ (map ('+':) unknownCommandsFound)) $ unlines $ concatMap adjustline $ lines $ cmdlist where cmdlist = commandsList - -- cmdcount = length $ commandsFromCommandsList cmdlist - commandsFound = builtinCommandNames ++ addonsFound + commandsFound = map (' ':) builtinCommandNames ++ map ('+':) addonsFound unknownCommandsFound = addonsFound \\ knownCommands - adjustline l | " hledger " `isPrefixOf` l = [l] - adjustline (' ':l) | not $ w `elem` commandsFound = [] - where w = takeWhile (not . (`elem` ['|',' '])) l + adjustline l | " hledger " `isPrefixOf` l = [l] + adjustline l@('+':_) | not $ cmd `elem` commandsFound = [] + where + cmd = takeWhile (not . isSpace) l adjustline l = [l] -knownCommands :: [String] -knownCommands = sort $ commandsFromCommandsList commandsList --- | Extract the command names from a commands list like the above: --- the first word (or words separated by |) of lines beginning with a space. -commandsFromCommandsList :: String -> [String] -commandsFromCommandsList s = - concatMap (splitOn "|") [w | ' ':l <- lines s, let w:_ = words l] - - --- The test command, defined here for easy access to other modules' tests. +-- The test command is defined here for easy access to other modules' tests. testmode = hledgerCommandMode - [here| test -Run the unit tests built in to hledger-lib and hledger, -printing results on stdout and exiting with success or failure. - -If a scope argument is provided, only tests in that (exact, case-sensitive) -scope are run. - -If a numeric second argument is provided, it will set the randomness seed, -for any tests which use randomness. - -FLAGS - |] + $(hereFileRelative "Hledger/Cli/Commands/Test.txt") [] [generalflagsgroup3] [] ([], Just $ argsFlag "[TESTPATTERN] [SEED]") --- | See testmode. --- --- Unlike other hledger commands, this one does not operate on the user's Journal. --- For ease of implementation the Journal parameter remains in the type signature. +-- | The test command. +-- Unlike most hledger commands, this one does not read the user's journal. +-- A 'Journal' argument remains in the type signature, but it should +-- not be used (and would raise an error). testcmd :: CliOpts -> Journal -> IO () testcmd opts _undefined = do let args = words' $ query_ $ reportopts_ opts @@ -252,6 +256,7 @@ e <- runEasytests args $ EasyTest.tests [tests_Hledger, tests_Commands] if e then exitFailure else exitSuccess + -- unit tests of hledger command-line executable tests_Commands = tests "Commands" [ @@ -537,7 +542,7 @@ ["assets:cash" `post` usd 4.82 ,"equity:opening balances" `post` usd (-4.82) ], - tpreceding_comment_lines="" + tprecedingcomment="" } , txnTieKnot Transaction { @@ -554,7 +559,7 @@ ["expenses:vacation" `post` usd 179.92 ,"assets:checking" `post` usd (-179.92) ], - tpreceding_comment_lines="" + tprecedingcomment="" } , txnTieKnot Transaction { @@ -571,7 +576,7 @@ ["assets:saving" `post` usd 200 ,"assets:checking" `post` usd (-200) ], - tpreceding_comment_lines="" + tprecedingcomment="" } , txnTieKnot Transaction { @@ -588,7 +593,7 @@ ["expenses:food:dining" `post` usd 4.82 ,"assets:cash" `post` usd (-4.82) ], - tpreceding_comment_lines="" + tprecedingcomment="" } , txnTieKnot Transaction { @@ -605,7 +610,7 @@ ["expenses:phone" `post` usd 95.11 ,"assets:checking" `post` usd (-95.11) ], - tpreceding_comment_lines="" + tprecedingcomment="" } , txnTieKnot Transaction { @@ -622,7 +627,7 @@ ["liabilities:credit cards:discover" `post` usd 80 ,"assets:checking" `post` usd (-80) ], - tpreceding_comment_lines="" + tprecedingcomment="" } ] } diff --git a/Hledger/Cli/Commands/Accounts.hs b/Hledger/Cli/Commands/Accounts.hs --- a/Hledger/Cli/Commands/Accounts.hs +++ b/Hledger/Cli/Commands/Accounts.hs @@ -13,6 +13,7 @@ {-# LANGUAGE MultiWayIf #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ScopedTypeVariables #-} +{-# LANGUAGE TemplateHaskell #-} {-# LANGUAGE CPP #-} module Hledger.Cli.Commands.Accounts ( @@ -33,31 +34,17 @@ -- | Command line options for this command. -accountsmode = (defCommandMode $ ["accounts"] ++ aliases) { - modeHelp = "show account names" `withAliases` aliases - ,modeHelpSuffix = [ - "This command lists account names, either declared with account directives" - ,"(--declared), posted to (--used), or both (default)." - ,"With query arguments, only matched account names and account names" - ,"referenced by matched postings are shown." - ,"It shows a flat list by default. With `--tree`, it uses indentation to" - ,"show the account hierarchy." - ,"In flat mode you can add `--drop N` to omit the first few account name components." - ,"Account names can be depth-clipped with `--depth N` or depth:N." - ] - ,modeGroupFlags = C.Group { - groupUnnamed = [ - flagNone ["declared"] (\opts -> setboolopt "declared" opts) "show account names declared with account directives" - ,flagNone ["used"] (\opts -> setboolopt "used" opts) "show account names referenced by transactions" - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree" - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["a"] +accountsmode = hledgerCommandMode + $(hereFileRelative "Hledger/Cli/Commands/Accounts.txt") + [flagNone ["declared"] (\opts -> setboolopt "declared" opts) "show account names declared with account directives" + ,flagNone ["used"] (\opts -> setboolopt "used" opts) "show account names referenced by transactions" + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree" + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | The accounts command. accounts :: CliOpts -> Journal -> IO () @@ -74,7 +61,7 @@ -- just the acct: part of the query will be reapplied later, after clipping acctq = dbg1 "acctq" $ filterQuery queryIsAcct q depth = dbg1 "depth" $ queryDepth $ filterQuery queryIsDepth q - matcheddeclaredaccts = dbg1 "matcheddeclaredaccts" $ filter (matchesAccount nodepthq) $ jdeclaredaccounts j + matcheddeclaredaccts = dbg1 "matcheddeclaredaccts" $ filter (matchesAccount nodepthq) $ map fst $ jdeclaredaccounts j matchedusedaccts = dbg5 "matchedusedaccts" $ map paccount $ journalPostings $ filterJournalPostings nodepthq j accts = dbg5 "accts to show" $ -- no need to nub/sort, accountTree will if | declared && not used -> matcheddeclaredaccts diff --git a/Hledger/Cli/Commands/Accounts.txt b/Hledger/Cli/Commands/Accounts.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Accounts.txt @@ -0,0 +1,24 @@ +accounts, a +Show account names. + +_FLAGS_ + +This command lists account names, either declared with account +directives (--declared), posted to (--used), or both (the default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +--tree, it uses indentation to show the account hierarchy. In flat mode +you can add --drop N to omit the first few account name components. +Account names can be depth-clipped with depth:N or --depth N or -N. + +Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts diff --git a/Hledger/Cli/Commands/Activity.hs b/Hledger/Cli/Commands/Activity.hs --- a/Hledger/Cli/Commands/Activity.hs +++ b/Hledger/Cli/Commands/Activity.hs @@ -1,3 +1,5 @@ +{-# LANGUAGE TemplateHaskell #-} + {-| Print a bar chart of posting activity per day, or other report interval. @@ -10,7 +12,6 @@ import Data.List import Data.Maybe import Data.Ord -import System.Console.CmdArgs.Explicit import Text.Printf import Hledger @@ -18,17 +19,12 @@ import Prelude hiding (putStr) import Hledger.Utils.UTF8IOCompat (putStr) -activitymode :: Mode RawOpts -activitymode = (defCommandMode $ ["activity"] ++ aliases) { - modeHelp = "show an ascii barchart of posting counts per interval (default: daily)" `withAliases` aliases - ,modeHelpSuffix = [] - ,modeGroupFlags = Group { - groupUnnamed = [] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = [] +activitymode = hledgerCommandMode + $(hereFileRelative "Hledger/Cli/Commands/Activity.txt") + [] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") barchar :: Char barchar = '*' diff --git a/Hledger/Cli/Commands/Activity.txt b/Hledger/Cli/Commands/Activity.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Activity.txt @@ -0,0 +1,16 @@ +activity +Show an ascii barchart of posting counts per interval. + +_FLAGS_ + +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. + +Examples: + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** 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 @@ -4,6 +4,7 @@ {-# OPTIONS_GHC -fno-warn-missing-signatures -fno-warn-unused-do-bind #-} {-# LANGUAGE ScopedTypeVariables, DeriveDataTypeable, RecordWildCards, TypeOperators, FlexibleContexts, OverloadedStrings, PackageImports #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Add ( addmode @@ -46,17 +47,12 @@ import Hledger.Cli.Commands.Register (postingsReportAsText) -addmode = (defCommandMode ["add"]) { - modeHelp = "prompt for transactions and add them to the journal" - ,modeHelpSuffix = ["Defaults come from previous similar transactions; use query patterns to restrict these."] - ,modeGroupFlags = Group { - groupUnnamed = [ - flagNone ["no-new-accounts"] (\opts -> setboolopt "no-new-accounts" opts) "don't allow creating new accounts" - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup2] - } - } +addmode = hledgerCommandMode + $(hereFileRelative "Hledger/Cli/Commands/Add.txt") + [flagNone ["no-new-accounts"] (\opts -> setboolopt "no-new-accounts" opts) "don't allow creating new accounts"] + [generalflagsgroup2] + [] + ([], Just $ argsFlag "[QUERY]") -- | State used while entering transactions. data EntryState = EntryState { diff --git a/Hledger/Cli/Commands/Add.txt b/Hledger/Cli/Commands/Add.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Add.txt @@ -0,0 +1,62 @@ +add +Prompt for transactions and add them to the journal. + +_FLAGS_ + +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 (by + description) recent transaction (filtered by the query, if any) 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]: $ 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 @@ -235,6 +235,7 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ExtendedDefaultRules #-} {-# LANGUAGE ScopedTypeVariables #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Balance ( balancemode @@ -268,36 +269,33 @@ -- | Command line options for this command. -balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don't show the common bal alias - modeHelp = "show accounts and balances" `withAliases` aliases - ,modeGroupFlags = C.Group { - groupUnnamed = [ - flagNone ["change"] (\opts -> setboolopt "change" opts) - "show balance change in each period (default)" - ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) - "show balance change accumulated across periods (in multicolumn reports)" - ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) - "show historical ending balance in each period (includes postings before report start date)\n " - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports)\n " - ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" - ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" - ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" - ,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 to display prettier tables" - ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." - ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" - ,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "with --budget, show unbudgeted accounts also" - ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign" - ] - ++ outputflags - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["b","bal"] +balancemode = hledgerCommandMode + $(hereFileRelative "Hledger/Cli/Commands/Balance.txt") + ([flagNone ["change"] (\opts -> setboolopt "change" opts) + "show balance change in each period (default)" + ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) + "show balance change accumulated across periods (in multicolumn reports)" + ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) + "show historical ending balance in each period (includes postings before report start date)\n " + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports)\n " + ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" + ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" + ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" + ,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 to display prettier tables" + ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." + ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" + ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign" + ,flagNone ["transpose"] (setboolopt "transpose") "transpose rows and columns" + ] + ++ outputflags + ) + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | The balance command, prints a balance report. balance :: CliOpts -> Journal -> IO () @@ -313,9 +311,8 @@ (True, _) -> do -- single or multicolumn budget report reportspan <- reportSpan j ropts - let budgetreport = dbg1 "budgetreport" $ budgetReport ropts assrt showunbudgeted reportspan d j + let budgetreport = dbg1 "budgetreport" $ budgetReport ropts assrt reportspan d j where - showunbudgeted = boolopt "show-unbudgeted" rawopts assrt = not $ ignore_assertions_ $ inputopts_ opts render = case format of "csv" -> const $ error' "Sorry, CSV output is not yet implemented for this kind of report." -- TODO @@ -469,6 +466,7 @@ -- and will include the final totals row unless --no-total is set. multiBalanceReportAsCsv :: ReportOpts -> MultiBalanceReport -> CSV multiBalanceReportAsCsv opts (MultiBalanceReport (colspans, items, (coltotals,tot,avg))) = + maybetranspose $ ("Account" : map showDateSpan colspans ++ (if row_total_ opts then ["Total"] else []) ++ (if average_ opts then ["Average"] else []) @@ -488,7 +486,10 @@ ++ (if row_total_ opts then [tot] else []) ++ (if average_ opts then [avg] else []) )] - + where + maybetranspose | transpose_ opts = transpose + | otherwise = id + -- | Render a multi-column balance report as HTML. multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html () multiBalanceReportAsHtml ropts mbr = @@ -505,7 +506,8 @@ multiBalanceReportHtmlRows :: ReportOpts -> MultiBalanceReport -> (Html (), [Html ()], Maybe (Html ())) multiBalanceReportHtmlRows ropts mbr = let - headingsrow:rest = multiBalanceReportAsCsv ropts mbr + headingsrow:rest | transpose_ ropts = error' "Sorry, --transpose is not supported with HTML output yet" + | otherwise = multiBalanceReportAsCsv ropts mbr (bodyrows, mtotalsrow) | no_total_ ropts = (rest, Nothing) | otherwise = (init rest, Just $ last rest) in @@ -592,6 +594,7 @@ -- | Build a 'Table' from a multi-column balance report. balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount balanceReportAsTable opts (MultiBalanceReport (colspans, items, (coltotals,tot,avg))) = + maybetranspose $ addtotalrow $ Table (T.Group NoLine $ map Header accts) @@ -617,7 +620,9 @@ ++ (if row_total_ opts && not (null coltotals) then [tot] else []) ++ (if average_ opts && not (null coltotals) then [avg] else []) )) - + maybetranspose | transpose_ opts = \(Table rh ch vals) -> Table ch rh (transpose vals) + | otherwise = id + -- | Given a table representing a multi-column balance report (for example, -- made using 'balanceReportAsTable'), render it in a format suitable for -- console output. diff --git a/Hledger/Cli/Commands/Balance.txt b/Hledger/Cli/Commands/Balance.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Balance.txt @@ -0,0 +1,460 @@ +balance, bal, b +Show accounts and their balances. + +_FLAGS_ + +The balance command is hledger's most versatile command. Note, despite +the name, it is not always used for showing real-world account balances; +the more accounting-aware balancesheet and incomestatement may be more +convenient for that. + +By default, it displays all accounts, and each account's change in +balance during the entire period of the journal. Balance changes are +calculated by adding up the postings in each account. You can limit the +postings matched, by a query, to see fewer accounts, changes over a +different time period, changes from only cleared transactions, etc. + +If you include an account's complete history of postings in the report, +the balance change is equivalent to the account's current ending +balance. For a real-world account, typically you won't have all +transactions in the journal; instead you'll have all transactions after +a certain date, and an "opening balances" transaction setting the +correct starting balance on that date. Then the balance command will +show real-world account balances. In some cases the -H/--historical flag +is used to ensure this (more below). + +The balance command can produce several styles of report: + +Classic balance report + +This is the original balance report, as found in Ledger. It usually +looks like this: + +$ 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 + +By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. At each level of the tree, accounts are +sorted by account code if any, then by account name. Or with +-S/--sort-amount, by their balance amount. + +"Boring" accounts, which contain a single interesting subaccount and no +balance of their own, are elided into the following line for more +compact output. (Eg above, the "liabilities" account.) Use --no-elide to +prevent this. + +Account balances are "inclusive" - they include the balances of any +subaccounts. + +Accounts which have zero balance (and no non-zero subaccounts) are +omitted. Use -E/--empty to show them. + +A final total is displayed by default; use -N/--no-total to suppress it, +eg: + +$ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + +Customising the classic balance report + +You can customise the layout of classic balance reports with +--format FMT: + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. It may contain any suitable text, with +data fields interpolated like so: + +%[MIN][.MAX](FIELDNAME) + +- MIN pads with spaces to at least this width (optional) +- MAX truncates at this width (optional) +- FIELDNAME must be enclosed in parentheses, and can be one of: + + - depth_spacer - a number of spaces equal to the account's depth, + or if MIN is specified, MIN * depth spaces. + - account - the account's name + - total - the account's balance/posted total, right justified + +Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + +- %_ - render on multiple lines, bottom-aligned (the default) +- %^ - render on multiple lines, top-aligned +- %, - render on one line, comma-separated + +There are some quirks. Eg in one-line mode, %(depth_spacer) has no +effect, instead %(account) has indentation built in. Experimentation may +be needed to get pleasing results. + +Some example formats: + +- %(total) - the account's total +- %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters +- %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line +- %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + +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 + +Flat mode + +To see a flat list instead of the default hierarchical display, use +--flat. In this mode, accounts (unless depth-clipped) show their full +names and "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 or depth:N or just -N, balance reports show accounts only +to the specified numeric depth. This is very useful to summarise a +complex set of accounts and get an overview. + +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + +Flat-mode balance reports, which normally show exclusive balances, show +inclusive balances at the depth limit. + +Multicolumn balance report + +Multicolumn or tabular balance reports are a very useful hledger +feature, and usually the preferred style. They share many of the above +features, but they show the report as a table, with columns representing +time periods. This mode is activated by providing a reporting interval. + +There are three types of multicolumn 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 + +Multicolumn 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). With --budget, --empty also shows unbudgeted accounts. + +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 + +Limitations: + +In multicolumn reports the -V/--value flag uses the market price on the +report end date, for all columns (not the price on each column's end +date). + +Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. + +Budget report + +With --budget, extra columns are displayed showing budget goals for each +account and period, if any. Budget goals are defined by periodic +transactions. This is very useful for comparing planned and actual +income, expenses, time usage, etc. --budget is most often combined with +a report interval. + +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 report: + +$ hledger balance -M --budget +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + +By default, only accounts with budget goals during the report period are +shown. In the example above, transactions in expenses:gifts and +expenses:supplies are counted towards expenses budget, but accounts +expenses:gifts and expenses:supplies are not shown, as they don't have +any budgets. + +You can use --empty shows unbudgeted accounts as well: + +$ hledger balance -M --budget --empty +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + +You can roll over unspent budgets to next period with --cumulative: + +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + +Note, the -S/--sort-amount flag is not yet fully supported with +--budget. + +For more examples, see Budgeting and Forecasting. + +Nested budgets + +You can add budgets to any account in your account hierarchy. If you +have budgets on both parent account and some of its children, then +budget(s) of the child account(s) would be added to the budget of their +parent, much like account balances behave. + +In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. + +To illustrate this, consider the following budget: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both expenses:personal and expenses is $1100. + +Transactions in expenses:personal:electronics will be counted both +towards its $100 budget and $1100 of expenses:personal , and +transactions in any other subaccount of expenses:personal would be +counted towards only towards the budget of expenses:personal. + +For example, let's consider these transactions: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + +2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + +2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + +2019/01/03 Flowers + expenses:personal $30.00 + liabilities + +As you can see, we have transactions in +expenses:personal:electronics:upgrades and +expenses:personal:train tickets, and since both of these accounts are +without explicitly defined budget, these transactions would be counted +towards budgets of expenses:personal:electronics and expenses:personal +accordingly: + +$ hledger balance --budget -M +Budget performance in 2019/01: + + || Jan +===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++------------------------------- + || 0 [ 0] + +And with --empty, we can get a better picture of budget allocation and +consumption: + +$ hledger balance --budget -M --empty +Budget performance in 2019/01: + + || Jan +========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++------------------------------- + || 0 [ 0] + +Output format + +The balance command supports output destination and output format +selection. diff --git a/Hledger/Cli/Commands/Balancesheet.hs b/Hledger/Cli/Commands/Balancesheet.hs --- a/Hledger/Cli/Commands/Balancesheet.hs +++ b/Hledger/Cli/Commands/Balancesheet.hs @@ -1,4 +1,5 @@ -{-# LANGUAGE QuasiQuotes, RecordWildCards #-} +{-# LANGUAGE RecordWildCards #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @balancesheet@ command prints a simple balance sheet. @@ -10,7 +11,6 @@ ,balancesheet ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -18,18 +18,7 @@ import Hledger.Cli.CompoundBalanceCommand balancesheetSpec = CompoundBalanceCommandSpec { - cbcname = "balancesheet", - cbcaliases = ["bs"], - cbchelp = [here| -This command displays a simple balance sheet, showing historical ending -balances of asset and liability accounts (ignoring any report begin date). -It assumes that these accounts are under a top-level `asset` or `liability` -account (case insensitive, plural forms also allowed). - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Balancesheet.txt")), cbctitle = "Balance Sheet", cbcqueries = [ CBCSubreportSpec{ diff --git a/Hledger/Cli/Commands/Balancesheet.txt b/Hledger/Cli/Commands/Balancesheet.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Balancesheet.txt @@ -0,0 +1,41 @@ +balancesheet, bs +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). It assumes that these accounts are under a top-level asset or +liability account (case insensitive, plural forms also allowed). + +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). + +_FLAGS_ + +Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + +With a reporting interval, multiple columns will be shown, one for each +report period. As with multicolumn balance reports, you can alter the +report mode with --change/--cumulative/--historical. Normally +balancesheet shows historical ending balances, which is what you need +for a balance sheet; note this means it ignores report begin dates. + +This command also supports output destination and output format +selection. diff --git a/Hledger/Cli/Commands/Balancesheetequity.hs b/Hledger/Cli/Commands/Balancesheetequity.hs --- a/Hledger/Cli/Commands/Balancesheetequity.hs +++ b/Hledger/Cli/Commands/Balancesheetequity.hs @@ -1,4 +1,5 @@ {-# LANGUAGE QuasiQuotes, RecordWildCards #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @balancesheetequity@ command prints a simple balance sheet. @@ -10,7 +11,6 @@ ,balancesheetequity ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -18,17 +18,7 @@ import Hledger.Cli.CompoundBalanceCommand balancesheetequitySpec = CompoundBalanceCommandSpec { - cbcname = "balancesheetequity", - cbcaliases = ["bse"], - cbchelp = [here|This command displays a simple balance sheet, showing historical ending -balances of asset, liability and equity accounts (ignoring any report begin date). -It assumes that these accounts are under a top-level `asset`, `liability` and `equity` -account (plural forms also allowed). - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Balancesheetequity.txt")), cbctitle = "Balance Sheet With Equity", cbcqueries = [ CBCSubreportSpec{ diff --git a/Hledger/Cli/Commands/Balancesheetequity.txt b/Hledger/Cli/Commands/Balancesheetequity.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Balancesheetequity.txt @@ -0,0 +1,31 @@ +balancesheetequity, bse +Just like balancesheet, but also reports Equity (which it assumes is +under a top-level equity account). + +_FLAGS_ + +Example: + +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 diff --git a/Hledger/Cli/Commands/Cashflow.hs b/Hledger/Cli/Commands/Cashflow.hs --- a/Hledger/Cli/Commands/Cashflow.hs +++ b/Hledger/Cli/Commands/Cashflow.hs @@ -1,4 +1,5 @@ {-# LANGUAGE QuasiQuotes, RecordWildCards #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @cashflow@ command prints a simplified cashflow statement. It just @@ -13,7 +14,6 @@ ,cashflow ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -21,18 +21,7 @@ import Hledger.Cli.CompoundBalanceCommand cashflowSpec = CompoundBalanceCommandSpec { - cbcname = "cashflow", - cbcaliases = ["cf"], - cbchelp = [here| -This command displays a simple cashflow statement, showing changes -in "cash" accounts. It assumes that these accounts are under a top-level -`asset` account (case insensitive, plural forms also allowed) and do not -contain `receivable` or `A/R` in their name. - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Cashflow.txt")), cbctitle = "Cashflow Statement", cbcqueries = [ CBCSubreportSpec{ diff --git a/Hledger/Cli/Commands/Cashflow.txt b/Hledger/Cli/Commands/Cashflow.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Cashflow.txt @@ -0,0 +1,33 @@ +cashflow, cf +This command displays a simple cashflow statement, showing changes in +"cash" accounts. It assumes that these accounts are under a top-level +asset account (case insensitive, plural forms also allowed) and do not +contain receivable or A/R in their name. Note this report shows all +account balances with normal positive sign (like conventional financial +statements, unlike balance/print/register) (experimental). + +_FLAGS_ + +Example: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + +With a reporting interval, multiple columns will be shown, one for each +report period. Normally cashflow shows changes in assets per period, +though as with multicolumn balance reports you can alter the report mode +with --change/--cumulative/--historical. + +This command also supports output destination and output format +selection. diff --git a/Hledger/Cli/Commands/Checkdates.hs b/Hledger/Cli/Commands/Checkdates.hs --- a/Hledger/Cli/Commands/Checkdates.hs +++ b/Hledger/Cli/Commands/Checkdates.hs @@ -1,27 +1,19 @@ -{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE NoOverloadedStrings #-} -- prevent trouble if turned on in ghci +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Checkdates ( checkdatesmode ,checkdates ) where -import Data.String.Here import Hledger import Hledger.Cli.CliOptions import System.Console.CmdArgs.Explicit import Text.Printf --- checkdatesmode :: Mode RawOpts +checkdatesmode :: Mode RawOpts checkdatesmode = hledgerCommandMode - [here| check-dates -Check that transactions are sorted by increasing date. -With --date2, checks secondary dates instead. -With --strict, dates must also be unique. -With a query, only matched transactions' dates are checked. -Reads the default journal file, or another specified with -f. -FLAGS - |] + ($(hereFileRelative "Hledger/Cli/Commands/Checkdates.txt")) [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] [generalflagsgroup1] [] diff --git a/Hledger/Cli/Commands/Checkdates.txt b/Hledger/Cli/Commands/Checkdates.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Checkdates.txt @@ -0,0 +1,7 @@ +check-dates +Check that transactions are sorted by increasing date. With --date2, +checks secondary dates instead. With --strict, dates must also be +unique. With a query, only matched transactions' dates are checked. +Reads the default journal file, or another specified with -f. + +_FLAGS_ diff --git a/Hledger/Cli/Commands/Checkdupes.hs b/Hledger/Cli/Commands/Checkdupes.hs --- a/Hledger/Cli/Commands/Checkdupes.hs +++ b/Hledger/Cli/Commands/Checkdupes.hs @@ -1,4 +1,4 @@ -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Checkdupes ( checkdupesmode @@ -8,7 +8,6 @@ import Data.Function import Data.List -import Data.String.Here import qualified Data.Text as T import Hledger import Hledger.Cli.CliOptions @@ -17,12 +16,7 @@ checkdupesmode :: Mode RawOpts checkdupesmode = hledgerCommandMode - [here| check-dupes -Reports account names having the same leaf but different prefixes. -In other words, two or more leaves that are categorized differently. -Reads the default journal file, or another specified as an argument. -An example: http://stefanorodighiero.net/software/hledger-dupes.html - |] + ($(hereFileRelative "Hledger/Cli/Commands/Checkdupes.txt")) [] [generalflagsgroup1] [] diff --git a/Hledger/Cli/Commands/Checkdupes.txt b/Hledger/Cli/Commands/Checkdupes.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Checkdupes.txt @@ -0,0 +1,8 @@ +check-dupes +Reports account names having the same leaf but different prefixes. In +other words, two or more leaves that are categorized differently. Reads +the default journal file, or another specified as an argument. + +_FLAGS_ + +An example: http://stefanorodighiero.net/software/hledger-dupes.html diff --git a/Hledger/Cli/Commands/Close.hs b/Hledger/Cli/Commands/Close.hs --- a/Hledger/Cli/Commands/Close.hs +++ b/Hledger/Cli/Commands/Close.hs @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Close ( closemode @@ -9,60 +9,14 @@ import Control.Monad (when) import Data.Maybe -import Data.String.Here import Data.Time.Calendar +import System.Console.CmdArgs.Explicit as C + import Hledger import Hledger.Cli.CliOptions -import System.Console.CmdArgs.Explicit as C closemode = hledgerCommandMode - [here| close equity -Print a "closing balances" transaction that brings all accounts (or with -query arguments, just the matched accounts) to a zero (historical) balance, -followed by an opposite "opening balances" transaction that restores the -balances from zero. - -FLAGS - -The opening transaction is useful to carry over asset/liability balances -if you choose to start a new journal file, eg yearly. The closing transaction -can be a useful complement, allowing you to optionally include old files -(for more history) without disturbing the asset/liability balances -(since the closing/opening pairs cancel out). - -This command may also be useful for closing out expense/income accounts -for a period (ie "closing the books" in accounting). - -Both transactions include balance assertions for the closed/reopened accounts. -You probably shouldn't use status or realness queries (eg -C or -R) with this -command, or the balance assertions will require that query to pass. - -By default, the closing transaction is dated yesterday, with balances -calculated as of end of yesterday, and the opening transaction is dated today. -To close on some other date, use: `hledger close -e OPENINGDATE ...`. -(-p or date: can also be used, the begin date is ignored.) - -You can chose to print just one of the transactions with `--opening` -or `--closing`. - -For example, carrying asset/liability balances into a new file for 2018: -``` -$ hledger close -f 2017.journal -e 2018/1/1 ^assets ^liab >>2017.journal -# cut & paste the opening transaction from 2017.journal to a new 2018.journal -# now: -$ hledger bs -f 2018.journal # correct balances -$ hledger bs -f 2018.journal -f 2017.journal # still correct -$ hledger bs -f 2017.journal not:desc:closing # must exclude closing txn -``` - -Transactions spanning the closing date may complicate matters. Eg, if -closing at end of 2017: -``` -2017/12/31 - expenses:food 1 - assets:bank:checking -1 ; date:2018/1/1 -``` - |] + $(hereFileRelative "Hledger/Cli/Commands/Close.txt") [flagNone ["opening"] (\opts -> setboolopt "opening" opts) "show just opening transaction" ,flagNone ["closing"] (\opts -> setboolopt "closing" opts) "show just closing transaction" ] @@ -83,22 +37,30 @@ closingdate = addDays (-1) openingdate (acctbals,_) = balanceReportFromMultiBalanceReport ropts_ q j balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmountSquashPricesForDisplay b) acctbals - ps = [posting{paccount=a - ,pamount=mixed [b] - ,pbalanceassertion=Just assertion{ baamount=b } - } - |(a,_,_,mb) <- acctbals - ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb - ] - ++ [posting{paccount="equity:opening balances", pamount=balancingamt}] - nps = [posting{paccount=a - ,pamount=mixed [negate b] - ,pbalanceassertion=Just assertion{ baamount=b{aquantity=0} } - } - |(a,_,_,mb) <- acctbals - ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb - ] - ++ [posting{paccount="equity:closing balances", pamount=negate balancingamt}] - when closing $ putStr $ showTransaction (nulltransaction{tdate=closingdate, tdescription="closing balances", tpostings=nps}) - when opening $ putStr $ showTransaction (nulltransaction{tdate=openingdate, tdescription="opening balances", tpostings=ps}) + + -- since balance assertion amounts are required to be exact, the + -- amounts in opening/closing transactions should be too (#941) + -- setprec = setFullPrecision + setprec = setMinimalPrecision + -- balance assertion amounts will be unpriced, cf #824 + closingps = [posting{paccount=a + ,pamount=mixed [setprec $ negate b] + ,pbalanceassertion=Just assertion{baamount=setprec b{aquantity=0, aprice=NoPrice}} + } + | (a,_,_,mb) <- acctbals + , b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb + ] + ++ [posting{paccount="equity:closing balances", pamount=negate balancingamt}] + + openingps = [posting{paccount=a + ,pamount=mixed [setprec b] + ,pbalanceassertion=Just assertion{baamount=setprec b{aprice=NoPrice}} + } + | (a,_,_,mb) <- acctbals + , b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb + ] + ++ [posting{paccount="equity:opening balances", pamount=balancingamt}] + + when closing $ putStr $ showTransaction (nulltransaction{tdate=closingdate, tdescription="closing balances", tpostings=closingps}) + when opening $ putStr $ showTransaction (nulltransaction{tdate=openingdate, tdescription="opening balances", tpostings=openingps}) diff --git a/Hledger/Cli/Commands/Close.txt b/Hledger/Cli/Commands/Close.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Close.txt @@ -0,0 +1,78 @@ +close, equity +Prints a "closing balances" transaction and an "opening balances" +transaction that bring account balances to and from zero, respectively. +Useful for bringing asset/liability balances forward into a new journal +file, or for closing out revenues/expenses to retained earnings at the +end of a period. + +_FLAGS_ + +The closing transaction transfers balances to "equity:closing balances". +The opening transaction transfers balances from "equity:opening +balances". You can chose to print just one of the transactions by using +the --opening or --closing flag. + +If you split your journal files by time (eg yearly), you will typically +run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. This makes the files self contained, +so that correct balances are reported no matter which of them are +loaded. Ie, if you load just one file, the balances are initialised +correctly; or if you load several files, the redundant closing/opening +transactions cancel each other out. (They will show up in print or +register reports; you can exclude them with a query like +not:desc:'(opening|closing) balances'.) + +If you're running a business, you might also use this command to "close +the books" at the end of an accounting period, transferring income +statement account balances to retained earnings. (You may want to change +the equity account name to something like "equity:retained earnings".) + +By default, the closing transaction is dated yesterday, the balances are +calculated as of end of yesterday, and the opening transaction is dated +today. To close on some other date, use: hledger close -e OPENINGDATE. +Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also +use -p or date:PERIOD (any starting date is ignored). + +Both transactions will include balance assertions for the +closed/reopened accounts. You probably shouldn't use status or realness +filters (like -C or -R or status:) with this command, or the generated +balance assertions will depend on these flags. Likewise, if you run this +command with --auto, the balance assertions will probably always require +--auto. + +Examples: + +Carrying asset/liability balances into a new file for 2019, all from +command line: + +_Warning: we use >> here to append; be careful not to type a single > +which would wipe your journal!_ + +$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + +Now: + +$ hledger bs -f 2019.journal # one file - balances are correct +$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct +$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + +Transactions spanning the closing date can complicate matters, breaking +balance assertions: + +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + +Here's one way to resolve that: + +; in 2018.journal: +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + +; in 2019.journal: +2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking diff --git a/Hledger/Cli/Commands/Files.hs b/Hledger/Cli/Commands/Files.hs --- a/Hledger/Cli/Commands/Files.hs +++ b/Hledger/Cli/Commands/Files.hs @@ -5,6 +5,7 @@ -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Files ( filesmode @@ -12,9 +13,7 @@ ) where import Data.List --- import Data.Text (Text) import Safe -import System.Console.CmdArgs.Explicit as C import Hledger import Prelude hiding (putStrLn) @@ -23,19 +22,12 @@ -- | Command line options for this command. -filesmode = (defCommandMode $ ["files"] ) { - modeHelp = "show names of included files" - ,modeHelpSuffix = [ - "This command lists names of all files included in the parsed journal(s)." - ,"With REGEX argument will list only files matching regular expression (case sensitive)." - ] - ,modeGroupFlags = C.Group { - groupUnnamed = [] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup2] - } - ,modeArgs= ([], Just $ argsFlag "[REGEX]") - } +filesmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Files.txt")) + [] + [generalflagsgroup2] + [] + ([], Just $ argsFlag "[REGEX]") -- | The files command. files :: CliOpts -> Journal -> IO () diff --git a/Hledger/Cli/Commands/Files.txt b/Hledger/Cli/Commands/Files.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Files.txt @@ -0,0 +1,5 @@ +files +List all files included in the journal. With a REGEX argument, only file +names matching the regular expression (case sensitive) are shown. + +_FLAGS_ diff --git a/Hledger/Cli/Commands/Help.hs b/Hledger/Cli/Commands/Help.hs --- a/Hledger/Cli/Commands/Help.hs +++ b/Hledger/Cli/Commands/Help.hs @@ -6,8 +6,9 @@ --TODO rename manuals --TODO substring matching -{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE PackageImports #-} +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Help ( @@ -19,36 +20,32 @@ import Prelude () import "base-compat-batteries" Prelude.Compat import Data.Char +import Data.String.Here import Data.List import Data.Maybe -import Data.String.Here import Safe import System.Console.CmdArgs.Explicit import System.Environment import System.IO +import Hledger.Utils (hereFileRelative) import Hledger.Data.RawOptions import Hledger.Data.Types import Hledger.Cli.CliOptions import Hledger.Cli.DocFiles --import Hledger.Utils.Debug -helpmode = (defCommandMode $ ["help"] ++ aliases) { - modeHelp = "show any of the hledger manuals, choosing the most suitable viewer (info, man, a pager, or stdout). With no argument, list the manuals." `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - flagNone ["info"] (setboolopt "info") "show the manual with info" - ,flagNone ["man"] (setboolopt "man") "show the manual with man" - ,flagNone ["pager"] (setboolopt "pager") "show the manual with $PAGER or less" - ,flagNone ["cat"] (setboolopt "cat") "show the manual on stdout" - ,flagNone ["help","h"] (setboolopt "help") "show this help" - ] - ,groupHidden = [] - ,groupNamed = [] - } - ,modeArgs = ([], Just $ argsFlag "[MANUAL]") -} - where aliases = [] +helpmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Help.txt")) + [flagNone ["info"] (setboolopt "info") "show the manual with info" + ,flagNone ["man"] (setboolopt "man") "show the manual with man" + ,flagNone ["pager"] (setboolopt "pager") "show the manual with $PAGER or less" + ,flagNone ["cat"] (setboolopt "cat") "show the manual on stdout" + ,flagNone ["help","h"] (setboolopt "help") "show this help" + ] + [] + [] + ([], Just $ argsFlag "[MANUAL]") -- | List or display one of the hledger manuals in various formats. -- You can select a docs viewer with one of the `--info`, `--man`, `--pager`, `--cat` flags. diff --git a/Hledger/Cli/Commands/Help.txt b/Hledger/Cli/Commands/Help.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Help.txt @@ -0,0 +1,35 @@ +help +Show any of the hledger manuals. + +_FLAGS_ + +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. + +Examples: + +$ 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 +... 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 @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Import ( importmode @@ -10,7 +10,6 @@ import Control.Monad import Data.List import Data.Ord -import Data.String.Here import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Add (journalAddTransaction) @@ -19,18 +18,7 @@ import Text.Printf importmode = hledgerCommandMode - [here| import -Read new transactions added to each FILE since last run, and add them to -the main journal file. Or with --dry-run, just print the transactions -that would be added. - -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) - -FLAGS - |] + ($(hereFileRelative "Hledger/Cli/Commands/Import.txt")) [flagNone ["dry-run"] (\opts -> setboolopt "dry-run" opts) "just show the transactions to be imported"] [generalflagsgroup1] [] @@ -49,7 +37,7 @@ Left e -> error' e Right newj -> case sortBy (comparing tdate) $ jtxns newj of - [] -> putStrLn "no new transactions" + [] -> return () newts | dryrun -> do printf "; would import %d new transactions:\n\n" (length newts) -- TODO how to force output here ? diff --git a/Hledger/Cli/Commands/Import.txt b/Hledger/Cli/Commands/Import.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Import.txt @@ -0,0 +1,19 @@ +import +Read new transactions added to each FILE since last run, and add them to +the main journal file. Or with --dry-run, just print the transactions +that would be added. + +_FLAGS_ + +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 diff --git a/Hledger/Cli/Commands/Incomestatement.hs b/Hledger/Cli/Commands/Incomestatement.hs --- a/Hledger/Cli/Commands/Incomestatement.hs +++ b/Hledger/Cli/Commands/Incomestatement.hs @@ -10,7 +10,6 @@ ,incomestatement ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -18,18 +17,7 @@ import Hledger.Cli.CompoundBalanceCommand incomestatementSpec = CompoundBalanceCommandSpec { - cbcname = "incomestatement", - cbcaliases = ["is"], - cbchelp = [here| -This command displays a simple income statement, showing revenues -and expenses during a period. It assumes that these accounts are under a -top-level `revenue` or `income` or `expense` account (case insensitive, -plural forms also allowed). - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Incomestatement.txt")), cbctitle = "Income Statement", cbcqueries = [ CBCSubreportSpec{ diff --git a/Hledger/Cli/Commands/Incomestatement.txt b/Hledger/Cli/Commands/Incomestatement.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Incomestatement.txt @@ -0,0 +1,42 @@ +incomestatement, is +This command displays a simple income statement, showing revenues and +expenses during a period. It assumes that these accounts are under a +top-level revenue or income or expense account (case insensitive, plural +forms also allowed). Note this report shows all account balances with +normal positive sign (like conventional financial statements, unlike +balance/print/register) (experimental). + +_FLAGS_ + +This command displays a simple income statement. It currently assumes +that you have top-level accounts named income (or revenue) and expense +(plural forms also allowed.) + +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 + +With a reporting interval, multiple columns will be shown, one for each +report period. Normally incomestatement shows revenues/expenses per +period, though as with multicolumn balance reports you can alter the +report mode with --change/--cumulative/--historical. + +This command also supports output destination and output format +selection. diff --git a/Hledger/Cli/Commands/Prices.hs b/Hledger/Cli/Commands/Prices.hs --- a/Hledger/Cli/Commands/Prices.hs +++ b/Hledger/Cli/Commands/Prices.hs @@ -1,4 +1,4 @@ -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Prices ( pricesmode @@ -8,7 +8,6 @@ import Data.Maybe import Data.List -import Data.String.Here import qualified Data.Text as T import Data.Time import Hledger @@ -16,12 +15,7 @@ import System.Console.CmdArgs.Explicit pricesmode = hledgerCommandMode - [here| prices -Print market price directives from the journal. -With --costs, also print synthetic market prices based on transaction prices. -With --inverted-costs, also print inverse prices based on transaction prices. -Prices (and postings providing prices) can be filtered by a query. - |] + ($(hereFileRelative "Hledger/Cli/Commands/Prices.txt")) [flagNone ["costs"] (setboolopt "costs") "print transaction prices from postings" ,flagNone ["inverted-costs"] (setboolopt "inverted-costs") "print transaction inverted prices from postings also"] [generalflagsgroup1] diff --git a/Hledger/Cli/Commands/Prices.txt b/Hledger/Cli/Commands/Prices.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Prices.txt @@ -0,0 +1,7 @@ +prices +Print market price directives from the journal. With --costs, also print +synthetic market prices based on transaction prices. With +--inverted-costs, also print inverse prices based on transaction prices. +Prices (and postings providing prices) can be filtered by a query. + +_FLAGS_ 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 @@ -5,6 +5,7 @@ -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Print ( printmode @@ -25,24 +26,19 @@ import Hledger.Cli.Commands.Add ( transactionsSimilarTo ) -printmode = (defCommandMode $ ["print"] ++ aliases) { - modeHelp = "show transaction journal entries, sorted by date. With --date2, sort by secondary date instead." `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - let arg = "STR" in - flagReq ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg - ("show the transaction whose description is most similar to "++arg++", and is most recent") - ,flagNone ["explicit","x"] (setboolopt "explicit") - "show all amounts explicitly" - ,flagNone ["new"] (setboolopt "new") - "show only newer-dated transactions added in each file since last run" - ] - ++ outputflags - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["p","txns"] +printmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Print.txt")) + [let arg = "STR" in + flagReq ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg + ("show the transaction whose description is most similar to "++arg++", and is most recent") + ,flagNone ["explicit","x"] (setboolopt "explicit") + "show all amounts explicitly" + ,flagNone ["new"] (setboolopt "new") + "show only newer-dated transactions added in each file since last run" + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | Print journal transactions in standard format. print' :: CliOpts -> Journal -> IO () diff --git a/Hledger/Cli/Commands/Print.txt b/Hledger/Cli/Commands/Print.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Print.txt @@ -0,0 +1,96 @@ +print, txns, p +Show transaction journal entries, sorted by date. + +_FLAGS_ + +The print command displays full journal entries (transactions) from the +journal file in date order, tidily formatted. With --date2, transactions +are sorted by secondary date instead. + +print's output is always a valid hledger journal. +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments + +$ 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 + +Normally, the journal entry's explicit or implicit amount style is +preserved. Ie when an amount is omitted in the journal, it will be +omitted in the output. You can use the -x/--explicit flag to make all +amounts explicit, which can be useful for troubleshooting or for making +your journal more readable and robust against data entry errors. Note, +-x will cause postings with a multi-commodity amount (these can arise +when a multi-commodity transaction has an implicit amount) will be split +into multiple single-commodity postings, for valid journal output. + +With -B/--cost, amounts with transaction prices are converted to cost +using that price. This can be used for troubleshooting. + +With -m/--match and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there is +no similar-enough match, no transaction will be shown. + +With --new, for each FILE being read, hledger reads (and writes) a +special state file (.latest.FILE in the same directory), containing the +latest transaction date(s) that were seen last time FILE was read. When +this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. This is useful for +ignoring already-seen entries in import data, such as downloaded CSV +files. Eg: + +$ hledger -f bank1.csv print --new +# shows transactions added since last print --new on this file + +This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. See also the import command. + +This command also supports output destination and output format +selection. Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + +- There is one CSV record per posting, with the parent transaction's + fields repeated. +- The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) +- The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. +- The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) diff --git a/Hledger/Cli/Commands/Printunique.hs b/Hledger/Cli/Commands/Printunique.hs --- a/Hledger/Cli/Commands/Printunique.hs +++ b/Hledger/Cli/Commands/Printunique.hs @@ -1,6 +1,4 @@ -{-# LANGUAGE QuasiQuotes #-} - -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Printunique ( printuniquemode @@ -10,30 +8,12 @@ import Data.List import Data.Ord -import Data.String.Here import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Print printuniquemode = hledgerCommandMode - [here| print-unique -Print transactions which do not reuse an already-seen description. - -FLAGS - -Example: -```shell -$ cat unique.journal -1/1 test - (acct:one) 1 -2/2 test - (acct:two) 2 -$ LEDGER_FILE=unique.journal hledger print-unique -(-f option not supported) -2015/01/01 test - (acct:one) 1 -``` - |] + ($(hereFileRelative "Hledger/Cli/Commands/Printunique.txt")) [] [generalflagsgroup1] [] diff --git a/Hledger/Cli/Commands/Printunique.txt b/Hledger/Cli/Commands/Printunique.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Printunique.txt @@ -0,0 +1,16 @@ +print-unique +Print transactions which do not reuse an already-seen description. + +_FLAGS_ + +Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 diff --git a/Hledger/Cli/Commands/Register.hs b/Hledger/Cli/Commands/Register.hs --- a/Hledger/Cli/Commands/Register.hs +++ b/Hledger/Cli/Commands/Register.hs @@ -5,6 +5,7 @@ -} {-# LANGUAGE CPP, OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Register ( registermode @@ -26,33 +27,28 @@ import Hledger.Cli.CliOptions import Hledger.Cli.Utils -registermode = (defCommandMode $ ["register"] ++ aliases) { - modeHelp = "show postings and running total. With --date2, show and sort by secondary date instead." `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - flagNone ["cumulative"] (\opts -> setboolopt "change" opts) - "show running total from report start date (default)" - ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) - "show historical running total/balance (includes postings before report start date)\n " - ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) - "show running average of posting amounts instead of total (implies --empty)" - ,flagNone ["related","r"] (\opts -> setboolopt "related" opts) "show postings' siblings instead" - ,flagReq ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N" - ("set output width (default: " ++ +registermode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Register.txt")) + [flagNone ["cumulative"] (\opts -> setboolopt "change" opts) + "show running total from report start date (default)" + ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) + "show historical running total/balance (includes postings before report start date)\n " + ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) + "show running average of posting amounts instead of total (implies --empty)" + ,flagNone ["related","r"] (\opts -> setboolopt "related" opts) "show postings' siblings instead" + ,flagReq ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N" + ("set output width (default: " ++ #ifdef mingw32_HOST_OS - show defaultWidth + show defaultWidth #else - "terminal width" + "terminal width" #endif - ++ " or $COLUMNS). -wN,M sets description width as well." - ) - ] - ++ outputflags - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["r","reg"] + ++ " or $COLUMNS). -wN,M sets description width as well." + ) + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | Print a (posting) register report. register :: CliOpts -> Journal -> IO () diff --git a/Hledger/Cli/Commands/Register.txt b/Hledger/Cli/Commands/Register.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Register.txt @@ -0,0 +1,100 @@ +register, reg, r +Show postings and their running total. + +_FLAGS_ + +The register command displays postings in date order, 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 + +With --date2, it shows and sorts by secondary date instead. + +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 (won't display correctly in --help): + +<--------------------------------- 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, & description width 40 + +This command also supports output destination and output format +selection. diff --git a/Hledger/Cli/Commands/Registermatch.hs b/Hledger/Cli/Commands/Registermatch.hs --- a/Hledger/Cli/Commands/Registermatch.hs +++ b/Hledger/Cli/Commands/Registermatch.hs @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Registermatch ( registermatchmode @@ -9,24 +9,17 @@ import Data.Char (toUpper) import Data.List -import Data.String.Here import qualified Data.Text as T import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Register registermatchmode = hledgerCommandMode - [here| register-match -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. -If there are multiple equally good matches, it shows the most recent. -Query options (options, not arguments) can be used to restrict the search space. -Helps ledger-autosync detect already-seen transactions when importing. - |] + ($(hereFileRelative "Hledger/Cli/Commands/Registermatch.txt")) [] [generalflagsgroup1] [] - ([], Nothing) + ([], Just $ argsFlag "[QUERY]") registermatch :: CliOpts -> Journal -> IO () registermatch opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do diff --git a/Hledger/Cli/Commands/Registermatch.txt b/Hledger/Cli/Commands/Registermatch.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Registermatch.txt @@ -0,0 +1,8 @@ +register-match +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. If there are multiple equally good +matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing. + +_FLAGS_ diff --git a/Hledger/Cli/Commands/Rewrite.hs b/Hledger/Cli/Commands/Rewrite.hs --- a/Hledger/Cli/Commands/Rewrite.hs +++ b/Hledger/Cli/Commands/Rewrite.hs @@ -1,5 +1,6 @@ -{-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns, QuasiQuotes #-} +{-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns #-} {-# LANGUAGE CPP #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Rewrite ( rewritemode @@ -12,7 +13,6 @@ #endif import Data.Functor.Identity import Data.List (sortOn, foldl') -import Data.String.Here import qualified Data.Text as T import Hledger import Hledger.Cli.CliOptions @@ -23,146 +23,7 @@ import qualified Data.Algorithm.Diff as D rewritemode = hledgerCommandMode - [here| rewrite -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - -FLAGS - -This is a start at a generic rewriter of transaction entries. -It reads the default journal and prints the transactions, like print, -but adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing transaction's first posting amount. - -Examples: -``` -hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -hledger-rewrite.hs -f rewrites.hledger -``` -rewrites.hledger may consist of entries like: -``` -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery -``` -Note the single quotes to protect the dollar sign from bash, -and the two spaces between account and amount. - -More: - -```shell -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' -``` - -Argument for `--add-posting` option is a usual posting of transaction with an -exception for amount specification. More precisely, you can use `'*'` (star -symbol) before the amount to indicate that that this is a factor for an -amount of original matched posting. If the amount includes a commodity name, -the new posting amount will be in the new commodity; otherwise, it will be in -the matched posting amount's commodity. - -#### Re-write rules in a file - -During the run this tool will execute so called -["Automated Transactions"](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions) -found in any journal it process. I.e instead of specifying this operations in -command line you can put them in a journal file. - -```shell -$ rewrite-rules.journal -``` - -Make contents look like this: - -```journal -= ^income - (liabilities:tax) *.33 - -= expenses:gifts - budget:gifts *-1 - assets:budget *1 -``` - -Note that `'='` (equality symbol) that is used instead of date in transactions -you usually write. It indicates the query by which you want to match the -posting to add new ones. - -```shell -$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal -``` - -This is something similar to the commands pipeline: - -```shell -$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ - | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ - --add-posting 'assets:budget *1' \ - > rewritten-tidy-output.journal -``` - -It is important to understand that relative order of such entries in journal is -important. You can re-use result of previously added postings. - -#### Diff output format - -To use this tool for batch modification of your journal files you may find -useful output in form of unified diff. - -```shell -$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' -``` - -Output might look like: - -```diff ---- /tmp/examples/sample.journal -+++ /tmp/examples/sample.journal -@@ -18,3 +18,4 @@ - 2008/01/01 income -- assets:bank:checking $1 -+ assets:bank:checking $1 - income:salary -+ (liabilities:tax) 0 -@@ -22,3 +23,4 @@ - 2008/06/01 gift -- assets:bank:checking $1 -+ assets:bank:checking $1 - income:gifts -+ (liabilities:tax) 0 -``` - -If you'll pass this through `patch` tool you'll get transactions containing the -posting that matches your query be updated. Note that multiple files might be -update according to list of input files specified via `--file` options and -`include` directives inside of these files. - -Be careful. Whole transaction being re-formatted in a style of output from -`hledger print`. - -See also: - -https://github.com/simonmichael/hledger/issues/99 - -#### rewrite vs. print --auto - -This command predates print --auto, and currently does much the same thing, -but with these differences: - -- with multiple files, rewrite lets rules in any file affect all other files. - print --auto uses standard directive scoping; rules affect only child files. - -- rewrite's query limits which transactions can be rewritten; all are printed. - print --auto's query limits which transactions are printed. - -- rewrite applies rules specified on command line or in the journal. - print --auto applies rules specified in the journal. - - |] + ($(hereFileRelative "Hledger/Cli/Commands/Rewrite.txt")) [flagReq ["add-posting"] (\s opts -> Right $ setopt "add-posting" s opts) "'ACCT AMTEXPR'" "add a posting to ACCT, which may be parenthesised. AMTEXPR is either a literal amount, or *N which means the transaction's first matched amount multiplied by N (a decimal number). Two spaces separate ACCT and AMTEXPR." ,flagNone ["diff"] (setboolopt "diff") "generate diff suitable as an input for patch tool" @@ -170,18 +31,15 @@ [generalflagsgroup1] [] ([], Just $ argsFlag "[QUERY] --add-posting \"ACCT AMTEXPR\" ...") ------------------------------------------------------------------------------- -- TODO regex matching and interpolating matched name in replacement -- TODO interpolating match groups in replacement -- TODO allow using this on unbalanced entries, eg to rewrite while editing rewrite opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j@Journal{jtxns=ts} = do - -- create re-writer - let modifiers = transactionModifierFromOpts opts : jtxnmodifiers j - applyallmodifiers = foldr (flip (.) . transactionModifierToFunction) id modifiers -- rewrite matched transactions - let j' = j{jtxns=map applyallmodifiers ts} + let modifiers = transactionModifierFromOpts opts : jtxnmodifiers j + let j' = j{jtxns=modifyTransactions modifiers ts} -- run the print command, showing all transactions, or show diffs printOrDiff rawopts opts{reportopts_=ropts{query_=""}} j j' diff --git a/Hledger/Cli/Commands/Rewrite.txt b/Hledger/Cli/Commands/Rewrite.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Rewrite.txt @@ -0,0 +1,128 @@ +rewrite +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +--auto. + +_FLAGS_ + +This is a start at a generic rewriter of transaction entries. It reads +the default journal and prints the transactions, like print, but adds +one or more specified postings to any transactions matching QUERY. The +posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + +Examples: + +hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +hledger-rewrite.hs -f rewrites.hledger + +rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + +Note the single quotes to protect the dollar sign from bash, and the two +spaces between account and amount. + +More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + +Argument for --add-posting option is a usual posting of transaction with +an exception for amount specification. More precisely, you can use '*' +(star symbol) before the amount to indicate that that this is a factor +for an amount of original matched posting. If the amount includes a +commodity name, the new posting amount will be in the new commodity; +otherwise, it will be in the matched posting amount's commodity. + +Re-write rules in a file + +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. I.e instead of specifying this +operations in command line you can put them in a journal file. + +$ rewrite-rules.journal + +Make contents look like this: + += ^income + (liabilities:tax) *.33 + += expenses:gifts + budget:gifts *-1 + assets:budget *1 + +Note that '=' (equality symbol) that is used instead of date in +transactions you usually write. It indicates the query by which you want +to match the posting to add new ones. + +$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + +This is something similar to the commands pipeline: + +$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + +It is important to understand that relative order of such entries in +journal is important. You can re-use result of previously added +postings. + +Diff output format + +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. + +$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + +Output might look like: + +--- /tmp/examples/sample.journal ++++ /tmp/examples/sample.journal +@@ -18,3 +18,4 @@ + 2008/01/01 income +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:salary ++ (liabilities:tax) 0 +@@ -22,3 +23,4 @@ + 2008/06/01 gift +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:gifts ++ (liabilities:tax) 0 + +If you'll pass this through patch tool you'll get transactions +containing the posting that matches your query be updated. Note that +multiple files might be update according to list of input files +specified via --file options and include directives inside of these +files. + +Be careful. Whole transaction being re-formatted in a style of output +from hledger print. + +See also: + +https://github.com/simonmichael/hledger/issues/99 + +rewrite vs. print --auto + +This command predates print --auto, and currently does much the same +thing, but with these differences: + +- with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + +- rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + +- rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. diff --git a/Hledger/Cli/Commands/Roi.hs b/Hledger/Cli/Commands/Roi.hs --- a/Hledger/Cli/Commands/Roi.hs +++ b/Hledger/Cli/Commands/Roi.hs @@ -1,4 +1,5 @@ -{-# LANGUAGE QuasiQuotes,ParallelListComp,CPP #-} +{-# LANGUAGE ParallelListComp, CPP #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @roi@ command prints internal rate of return and time-weighted rate of return for and investment. @@ -19,7 +20,6 @@ import Data.Ord import Numeric.RootFinding import Data.Decimal -import Data.String.Here import System.Console.CmdArgs.Explicit as CmdArgs import Text.Tabular as Tbl @@ -29,31 +29,17 @@ import Hledger.Cli.CliOptions -roimode = (defCommandMode $ ["roi"]) { - modeHelp = "shows return on investment for your portfolio." - ,modeHelpSuffix=lines [here| -This command will show you time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - -Command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - -Any transactions affecting balance of investment account(s) and not originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - -At a minimum, you need to supply query (which could be just an account name) to select your investments with `--inv`, and another query to identify your profit and loss transactions with `--pnl`. - -Command will compute and display internalized rate of return (IRR) and time-weighted rate of return (TWR) for your investments for the time period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. -|] - ,modeGroupFlags = CmdArgs.Group { - groupUnnamed = [ - flagNone ["cashflow"] (setboolopt "cashflow") "show all amounts that were used to compute returns" - , flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY" - "query to select your investment transactions" - , flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY" - "query to select profit-and-loss or appreciation/valuation transactions" - ] - , groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } +roimode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Roi.txt")) + [flagNone ["cashflow"] (setboolopt "cashflow") "show all amounts that were used to compute returns" + ,flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY" + "query to select your investment transactions" + ,flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY" + "query to select profit-and-loss or appreciation/valuation transactions" + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- One reporting span, data OneSpan = OneSpan @@ -117,14 +103,15 @@ irr <- internalRateOfReturn showCashFlow prettyTables thisSpan twr <- timeWeightedReturn showCashFlow prettyTables investmentsQuery trans thisSpan let cashFlowAmt = negate $ sum $ map snd cashFlow + let smallIsZero x = if abs x < 0.01 then 0.0 else x return [ showDate spanBegin , showDate (addDays (-1) spanEnd) , show valueBefore , show cashFlowAmt , show valueAfter , show (valueAfter - (valueBefore + cashFlowAmt)) - , printf "%0.2f%%" irr - , printf "%0.2f%%" twr ] + , printf "%0.2f%%" $ smallIsZero irr + , printf "%0.2f%%" $ smallIsZero twr ] let table = Table (Tbl.Group NoLine (map (Header . show) (take (length tableBody) [1..]))) diff --git a/Hledger/Cli/Commands/Roi.txt b/Hledger/Cli/Commands/Roi.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Roi.txt @@ -0,0 +1,23 @@ +roi +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + +_FLAGS_ + +This command assumes that you have account(s) that hold nothing but your +investments and whenever you record current appraisal/valuation of these +investments you offset unrealized profit and loss into account(s) that, +again, hold nothing but unrealized profit and loss. + +Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. + +At a minimum, you need to supply a query (which could be just an account +name) to select your investments with --inv, and another query to +identify your profit and loss transactions with --pnl. + +It will compute and display the internalized rate of return (IRR) and +time-weighted rate of return (TWR) for your investments for the time +period requested. Both rates of return are annualized before display, +regardless of the length of reporting interval. diff --git a/Hledger/Cli/Commands/Stats.hs b/Hledger/Cli/Commands/Stats.hs --- a/Hledger/Cli/Commands/Stats.hs +++ b/Hledger/Cli/Commands/Stats.hs @@ -5,6 +5,7 @@ -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Stats ( statsmode @@ -29,17 +30,13 @@ import Hledger.Cli.Utils (writeOutput) -statsmode = (defCommandMode $ ["stats"] ++ aliases) { - modeHelp = "show some journal statistics" `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE. A file extension matching one of the above formats selects that format." - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = [] +statsmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Stats.txt")) + [flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE. A file extension matching one of the above formats selects that format." + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- like Register.summarisePostings -- | Print various statistics for the journal. diff --git a/Hledger/Cli/Commands/Stats.txt b/Hledger/Cli/Commands/Stats.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Stats.txt @@ -0,0 +1,25 @@ +stats +Show some journal statistics. + +_FLAGS_ + +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. + +Example: + +$ 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 ($) + +This command also supports output destination and output format +selection. 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 @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Tags ( tagsmode @@ -8,20 +8,13 @@ where import Data.List -import Data.String.Here import qualified Data.Text as T import Safe import Hledger import Hledger.Cli.CliOptions tagsmode = hledgerCommandMode - [here| 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 QUERY arguments, only transactions matching the query are considered. -Reads the default journal file, or another specified with -f. -FLAGS - |] + ($(hereFileRelative "Hledger/Cli/Commands/Tags.txt")) [] -- [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] -- [generalflagsgroup1] [] diff --git a/Hledger/Cli/Commands/Tags.txt b/Hledger/Cli/Commands/Tags.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Tags.txt @@ -0,0 +1,7 @@ +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 QUERY arguments, only transactions matching the query are +considered. + +_FLAGS_ diff --git a/Hledger/Cli/Commands/Test.txt b/Hledger/Cli/Commands/Test.txt new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Test.txt @@ -0,0 +1,21 @@ +test +Run built-in unit tests. + +_FLAGS_ + +This command runs the unit tests built in to hledger-lib and hledger, +printing test names and results on stdout. If any test fails, the exit +code will be non-zero. + +Test names include a group prefix. If a (exact, case sensitive) group +prefix, or a full test name is provided as the first argument, only that +group or test is run. + +If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). + +This is mainly used by developers, but it's nice to be able to +sanity-check your installed hledger executable at any time. All tests +are expected to pass - if you ever see otherwise, something has gone +wrong, please report a bug! diff --git a/Hledger/Cli/CompoundBalanceCommand.hs b/Hledger/Cli/CompoundBalanceCommand.hs --- a/Hledger/Cli/CompoundBalanceCommand.hs +++ b/Hledger/Cli/CompoundBalanceCommand.hs @@ -41,9 +41,7 @@ -- it should be added to or subtracted from the grand total. -- data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec { - cbcname :: String, -- ^ command name - cbcaliases :: [String], -- ^ command aliases - cbchelp :: String, -- ^ command line help + cbcdoc :: CommandDoc, -- ^ the command's name(s) and documentation cbctitle :: String, -- ^ overall report title cbcqueries :: [CBCSubreportSpec], -- ^ subreport details cbctype :: BalanceType -- ^ the "balance" type (change, cumulative, historical) @@ -83,37 +81,35 @@ -- | Generate a cmdargs option-parsing mode from a compound balance command -- specification. compoundBalanceCommandMode :: CompoundBalanceCommandSpec -> Mode RawOpts -compoundBalanceCommandMode CompoundBalanceCommandSpec{..} = (defCommandMode $ cbcname : cbcaliases) { - modeHelp = cbchelp `withAliases` cbcaliases - ,modeGroupFlags = C.Group { - groupUnnamed = [ - flagNone ["change"] (\opts -> setboolopt "change" opts) - ("show balance change in each period" ++ defType PeriodChange) - ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) - ("show balance change accumulated across periods (in multicolumn reports)" - ++ defType CumulativeChange - ) - ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) - ("show historical ending balance in each period (includes postings before report start date)" - ++ defType HistoricalBalance - ) - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" - ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" - ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" - ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" - ,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 code/name" - ,outputFormatFlag - ,outputFileFlag - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } +compoundBalanceCommandMode CompoundBalanceCommandSpec{..} = + hledgerCommandMode + cbcdoc + [flagNone ["change"] (\opts -> setboolopt "change" opts) + ("show balance change in each period" ++ defType PeriodChange) + ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) + ("show balance change accumulated across periods (in multicolumn reports)" + ++ defType CumulativeChange + ) + ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) + ("show historical ending balance in each period (includes postings before report start date)" + ++ defType HistoricalBalance + ) + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" + ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" + ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" + ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" + ,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 code/name" + ,outputFormatFlag + ,outputFileFlag + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") where defType :: BalanceType -> String defType bt | bt == cbctype = " (default)" diff --git a/Hledger/Cli/DocFiles.hs b/Hledger/Cli/DocFiles.hs --- a/Hledger/Cli/DocFiles.hs +++ b/Hledger/Cli/DocFiles.hs @@ -24,57 +24,59 @@ import "base-compat-batteries" Prelude.Compat import Data.ByteString (ByteString) import qualified Data.ByteString.Char8 as BC -import Data.FileEmbed import Data.String import System.IO import System.IO.Temp import System.Process -import Hledger.Utils (first3, second3, third3) +import Hledger.Utils (first3, second3, third3, embedFileRelative) type Topic = String +-- | These are all the main hledger manuals, in man, txt, and info formats. +-- Only files under the current package directory can be embedded, +-- so most of these are symlinked here from the other package directories. docFiles :: [(Topic, (ByteString, ByteString, ByteString))] docFiles = [ ("hledger", - ($(makeRelativeToProject "embeddedfiles/hledger.1" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger.1") + ,$(embedFileRelative "embeddedfiles/hledger.txt") + ,$(embedFileRelative "embeddedfiles/hledger.info") )) ,("hledger-ui", - ($(makeRelativeToProject "embeddedfiles/hledger-ui.1" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger-ui.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger-ui.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger-ui.1") + ,$(embedFileRelative "embeddedfiles/hledger-ui.txt") + ,$(embedFileRelative "embeddedfiles/hledger-ui.info") )) ,("hledger-web", - ($(makeRelativeToProject "embeddedfiles/hledger-web.1" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger-web.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger-web.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger-web.1") + ,$(embedFileRelative "embeddedfiles/hledger-web.txt") + ,$(embedFileRelative "embeddedfiles/hledger-web.info") )) ,("hledger-api", - ($(makeRelativeToProject "embeddedfiles/hledger-api.1" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger-api.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger-api.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger-api.1") + ,$(embedFileRelative "embeddedfiles/hledger-api.txt") + ,$(embedFileRelative "embeddedfiles/hledger-api.info") )) ,("journal", - ($(makeRelativeToProject "embeddedfiles/hledger_journal.5" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_journal.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_journal.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger_journal.5") + ,$(embedFileRelative "embeddedfiles/hledger_journal.txt") + ,$(embedFileRelative "embeddedfiles/hledger_journal.info") )) ,("csv", - ($(makeRelativeToProject "embeddedfiles/hledger_csv.5" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_csv.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_csv.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger_csv.5") + ,$(embedFileRelative "embeddedfiles/hledger_csv.txt") + ,$(embedFileRelative "embeddedfiles/hledger_csv.info") )) ,("timeclock", - ($(makeRelativeToProject "embeddedfiles/hledger_timeclock.5" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_timeclock.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_timeclock.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger_timeclock.5") + ,$(embedFileRelative "embeddedfiles/hledger_timeclock.txt") + ,$(embedFileRelative "embeddedfiles/hledger_timeclock.info") )) ,("timedot", - ($(makeRelativeToProject "embeddedfiles/hledger_timedot.5" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_timedot.txt" >>= embedFile) - ,$(makeRelativeToProject "embeddedfiles/hledger_timedot.info" >>= embedFile) + ($(embedFileRelative "embeddedfiles/hledger_timedot.5") + ,$(embedFileRelative "embeddedfiles/hledger_timedot.txt") + ,$(embedFileRelative "embeddedfiles/hledger_timedot.info") )) ] diff --git a/Hledger/Cli/Main.hs b/Hledger/Cli/Main.hs --- a/Hledger/Cli/Main.hs +++ b/Hledger/Cli/Main.hs @@ -67,7 +67,7 @@ ,groupNamed = [ ] -- subcommands handled but not shown in the help: - ,groupHidden = map fst builtinCommands ++ map quickAddonCommandMode addons + ,groupHidden = map fst builtinCommands ++ map addonCommandMode addons } ,modeGroupFlags = Group { -- flags in named groups: diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs --- a/Hledger/Cli/Utils.hs +++ b/Hledger/Cli/Utils.hs @@ -140,7 +140,7 @@ -- They end on or before the specified report end date, or 180 days from today if unspecified. -- journalAddForecast :: CliOpts -> Journal -> IO Journal -journalAddForecast opts@CliOpts{reportopts_=ropts} j = do +journalAddForecast opts@CliOpts{inputopts_=iopts, reportopts_=ropts} j = do today <- getCurrentDay -- "They start on or after the day following the latest normal transaction in the journal, or today if there are none." @@ -152,13 +152,17 @@ let forecastend = dbg2 "forecastend" $ fromMaybe (addDays 180 today) mspecifiedend let forecastspan = DateSpan (Just forecaststart) (Just forecastend) - forecasttxns = [ txnTieKnot t | pt <- jperiodictxns j - , t <- runPeriodicTransaction pt forecastspan - , spanContainsDate forecastspan (tdate t) - ] + forecasttxns = + [ txnTieKnot t | pt <- jperiodictxns j + , t <- runPeriodicTransaction pt forecastspan + , spanContainsDate forecastspan (tdate t) + ] + -- With --auto enabled, transaction modifiers are also applied to forecast txns + forecasttxns' = (if auto_ iopts then modifyTransactions (jtxnmodifiers j) else id) forecasttxns + return $ if forecast_ ropts - then journalBalanceTransactions' opts j{ jtxns = forecasttxns ++ jtxns j } -- XXX wouldn't appending be better ? + then journalBalanceTransactions' opts j{ jtxns = concat [jtxns j, forecasttxns'] } else j where journalBalanceTransactions' opts j = diff --git a/embeddedfiles/hledger-api.1 b/embeddedfiles/hledger-api.1 --- a/embeddedfiles/hledger-api.1 +++ b/embeddedfiles/hledger-api.1 @@ -1,5 +1,5 @@ -.TH "hledger\-api" "1" "December 2018" "hledger\-api 1.12" "hledger User Manuals" +.TH "hledger\-api" "1" "February 2019" "hledger\-api 1.13" "hledger User Manuals" diff --git a/embeddedfiles/hledger-api.info b/embeddedfiles/hledger-api.info --- a/embeddedfiles/hledger-api.info +++ b/embeddedfiles/hledger-api.info @@ -3,7 +3,7 @@  File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-api(1) hledger-api 1.12 +hledger-api(1) hledger-api 1.13 ******************************* hledger-api is a simple web API server, intended to support client-side diff --git a/embeddedfiles/hledger-api.txt b/embeddedfiles/hledger-api.txt --- a/embeddedfiles/hledger-api.txt +++ b/embeddedfiles/hledger-api.txt @@ -117,4 +117,4 @@ -hledger-api 1.12 December 2018 hledger-api(1) +hledger-api 1.13 February 2019 hledger-api(1) diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1 --- a/embeddedfiles/hledger-ui.1 +++ b/embeddedfiles/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger\-ui" "1" "December 2018" "hledger\-ui 1.12" "hledger User Manuals" +.TH "hledger\-ui" "1" "February 2019" "hledger\-ui 1.13" "hledger User Manuals" @@ -20,18 +20,19 @@ 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 +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 -Note hledger\-ui has some different defaults: \- it generates -rule\-based transactions and postings by default (\[en]forecast and -\[en]auto are always on). -\- it hides transactions dated in the future by default (change this -with \[en]future or the F key). -Experimental. +Note hledger\-ui has some different defaults (experimental): +.IP \[bu] 2 +it generates rule\-based transactions and postings by default +(\-\-forecast and \-\-auto are always on). +.IP \[bu] 2 +it hides transactions dated in the future by default (change this with +\-\-future or the F key). .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 @@ -57,7 +58,7 @@ .RE .TP .B \f[C]\-\-register=ACCTREGEX\f[] -start in the (first) matched account's register screen +start in the (first) matched account\[aq]s register screen .RS .RE .TP @@ -96,7 +97,7 @@ .RE .TP .B \f[C]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') +Field separator to expect when reading CSV (default: \[aq],\[aq]) .RS .RE .TP @@ -264,7 +265,7 @@ 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.) +(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). @@ -272,9 +273,9 @@ 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. +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 @@ -299,8 +300,8 @@ 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). +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. @@ -310,7 +311,7 @@ Disabling balance assertions temporarily can be useful for troubleshooting. .PP -\f[C]a\f[] runs command\-line hledger's add command, and reloads the +\f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the updated file. This allows some basic data entry. .PP @@ -333,7 +334,8 @@ .SS Accounts screen .PP This is normally the first screen displayed. -It lists accounts and their balances, like hledger's balance command. +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 @@ -380,8 +382,8 @@ 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. +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 @@ -392,7 +394,7 @@ (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 +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, @@ -405,10 +407,10 @@ the running historical balance you would see on a bank register for the current account. .PP -Transactions affecting this account's subaccounts will be included in -the register if the accounts screen is in tree mode, or if it's in flat -mode but this account has subaccounts which are not shown due to a depth -limit. +Transactions affecting this account\[aq]s subaccounts will be included +in the register if the accounts screen is in tree mode, or if it\[aq]s +in flat mode but this account has subaccounts which are not shown due to +a depth limit. In other words, the register always shows the transactions contributing to the balance shown on the accounts screen. .PD 0 @@ -422,7 +424,7 @@ 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 +activate all three, the filter is removed.) .PP \f[C]R\f[] toggles real mode, in which virtual postings are ignored. .PP @@ -435,10 +437,10 @@ .SS Transaction screen .PP This screen shows a single transaction, as a general journal entry, -similar to hledger's print command and journal format +similar to hledger\[aq]s print command and journal format (hledger_journal(5)). .PP -The transaction's date(s) and any cleared flag, transaction code, +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). @@ -449,9 +451,9 @@ 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). +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, @@ -479,7 +481,7 @@ 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). +\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 diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info --- a/embeddedfiles/hledger-ui.info +++ b/embeddedfiles/hledger-ui.info @@ -3,7 +3,7 @@  File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.12 +hledger-ui(1) hledger-ui 1.13 ***************************** hledger-ui is hledger's curses-style interface, providing an efficient @@ -12,11 +12,13 @@ interface, and sometimes quicker and more convenient than the web interface. - Note hledger-ui has some different defaults: - it generates -rule-based transactions and postings by default (-forecast and -auto are -always on). - it hides transactions dated in the future by default -(change this with -future or the F key). Experimental. + Note hledger-ui has some different defaults (experimental): + * it generates rule-based transactions and postings by default + (-forecast and -auto are always on). + * it hides transactions dated in the future by default (change this + with -future or the F key). + 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 @@ -347,7 +349,7 @@ 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 +is removed.) 'R' toggles real mode, in which virtual postings are ignored. @@ -396,19 +398,19 @@  Tag Table: Node: Top71 -Node: OPTIONS1084 -Ref: #options1181 -Node: KEYS4600 -Ref: #keys4695 -Node: SCREENS7951 -Ref: #screens8036 -Node: Accounts screen8126 -Ref: #accounts-screen8254 -Node: Register screen10470 -Ref: #register-screen10625 -Node: Transaction screen12622 -Ref: #transaction-screen12780 -Node: Error screen13650 -Ref: #error-screen13772 +Node: OPTIONS1100 +Ref: #options1197 +Node: KEYS4616 +Ref: #keys4711 +Node: SCREENS7967 +Ref: #screens8052 +Node: Accounts screen8142 +Ref: #accounts-screen8270 +Node: Register screen10486 +Ref: #register-screen10641 +Node: Transaction screen12637 +Ref: #transaction-screen12795 +Node: Error screen13665 +Ref: #error-screen13787  End Tag Table diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt --- a/embeddedfiles/hledger-ui.txt +++ b/embeddedfiles/hledger-ui.txt @@ -22,22 +22,25 @@ mand-line interface, and sometimes quicker and more convenient than the web interface. - Note hledger-ui has some different defaults: - it generates rule-based - transactions and postings by default (-forecast and -auto are always - on). - it hides transactions dated in the future by default (change - this with -future or the F key). Experimental. + Note hledger-ui has some different defaults (experimental): - 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), + o it generates rule-based transactions and postings by default (--fore- + cast and --auto are always on). + + o it hides transactions dated in the future by default (change this + with --future or the F key). + + 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 + Note: if invoking hledger-ui as a hledger subcommand, write -- before options as shown above. - Any QUERYARGS are interpreted as a hledger search query which filters + Any QUERYARGS are interpreted as a hledger search query which filters the data. --watch @@ -50,7 +53,7 @@ start in the (first) matched account's register screen --change - show period balances (changes) at startup instead of historical + show period balances (changes) at startup instead of historical balances -F --flat @@ -69,11 +72,11 @@ $LEDGER_FILE or $HOME/.hledger.journal) --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: + Conversion rules file to use when reading CSV (default: FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') + Field separator to expect when reading CSV (default: ',') --alias=OLD=NEW rename accounts named OLD to NEW @@ -110,11 +113,11 @@ multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax (overrides the flags above) --date2 - match the secondary date instead (see command help for other + match the secondary date instead (see command help for other effects) -U --unmarked @@ -133,21 +136,21 @@ hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the + convert amounts to their cost at transaction time (using the transaction price, if any) -V --value - convert amounts to their market value on the report end date + convert amounts to their market value on the report end date (using the most recent applicable market price, if any) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- + apply periodic transaction rules to generate future transac- tions, to 6 months from now or report end date. When a reporting option appears more than once in the command line, the @@ -167,70 +170,70 @@ 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, + 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 + ? 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 + 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 + 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 + 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- + 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 + / 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). + common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - As mentioned above, hledger-ui shows auto-generated periodic transac- + As mentioned above, hledger-ui shows auto-generated periodic transac- tions, and hides future transactions (auto-generated or not) by default. F toggles showing and hiding these future transactions. This - is similar to using a query like date:-tomorrow, but more convenient. + is similar to using a query like date:-tomorrow, but more convenient. (experimental) - ESCAPE removes all filters and jumps back to the top screen. Or, it + 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 + 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 + 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 + 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 + 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 + 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- + 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 + 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. @@ -239,44 +242,44 @@ 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 + 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 shown as a flat list by default. Press T to toggle - tree mode. In flat mode, account balances are exclusive of subac- - counts, except where subaccounts are hidden by a depth limit (see - below). In tree mode, all account balances are inclusive of subac- + Account names are shown as a flat list by default. Press T to toggle + tree mode. In flat mode, account balances are exclusive of subac- + counts, except where subaccounts are hidden by a depth limit (see + below). In tree mode, all account balances are inclusive of subac- counts. - To see less detail, press a number key, 1 to 9, to set a depth limit. + To see less detail, press a number key, 1 to 9, to set a depth limit. Or use - to decrease and +/= to increase the depth limit. 0 shows even - less detail, collapsing all accounts to a single total. To remove the - depth limit, set it higher than the maximum account depth, or press + less detail, collapsing all accounts to a single total. To remove the + depth limit, set it higher than the maximum account depth, or press ESCAPE. 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 + 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 + 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 + 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. @@ -285,64 +288,63 @@ 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 + 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 + 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 + 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 + a filter query, it will be the running historical balance you would see on a bank register for the current account. - Transactions affecting this account's subaccounts will be included in + Transactions affecting this account's subaccounts will be included in the register if the accounts screen is in tree mode, or if it's in flat - mode but this account has subaccounts which are not shown due to a - depth limit. In other words, the register always shows the transac- + mode but this account has subaccounts which are not shown due to a + depth limit. In other words, the register always shows the transac- tions contributing to the balance shown on the accounts screen. Tree mode/flat mode can be toggled with T here also. - U toggles filtering by unmarked status, showing or hiding unmarked + 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 + 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.) 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- + 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- + 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 + 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 + 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 + 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.) @@ -350,17 +352,17 @@ 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- + ~/.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 + 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- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-ui can't read from stdin). @@ -368,13 +370,13 @@ -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 + 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- + --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. @@ -382,7 +384,7 @@ REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -396,7 +398,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + 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) @@ -404,4 +406,4 @@ -hledger-ui 1.12 December 2018 hledger-ui(1) +hledger-ui 1.13 February 2019 hledger-ui(1) diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1 --- a/embeddedfiles/hledger-web.1 +++ b/embeddedfiles/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger\-web" "1" "December 2018" "hledger\-web 1.12" "hledger User Manuals" +.TH "hledger\-web" "1" "February 2019" "hledger\-web 1.13" "hledger User Manuals" @@ -20,7 +20,7 @@ file format. hledger is inspired by and largely compatible with ledger(1). .PP -hledger\-web is hledger's web interface. +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 @@ -42,8 +42,8 @@ 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. +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). @@ -61,8 +61,9 @@ 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). +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 @@ -90,7 +91,7 @@ \f[C]\-\-\f[] before options as shown above. .TP .B \f[C]\-\-serve\f[] -serve and log requests, don't browse or auto\-exit +serve and log requests, don\[aq]t browse or auto\-exit .RS .RE .TP @@ -134,7 +135,7 @@ .RE .TP .B \f[C]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') +Field separator to expect when reading CSV (default: \[aq],\[aq]) .RS .RE .TP @@ -302,7 +303,8 @@ 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). +\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 diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info --- a/embeddedfiles/hledger-web.info +++ b/embeddedfiles/hledger-web.info @@ -3,7 +3,7 @@  File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.12 +hledger-web(1) hledger-web 1.13 ******************************* hledger-web is hledger's web interface. It starts a simple web diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt --- a/embeddedfiles/hledger-web.txt +++ b/embeddedfiles/hledger-web.txt @@ -106,7 +106,7 @@ FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') + Field separator to expect when reading CSV (default: ',') --alias=OLD=NEW rename accounts named OLD to NEW @@ -251,4 +251,4 @@ -hledger-web 1.12 December 2018 hledger-web(1) +hledger-web 1.13 February 2019 hledger-web(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 --- a/embeddedfiles/hledger.1 +++ b/embeddedfiles/hledger.1 @@ -1,3093 +1,3203 @@ .\"t -.TH "hledger" "1" "December 2018" "hledger 1.12" "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]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') -.RS -.RE -.TP -.B \f[C]\-\-alias=OLD=NEW\f[] -rename accounts named OLD to NEW -.RS -.RE -.TP -.B \f[C]\-\-anon\f[] -anonymize accounts and payees -.RS -.RE -.TP -.B \f[C]\-\-pivot\ FIELDNAME\f[] -use some other field or tag for the account name -.RS -.RE -.TP -.B \f[C]\-I\ \-\-ignore\-assertions\f[] -ignore any failing balance assertions -.RS -.RE -.PP -General reporting options: -.TP -.B \f[C]\-b\ \-\-begin=DATE\f[] -include postings/txns on or after this date -.RS -.RE -.TP -.B \f[C]\-e\ \-\-end=DATE\f[] -include postings/txns before this date -.RS -.RE -.TP -.B \f[C]\-D\ \-\-daily\f[] -multiperiod/multicolumn report by day -.RS -.RE -.TP -.B \f[C]\-W\ \-\-weekly\f[] -multiperiod/multicolumn report by week -.RS -.RE -.TP -.B \f[C]\-M\ \-\-monthly\f[] -multiperiod/multicolumn report by month -.RS -.RE -.TP -.B \f[C]\-Q\ \-\-quarterly\f[] -multiperiod/multicolumn report by quarter -.RS -.RE -.TP -.B \f[C]\-Y\ \-\-yearly\f[] -multiperiod/multicolumn report by year -.RS -.RE -.TP -.B \f[C]\-p\ \-\-period=PERIODEXP\f[] -set start date, end date, and/or reporting interval all at once using -period expressions syntax (overrides the flags above) -.RS -.RE -.TP -.B \f[C]\-\-date2\f[] -match the secondary date instead (see command help for other effects) -.RS -.RE -.TP -.B \f[C]\-U\ \-\-unmarked\f[] -include only unmarked postings/txns (can combine with \-P or \-C) -.RS -.RE -.TP -.B \f[C]\-P\ \-\-pending\f[] -include only pending postings/txns -.RS -.RE -.TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns -.RS -.RE -.TP -.B \f[C]\-R\ \-\-real\f[] -include only non\-virtual postings -.RS -.RE -.TP -.B \f[C]\-NUM\ \-\-depth=NUM\f[] -hide/aggregate accounts or postings more than NUM levels deep -.RS -.RE -.TP -.B \f[C]\-E\ \-\-empty\f[] -show items with zero amount, normally hidden (and vice\-versa in -hledger\-ui/hledger\-web) -.RS -.RE -.TP -.B \f[C]\-B\ \-\-cost\f[] -convert amounts to their cost at transaction time (using the transaction -price, if any) -.RS -.RE -.TP -.B \f[C]\-V\ \-\-value\f[] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) -.RS -.RE -.TP -.B \f[C]\-\-auto\f[] -apply automated posting rules to modify transactions. -.RS -.RE -.TP -.B \f[C]\-\-forecast\f[] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. -.RS -.RE -.PP -When a reporting option appears more than once in the command line, the -last one takes precedence. -.PP -Some reporting options can also be written as query arguments. -.SS Command options -.PP -To see options for a particular command, including command\-specific -options, run: \f[C]hledger\ COMMAND\ \-h\f[]. -.PP -Command\-specific options must be written after the command name, eg: -\f[C]hledger\ print\ \-x\f[]. -.PP -Additionally, if the command is an addon, you may need to put its -options after a double\-hyphen, eg: -\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. -Or, you can run the addon executable directly: -\f[C]hledger\-ui\ \-\-watch\f[]. -.SS Command arguments -.PP -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. -.SS Argument files -.PP -You can save a set of command line options/arguments in a file, one per -line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command -line. -To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a -\f[C]\-\-\f[] argument. -For more, see Save frequently used options. -.SS Special characters in arguments and queries -.PP -In shell command lines, option and argument values which contain -\[lq]problematic\[rq] characters, ie spaces, and also characters -significant to your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], -\f[C])\f[], \f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing -them in quotes or by writing backslashes before the characters. -Eg: -.PP -\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. -.SS More escaping -.PP -Characters significant both to the shell and in regular expressions may -need one extra level of escaping. -These include parentheses, the pipe symbol and the dollar sign. -Eg, to match the dollar symbol, bash users should do: -.PP -\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] -.PP -or: -.PP -\f[C]hledger\ balance\ cur:\\\\$\f[] -.SS Even more escaping -.PP -When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[], -hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options -and arguments once, so you might need to \f[I]triple\f[]\-escape. -Eg in bash, running the ui command and matching the dollar sign, it's: -.PP -\f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] -.PP -or: -.PP -\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] -.PP -If you asked why \f[I]four\f[] slashes above, this may help: -.PP -.TS -tab(@); -l l. -T{ -unescaped: -T}@T{ -\f[C]$\f[] -T} -T{ -escaped: -T}@T{ -\f[C]\\$\f[] -T} -T{ -double\-escaped: -T}@T{ -\f[C]\\\\$\f[] -T} -T{ -triple\-escaped: -T}@T{ -\f[C]\\\\\\\\$\f[] -T} -.TE -.PP -(The number of backslashes in fish shell is left as an exercise for the -reader.) -.PP -You can always avoid the extra escaping for addons by running the addon -directly: -.PP -\f[C]hledger\-ui\ cur:\\\\$\f[] -.SS Less escaping -.PP -Inside an argument file, or in the search field of hledger\-ui or -hledger\-web, or at a GHCI prompt, you need one less level of escaping -than at the command line. -And backslashes may work better than quotes. -Eg: -.PP -\f[C]ghci>\ :main\ balance\ cur:\\$\f[] -.SS Command line tips -.PP -If in doubt, keep things simple: -.IP \[bu] 2 -write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[]) -.IP \[bu] 2 -run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[]) -.IP \[bu] 2 -enclose problematic args in single quotes -.IP \[bu] 2 -if needed, also add a backslash to escape regexp metacharacters -.PP -To find out exactly how a command line is being parsed, add -\f[C]\-\-debug=2\f[] to troubleshoot. -.SS Unicode characters -.PP -hledger is expected to handle unicode (non\-ascii) characters, but this -requires a well\-configured environment. -.PP -To handle unicode characters in the command line or input data, a system -locale that can decode them must be configured (POSIX's default -\f[C]C\f[] locale will not work). -Eg in bash, you could do: -.IP -.nf -\f[C] -export\ LANG=en_US.UTF\-8 -\f[] -.fi -.PP -See Troubleshooting for more about this. -.PP -Unicode characters should appear correctly in hledger's output. -For the hledger and hledger\-ui tools, this requires that -.IP \[bu] 2 -your terminal supports unicode -.IP \[bu] 2 -the terminal's font includes the required unicode glyphs -.IP \[bu] 2 -the terminal is configured to display \[lq]wide\[rq] characters as -double width (otherwise report alignment will be off) -.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]2004/10/1\f[], \f[C]2004\-01\-01\f[], \f[C]2004.9.1\f[] -T}@T{ -exact date, several separators allowed. -Year is 4+ digits, month is 1\-12, day is 1\-31 -T} -T{ -\f[C]2004\f[] -T}@T{ -start of year -T} -T{ -\f[C]2004/10\f[] -T}@T{ -start of month -T} -T{ -\f[C]10/1\f[] -T}@T{ -month and day in current year -T} -T{ -\f[C]21\f[] -T}@T{ -day in current month -T} -T{ -\f[C]october,\ oct\f[] -T}@T{ -start of month in current year -T} -T{ -\f[C]yesterday,\ today,\ tomorrow\f[] -T}@T{ -\-1, 0, 1 days from today -T} -T{ -\f[C]last/this/next\ day/week/month/quarter/year\f[] -T}@T{ -\-1, 0, 1 periods from the current period -T} -T{ -\f[C]20181201\f[] -T}@T{ -8 digit YYYYMMDD with valid year month and day -T} -T{ -\f[C]201812\f[] -T}@T{ -6 digit YYYYMM with valid year and month -T} -.TE -.PP -Counterexamples \- malformed digit sequences might give surprising -results: -.PP -.TS -tab(@); -l l. -T{ -\f[C]201813\f[] -T}@T{ -6 digits with an invalid month is parsed as start of 6\-digit year -T} -T{ -\f[C]20181301\f[] -T}@T{ -8 digits with an invalid month is parsed as start of 8\-digit year -T} -T{ -\f[C]20181232\f[] -T}@T{ -8 digits with an invalid day gives an error -T} -T{ -\f[C]201801012\f[] -T}@T{ -9+ digits beginning with a valid YYYYMMDD gives an error -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. -.PD 0 -.P -.PD -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\ \-N\ euros -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros -\f[] -.fi -.PP -What are they worth at end of nov 3 ? -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V\ \-e\ 2016/11/4 -\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros -\f[] -.fi -.PP -What are they worth after 2016/12/21 ? -(no report end date specified, defaults to today) -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V -\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros -\f[] -.fi -.PP -Currently, hledger's \-V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). -.PP -Currently, \-V has a limitation in multicolumn balance reports: it uses -the market prices on the report end date for all columns. -(Instead of the prices on each column's end date.) -.SS Combining \-B and \-V -.PP -Using \-B/\[en]cost and \-V/\[en]value together is currently allowed, -but the results are probably not meaningful. -Let us know if you find a use for this. -.SS Output destination -.PP -Some commands (print, register, stats, the balance commands) can write -their output to a destination other than the console. -This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) -$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE -\f[] -.fi -.SS Output format -.PP -Some commands can write their output in other formats. -Eg print and register can output CSV, and the balance commands can -output CSV or HTML. -This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by -specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with -\f[C]\-o/\-\-output\-file\f[]. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout -$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv -\f[] -.fi -.SS Regular expressions -.PP -hledger uses regular expressions in a number of places: -.IP \[bu] 2 -query terms, on the command line and in the hledger\-web search form: -\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[], -\f[C]tag:...=REGEX\f[] -.IP \[bu] 2 -CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[] -.IP \[bu] 2 -account alias directives and options: -\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[], -\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[] -.PP -hledger's regular expressions come from the regex\-tdfa library. -In general they: -.IP \[bu] 2 -are case insensitive -.IP \[bu] 2 -are infix matching (do not need to match the entire thing being matched) -.IP \[bu] 2 -are POSIX extended regular expressions -.IP \[bu] 2 -also support GNU word boundaries (\\<, \\>, \\b, \\B) -.IP \[bu] 2 -and parenthesised capturing groups and numeric backreferences in -replacement strings -.IP \[bu] 2 -do not support mode modifiers like (?s) -.PP -Some things to note: -.IP \[bu] 2 -In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular -expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]). -Elsewhere in hledger, these are not required. -.IP \[bu] 2 -In queries, to match a regular expression metacharacter like \f[C]$\f[] -as a literal character, prepend a backslash. -Eg to search for amounts with the dollar sign in hledger\-web, write -\f[C]cur:\\$\f[]. -.IP \[bu] 2 -On the command line, some metacharacters like \f[C]$\f[] have a special -meaning to the shell and so must be escaped at least once more. -See Special characters. -.SH QUERIES -.PP -One of hledger's strengths is being able to quickly report on precise -subsets of your data. -Most commands accept an optional query expression, written as arguments -after the command name, to filter the data by date, account name or -other criteria. -The syntax is similar to a web search: one or more space\-separated -search terms, quotes to enclose whitespace, prefixes to match specific -fields, a not: prefix to negate the match. -.PP -We do not yet support arbitrary boolean combinations of search terms; -instead most commands show transactions/postings/accounts which match -(or negatively match): -.IP \[bu] 2 -any of the description terms AND -.IP \[bu] 2 -any of the account terms AND -.IP \[bu] 2 -any of the status terms AND -.IP \[bu] 2 -all the other terms. -.PP -The print command instead shows transactions which: -.IP \[bu] 2 -match any of the description terms AND -.IP \[bu] 2 -have any postings matching any of the positive account terms AND -.IP \[bu] 2 -have no postings matching any of the negative account terms AND -.IP \[bu] 2 -match all the other terms. -.PP -The following kinds of search terms can be used. -Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to -exclude a particular subaccount. -.TP -.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[] -match account names by this regular expression. -(With no prefix, \f[C]acct:\f[] is assumed.) -.RS -.RE -same as above -.RS -.RE -.TP -.B \f[B]\f[BC]amt:N,\ amt:N,\ amt:>=N\f[B]\f[] -match postings with a single\-commodity amount that is equal to, less -than, or greater than N. -(Multi\-commodity amounts are not tested, and will always match.) The -comparison has two modes: if N is preceded by a + or \- sign (or is 0), -the two signed numbers are compared. -Otherwise, the absolute magnitudes are compared, ignoring sign. -.RS -.RE -.TP -.B \f[B]\f[BC]code:REGEX\f[B]\f[] -match by transaction code (eg check number) -.RS -.RE -.TP -.B \f[B]\f[BC]cur:REGEX\f[B]\f[] -match postings or transactions including any amounts whose -currency/commodity symbol is fully matched by REGEX. -(For a partial match, use \f[C]\&.*REGEX.*\f[]). -Note, to match characters which are regex\-significant, like the dollar -sign (\f[C]$\f[]), you need to prepend \f[C]\\\f[]. -And when using the command line you need to add one more level of -quoting to hide it from the shell, so eg do: -\f[C]hledger\ print\ cur:\[aq]\\$\[aq]\f[] or -\f[C]hledger\ print\ cur:\\\\$\f[]. -.RS -.RE -.TP -.B \f[B]\f[BC]desc:REGEX\f[B]\f[] -match transaction descriptions. -.RS -.RE -.TP -.B \f[B]\f[BC]date:PERIODEXPR\f[B]\f[] -match dates within the specified period. -PERIODEXPR is a period expression (with no report interval). -Examples: \f[C]date:2016\f[], \f[C]date:thismonth\f[], -\f[C]date:2000/2/1\-2/15\f[], \f[C]date:lastweek\-\f[]. -If the \f[C]\-\-date2\f[] command line flag is present, this matches -secondary dates instead. -.RS -.RE -.TP -.B \f[B]\f[BC]date2:PERIODEXPR\f[B]\f[] -match secondary dates within the specified period. -.RS -.RE -.TP -.B \f[B]\f[BC]depth:N\f[B]\f[] -match (or display, depending on command) accounts at or above this depth -.RS -.RE -.TP -.B \f[B]\f[BC]note:REGEX\f[B]\f[] -match transaction notes (part of description right of \f[C]|\f[], or -whole description when there's no \f[C]|\f[]) -.RS -.RE -.TP -.B \f[B]\f[BC]payee:REGEX\f[B]\f[] -match transaction payee/payer names (part of description left of -\f[C]|\f[], or whole description when there's no \f[C]|\f[]) -.RS -.RE -.TP -.B \f[B]\f[BC]real:,\ real:0\f[B]\f[] -match real or virtual postings respectively -.RS -.RE -.TP -.B \f[B]\f[BC]status:,\ status:!,\ status:*\f[B]\f[] -match unmarked, pending, or cleared transactions respectively -.RS -.RE -.TP -.B \f[B]\f[BC]tag:REGEX[=REGEX]\f[B]\f[] -match by tag name, and optionally also by tag value. -Note a tag: query is considered to match a transaction if it matches any -of the postings. -Also remember that postings inherit the tags of their parent -transaction. -.RS -.RE -.PP -The following special search term is used automatically in hledger\-web, -only: -.TP -.B \f[B]\f[BC]inacct:ACCTNAME\f[B]\f[] -tells hledger\-web to show the transaction register for this account. -Can be filtered further with \f[C]acct\f[] etc. -.RS -.RE -.PP -Some of these can also be expressed as command\-line options (eg -\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]). -Generally you can mix options and query arguments, and the resulting -query will be their intersection (perhaps excluding the -\f[C]\-p/\-\-period\f[] option). -.SH COMMANDS -.PP -hledger provides a number of subcommands; \f[C]hledger\f[] with no -arguments shows a list. -.PP -If you install additional \f[C]hledger\-*\f[] packages, or if you put -programs or scripts named \f[C]hledger\-NAME\f[] in your PATH, these -will also be listed as subcommands. -.PP -Run a subcommand by writing its name as first argument (eg -\f[C]hledger\ incomestatement\f[]). -You can also write one of the standard short aliases displayed in -parentheses in the command list (\f[C]hledger\ b\f[]), or any any -unambiguous prefix of a command name (\f[C]hledger\ inc\f[]). -.PP -Here are all the builtin commands in alphabetical order. -See also \f[C]hledger\f[] for a more organised command list, and -\f[C]hledger\ CMD\ \-h\f[] for detailed command help. -.SS accounts -.PP -Show account names. -Alias: a. -.TP -.B \f[C]\-\-declared\f[] -show account names declared with account directives -.RS -.RE -.TP -.B \f[C]\-\-used\f[] -show account names posted to by transactions -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show short account names and their parents, as a tree -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show full account names, as a list (default) -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -in flat mode: omit N leading account name parts -.RS -.RE -.PP -This command lists account names, either declared with account -directives (\[en]declared), posted to (\[en]used), or both (default). -With query arguments, only matched account names and account names -referenced by matched postings are shown. -It shows a flat list by default. -With \f[C]\-\-tree\f[], it uses indentation to show the account -hierarchy. -In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few -account name components. -Account names can be depth\-clipped with \f[C]\-\-depth\ N\f[] or -depth:N. -.PP -Examples: -.IP -.nf -\f[C] -$\ hledger\ accounts\ \-\-tree -assets -\ \ bank -\ \ \ \ checking -\ \ \ \ saving -\ \ cash -expenses -\ \ food -\ \ supplies -income -\ \ gifts -\ \ salary -liabilities -\ \ debts -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ accounts\ \-\-drop\ 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts -\f[] -.fi -.SS activity -.PP -Show an ascii barchart of posting counts per interval. -.PP -The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). -With query arguments, it counts only matched transactions. -.IP -.nf -\f[C] -$\ hledger\ activity\ \-\-quarterly -2008\-01\-01\ ** -2008\-04\-01\ ******* -2008\-07\-01\ -2008\-10\-01\ ** -\f[] -.fi -.SS add -.PP -Prompt for transactions and add them to the journal. -.TP -.B \f[C]\-\-no\-new\-accounts\f[] -don't allow creating new accounts; helps prevent typos when entering -account names -.RS -.RE -.PP -Many hledger users edit their journals directly with a text editor, or -generate them from CSV. -For more interactive data entry, there is the \f[C]add\f[] command, -which prompts interactively on the console for new transactions, and -appends them to the journal file (if there are multiple -\f[C]\-f\ FILE\f[] options, the first file is used.) Existing -transactions are not changed. -This is the only hledger command that writes to the journal file. -.PP -To use it, just run \f[C]hledger\ add\f[] and follow the prompts. -You can add as many transactions as you like; when you are finished, -enter \f[C]\&.\f[] or press control\-d or control\-c to exit. -.PP -Features: -.IP \[bu] 2 -add tries to provide useful defaults, using the most similar recent -transaction (by description) as a template. -.IP \[bu] 2 -You can also set the initial defaults with command line arguments. -.IP \[bu] 2 -Readline\-style edit keys can be used during data entry. -.IP \[bu] 2 -The tab key will auto\-complete whenever possible \- accounts, -descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[], -\f[C]tomorrow\f[]). -If the input area is empty, it will insert the default value. -.IP \[bu] 2 -If the journal defines a default commodity, it will be added to any bare -numbers entered. -.IP \[bu] 2 -A parenthesised transaction code may be entered following a date. -.IP \[bu] 2 -Comments and tags may be entered following a description or amount. -.IP \[bu] 2 -If you make a mistake, enter \f[C]<\f[] at any prompt to restart the -transaction. -.IP \[bu] 2 -Input prompts are displayed in a different colour when the terminal -supports it. -.PP -Example (see the tutorial for a detailed explanation): -.IP -.nf -\f[C] -$\ hledger\ add -Adding\ transactions\ to\ journal\ file\ /src/hledger/examples/sample.journal -Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults. -Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults. -An\ optional\ (CODE)\ may\ follow\ transaction\ dates. -An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts. -If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction. -To\ end\ a\ transaction,\ enter\ .\ when\ prompted. -To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c. -Date\ [2015/05/22]:\ -Description:\ supermarket -Account\ 1:\ expenses:food -Amount\ \ 1:\ $10 -Account\ 2:\ assets:checking -Amount\ \ 2\ [$\-10.0]:\ -Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ . -2015/05/22\ supermarket -\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10 -\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0 - -Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\ -Saved. -Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit) -Date\ [2015/05/22]:\ \ $ -\f[] -.fi -.SS balance -.PP -Show accounts and their balances. -Aliases: b, bal. -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date) -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv, html. -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.TP -.B \f[C]\-\-pretty\-tables\f[] -use unicode to display prettier tables. -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name (in flat mode). -With multiple columns, sorts by the row total, or by row average if that -is displayed. -.RS -.RE -.TP -.B \f[C]\-\-invert\f[] -display all amounts with reversed sign -.RS -.RE -.TP -.B \f[C]\-\-budget\f[] -show performance compared to budget goals defined by periodic -transactions -.RS -.RE -.TP -.B \f[C]\-\-show\-unbudgeted\f[] -with \[en]budget, show unbudgeted accounts also -.RS -.RE -.PP -The balance command is hledger's most versatile command. -Note, despite the name, it is not always used for showing real\-world -account balances; the more accounting\-aware balancesheet and -incomestatement may be more convenient for that. -.PP -By default, it displays all accounts, and each account's change in -balance during the entire period of the journal. -Balance changes are calculated by adding up the postings in each -account. -You can limit the postings matched, by a query, to see fewer accounts, -changes over a different time period, changes from only cleared -transactions, etc. -.PP -If you include an account's complete history of postings in the report, -the balance change is equivalent to the account's current ending -balance. -For a real\-world account, typically you won't have all transactions in -the journal; instead you'll have all transactions after a certain date, -and an \[lq]opening balances\[rq] transaction setting the correct -starting balance on that date. -Then the balance command will show real\-world account balances. -In some cases the \-H/\[en]historical flag is used to ensure this (more -below). -.PP -The balance command can produce several styles of report: -.SS Classic balance report -.PP -This is the original balance report, as found in Ledger. -It usually looks like this: -.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 -By default, accounts are displayed hierarchically, with subaccounts -indented below their parent. -At each level of the tree, accounts are sorted by account code if any, -then by account name. -Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. -.PP -\[lq]Boring\[rq] accounts, which contain a single interesting subaccount -and no balance of their own, are elided into the following line for more -compact output. -(Eg above, the \[lq]liabilities\[rq] account.) Use -\f[C]\-\-no\-elide\f[] to prevent this. -.PP -Account balances are \[lq]inclusive\[rq] \- they include the balances of -any subaccounts. -.PP -Accounts which have zero balance (and no non\-zero subaccounts) are -omitted. -Use \f[C]\-E/\-\-empty\f[] to show them. -.PP -A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to -suppress it, eg: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies -\f[] -.fi -.SS Customising the classic balance report -.PP -You can customise the layout of classic balance reports with -\f[C]\-\-format\ FMT\f[]: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-\-format\ "%20(account)\ %12(total)" -\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ $\-1 -\ \ \ \ \ \ \ \ \ bank:saving\ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ cash\ \ \ \ \ \ \ \ \ \ $\-2 -\ \ \ \ \ \ \ \ \ \ \ \ expenses\ \ \ \ \ \ \ \ \ \ \ $2 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ food\ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ \ \ \ \ \ \ \ \ supplies\ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ income\ \ \ \ \ \ \ \ \ \ $\-2 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ gifts\ \ \ \ \ \ \ \ \ \ $\-1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ salary\ \ \ \ \ \ \ \ \ \ $\-1 -\ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ $1 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -The FMT format string (plus a newline) specifies the formatting applied -to each account/balance pair. -It may contain any suitable text, with data fields interpolated like so: -.PP -\f[C]%[MIN][.MAX](FIELDNAME)\f[] -.IP \[bu] 2 -MIN pads with spaces to at least this width (optional) -.IP \[bu] 2 -MAX truncates at this width (optional) -.IP \[bu] 2 -FIELDNAME must be enclosed in parentheses, and can be one of: -.RS 2 -.IP \[bu] 2 -\f[C]depth_spacer\f[] \- a number of spaces equal to the account's -depth, or if MIN is specified, MIN * depth spaces. -.IP \[bu] 2 -\f[C]account\f[] \- the account's name -.IP \[bu] 2 -\f[C]total\f[] \- the account's balance/posted total, right justified -.RE -.PP -Also, FMT can begin with an optional prefix to control how -multi\-commodity amounts are rendered: -.IP \[bu] 2 -\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default) -.IP \[bu] 2 -\f[C]%^\f[] \- render on multiple lines, top\-aligned -.IP \[bu] 2 -\f[C]%,\f[] \- render on one line, comma\-separated -.PP -There are some quirks. -Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead -\f[C]%(account)\f[] has indentation built in. - Experimentation may be needed to get pleasing results. -.PP -Some example formats: -.IP \[bu] 2 -\f[C]%(total)\f[] \- the account's total -.IP \[bu] 2 -\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded -to 20 characters and clipped at 20 characters -.IP \[bu] 2 -\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50 -characters, total padded to 20 characters, with multiple commodities -rendered on one line -.IP \[bu] 2 -\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default -format for the single\-column balance report -.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 Flat mode -.PP -To see a flat list instead of the default hierarchical display, use -\f[C]\-\-flat\f[]. -In this mode, accounts (unless depth\-clipped) show their full names and -\[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[] or \f[C]depth:N\f[] or just \f[C]\-N\f[], -balance reports show accounts only to the specified numeric depth. -This is very useful to summarise a complex set of accounts and get an -overview. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-N\ \-1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities -\f[] -.fi -.PP -Flat\-mode balance reports, which normally show exclusive balances, show -inclusive balances at the depth limit. -.SS Multicolumn balance report -.PP -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. -They share many of the above features, but they show the report as a -table, with columns representing time periods. -This mode is activated by providing a reporting interval. -.PP -There are three types of multicolumn 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 -Multicolumn 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 -.PP -Limitations: -.PP -In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market -price on the report end date, for all columns (not the price on each -column's end date). -.PP -Eliding of boring parent accounts in tree mode, as in the classic -balance report, is not yet supported in multicolumn reports. -.SS Budget report -.PP -With \f[C]\-\-budget\f[], extra columns are displayed showing budget -goals for each account and period, if any. -Budget goals are defined by periodic transactions. -This is very useful for comparing planned and actual income, expenses, -time usage, etc. -\[en]budget is most often combined with a report interval. -.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 report: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ -======================++================================================= -\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $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 -By default, only accounts with budget goals during the report period are -shown. -\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well. -Top\-level accounts with no budget goals anywhere below them are grouped -under \f[C]\f[]. -.PP -You can roll over unspent budgets to next period with -\f[C]\-\-cumulative\f[]: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ -======================++================================================= -\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $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 -Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported -with \f[C]\-\-budget\f[]. -.PP -For more examples, see Budgeting and Forecasting. -.SS Output format -.PP -The balance command supports output destination and output format -selection. -.SS balancesheet -.PP -This command displays a simple balance sheet, showing historical ending -balances of asset and liability accounts (ignoring any report begin -date). -It assumes that these accounts are under a top\-level \f[C]asset\f[] or -\f[C]liability\f[] account (case insensitive, plural forms also -allowed). -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). -(bs) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period, instead of historical ending -balances -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of historical ending balances -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date) (default) -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE -.PP -Example: -.IP -.nf -\f[C] -$\ hledger\ balancesheet -Balance\ Sheet - -Assets: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -Liabilities: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -With a reporting interval, multiple columns will be shown, one for each -report period. -As with multicolumn balance reports, you can alter the report mode with -\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. -Normally balancesheet shows historical ending balances, which is what -you need for a balance sheet; note this means it ignores report begin -dates. -.PP -This command also supports output destination and output format -selection. -.SS balancesheetequity -.PP -Just like balancesheet, but also reports Equity (which it assumes is -under a top\-level \f[C]equity\f[] account). -.PP -Example: -.IP -.nf -\f[C] -$\ hledger\ balancesheetequity -Balance\ Sheet\ With\ Equity - -Assets: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-3\ \ \ \ cash -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 - -Liabilities: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 - -Equity: -\ \ \ \ \ \ \ \ \ \ $1\ \ equity:owner -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ $1 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.SS cashflow -.PP -This command displays a simple cashflow statement, showing changes in -\[lq]cash\[rq] accounts. -It assumes that these accounts are under a top\-level \f[C]asset\f[] -account (case insensitive, plural forms also allowed) and do not contain -\f[C]receivable\f[] or \f[C]A/R\f[] in their name. -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). -(cf) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of changes during periods -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date), instead of changes during each period -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row (in simple reports) -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE -.PP -Example: -.IP -.nf -\f[C] -$\ hledger\ cashflow -Cashflow\ Statement - -Cash\ flows: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 -\f[] -.fi -.PP -With a reporting interval, multiple columns will be shown, one for each -report period. -Normally cashflow shows changes in assets per period, though as with -multicolumn balance reports you can alter the report mode with -\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. -.PP -This command also supports output destination and output format -selection. -.SS check\-dates -.PP -Check that transactions are sorted by increasing date. -With a query, only matched transactions' dates are checked. -.SS check\-dupes -.PP -Report account names having the same leaf but different prefixes. -An example: http://stefanorodighiero.net/software/hledger\-dupes.html -.SS close -.PP -Print closing/opening transactions that bring some or all account -balances to zero and back. -Can be useful for bringing asset/liability balances across file -boundaries, or for closing out income/expenses for a period. -This was formerly called \[lq]equity\[rq], as in Ledger, and that alias -is also accepted. -See close \[en]help for more. -.SS files -.PP -List all files included in the journal. -With a REGEX argument, only file names matching the regular expression -(case sensitive) are shown. -.SS help -.PP -Show any of the hledger manuals. -.PP -The \f[C]help\f[] command displays any of the main hledger manuals, in -one of several ways. -Run it with no argument to list the manuals, or provide a full or -partial manual name to select one. -.PP -hledger manuals are available in several formats. -hledger help will use the first of these display methods that it finds: -info, man, $PAGER, less, stdout (or when non\-interactive, just stdout). -You can force a particular viewer with the \f[C]\-\-info\f[], -\f[C]\-\-man\f[], \f[C]\-\-pager\f[], \f[C]\-\-cat\f[] flags. -.IP -.nf -\f[C] -$\ hledger\ help -Please\ choose\ a\ manual\ by\ typing\ "hledger\ help\ MANUAL"\ (a\ substring\ is\ ok). -Manuals:\ hledger\ hledger\-ui\ hledger\-web\ hledger\-api\ journal\ csv\ timeclock\ timedot -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ help\ h\ \-\-man - -hledger(1)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger\ User\ Manuals\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger(1) - -NAME -\ \ \ \ \ \ \ hledger\ \-\ a\ command\-line\ accounting\ tool - -SYNOPSIS -\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS] -\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS] -\ \ \ \ \ \ \ hledger - -DESCRIPTION -\ \ \ \ \ \ \ hledger\ \ is\ \ a\ \ cross\-platform\ \ program\ \ for\ tracking\ money,\ time,\ or\ any -\&... -\f[] -.fi -.SS import -.PP -Read new transactions added to each FILE since last run, and add them to -the main journal file. -.TP -.B \f[C]\-\-dry\-run\f[] -just show the transactions to be imported -.RS -.RE -.PP -The input files are specified as arguments \- no need to write \-f -before each one. -So eg to add new transactions from all CSV files to the main journal, -it's just: \f[C]hledger\ import\ *.csv\f[] -.PP -New transactions are detected in the same way as print \[en]new: by -assuming transactions are always added to the input files in increasing -date order, and by saving \f[C]\&.latest.FILE\f[] state files. -.PP -The \[en]dry\-run output is in journal format, so you can filter it, eg -to see only uncategorised transactions: -.IP -.nf -\f[C] -$\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\-assertions -\f[] -.fi -.SS incomestatement -.PP -This command displays a simple income statement, showing revenues and -expenses during a period. -It assumes that these accounts are under a top\-level \f[C]revenue\f[] -or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural -forms also allowed). -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). -(is) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of changes during periods -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date), instead of changes during each period -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE -.PP -This command displays a simple income statement. -It currently assumes that you have top\-level accounts named -\f[C]income\f[] (or \f[C]revenue\f[]) and \f[C]expense\f[] (plural forms -also allowed.) -.IP -.nf -\f[C] -$\ hledger\ incomestatement -Income\ Statement - -Revenues: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 - -Expenses: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -With a reporting interval, multiple columns will be shown, one for each -report period. -Normally incomestatement shows revenues/expenses per period, though as -with multicolumn balance reports you can alter the report mode with -\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. -.PP -This command also supports output destination and output format -selection. -.SS prices -.PP -Print market price directives from the journal. -With \[en]costs, also print synthetic market prices based on transaction -prices. -With \[en]inverted\-costs, also print inverse prices based on -transaction prices. -Prices (and postings providing prices) can be filtered by a query. -.SS print -.PP -Show transactions from the journal. -Aliases: p, txns. -.TP -.B \f[C]\-m\ STR\ \-\-match=STR\f[] -show the transaction whose description is most similar to STR, and is -most recent -.RS -.RE -.TP -.B \f[C]\-\-new\f[] -show only newer\-dated transactions added in each file since last run -.RS -.RE -.TP -.B \f[C]\-x\ \ \ \ \ \-\-explicit\f[] -show all amounts explicitly -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv. -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.IP -.nf -\f[C] -$\ hledger\ print -2008/01/01\ income -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -2008/06/01\ gift -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -2008/06/02\ save -\ \ \ \ assets:bank:saving\ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1 - -2008/06/03\ *\ eat\ &\ shop -\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ expenses:supplies\ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 - -2008/12/31\ *\ pay\ off -\ \ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1 -\f[] -.fi -.PP -The print command displays full journal entries (transactions) from the -journal file in date order, tidily formatted. -print's output is always a valid hledger journal. -It preserves all transaction information, but it does not preserve -directives or inter\-transaction comments -.PP -Normally, the journal entry's explicit or implicit amount style is -preserved. -Ie when an amount is omitted in the journal, it will be omitted in the -output. -You can use the \f[C]\-x\f[]/\f[C]\-\-explicit\f[] flag to make all -amounts explicit, which can be useful for troubleshooting or for making -your journal more readable and robust against data entry errors. -Note, \f[C]\-x\f[] will cause postings with a multi\-commodity amount -(these can arise when a multi\-commodity transaction has an implicit -amount) will be split into multiple single\-commodity postings, for -valid journal output. -.PP -With \f[C]\-B\f[]/\f[C]\-\-cost\f[], amounts with transaction prices are -converted to cost using that price. -This can be used for troubleshooting. -.PP -With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show -at most one transaction: the one one whose description is most similar -to STR, and is most recent. -STR should contain at least two characters. -If there is no similar\-enough match, no transaction will be shown. -.PP -With \f[C]\-\-new\f[], for each FILE being read, hledger reads (and -writes) a special state file (\f[C]\&.latest.FILE\f[] in the same -directory), containing the latest transaction date(s) that were seen -last time FILE was read. -When this file is found, only transactions with newer dates (and new -transactions on the latest date) are printed. -This is useful for ignoring already\-seen entries in import data, such -as downloaded CSV files. -Eg: -.IP -.nf -\f[C] -$\ hledger\ \-f\ bank1.csv\ print\ \-\-new -#\ shows\ transactions\ added\ since\ last\ print\ \-\-new\ on\ this\ file -\f[] -.fi -.PP -This assumes that transactions added to FILE always have same or -increasing dates, and that transactions on the same day do not get -reordered. -See also the import command. -.PP -This command also supports output destination and output format -selection. -Here's an example of print's CSV output: -.IP -.nf -\f[C] -$\ hledger\ print\ \-Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting\-status","posting\-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","\-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","\-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","\-1","$","1","","","" -"4","2008/06/03","","*","","eat\ &\ shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat\ &\ shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat\ &\ shop","","assets:cash","\-2","$","2","","","" -"5","2008/12/31","","*","","pay\ off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay\ off","","assets:bank:checking","\-1","$","1","","","" -\f[] -.fi -.IP \[bu] 2 -There is one CSV record per posting, with the parent transaction's -fields repeated. -.IP \[bu] 2 -The \[lq]txnidx\[rq] (transaction index) field shows which postings -belong to the same transaction. -(This number might change if transactions are reordered within the file, -files are parsed/included in a different order, etc.) -.IP \[bu] 2 -The amount is separated into \[lq]commodity\[rq] (the symbol) and -\[lq]amount\[rq] (numeric quantity) fields. -.IP \[bu] 2 -The numeric amount is repeated in either the \[lq]credit\[rq] or -\[lq]debit\[rq] column, for convenience. -(Those names are not accurate in the accounting sense; it just puts -negative amounts under credit and zero or greater amounts under debit.) -.SS print\-unique -.PP -Print transactions which do not reuse an already\-seen description. -.SS register -.PP -Show postings and their running total. -Aliases: r, reg. -.TP -.B \f[C]\-\-cumulative\f[] -show running total from report start date (default) -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical running total/balance (includes postings before report -start date) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show running average of posting amounts instead of total (implies -\[en]empty) -.RS -.RE -.TP -.B \f[C]\-r\ \-\-related\f[] -show postings' siblings instead -.RS -.RE -.TP -.B \f[C]\-w\ N\ \-\-width=N\f[] -set output width (default: terminal width or COLUMNS. -\-wN,M sets description width as well) -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv. -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.PP -The register command displays postings, one per line, and their running -total. -This is typically used with a query selecting a particular account, to -see that account's activity: -.IP -.nf -\f[C] -$\ hledger\ register\ checking -2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2 -2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -The \f[C]\-\-historical\f[]/\f[C]\-H\f[] flag adds the balance from any -undisplayed prior postings to the running total. -This is useful when you want to see only recent activity, with a -historically accurate running balance: -.IP -.nf -\f[C] -$\ hledger\ register\ checking\ \-b\ 2008/6\ \-\-historical -2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2 -2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -The \f[C]\-\-depth\f[] option limits the amount of sub\-account detail -displayed. -.PP -The \f[C]\-\-average\f[]/\f[C]\-A\f[] flag shows the running average -posting amount instead of the running total (so, the final number -displayed is the average for the whole report period). -This flag implies \f[C]\-\-empty\f[] (see below). -It is affected by \f[C]\-\-historical\f[]. -It works best when showing just one account and one commodity. -.PP -The \f[C]\-\-related\f[]/\f[C]\-r\f[] flag shows the \f[I]other\f[] -postings in the transactions of the postings which would normally be -shown. -.PP -With a reporting interval, register shows summary postings, one per -interval, aggregating the postings to each account: -.IP -.nf -\f[C] -$\ hledger\ register\ \-\-monthly\ income -2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2 -\f[] -.fi -.PP -Periods with no activity, and summary postings with a zero amount, are -not shown by default; use the \f[C]\-\-empty\f[]/\f[C]\-E\f[] flag to -see them: -.IP -.nf -\f[C] -$\ hledger\ register\ \-\-monthly\ income\ \-E -2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/02\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/03\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/04\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/05\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/07\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/08\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/09\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/10\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -\f[] -.fi -.PP -Often, you'll want to see just one line per interval. -The \f[C]\-\-depth\f[] option helps with this, causing subaccounts to be -aggregated: -.IP -.nf -\f[C] -$\ hledger\ register\ \-\-monthly\ assets\ \-\-depth\ 1h -2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 -2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 -\f[] -.fi -.PP -Note when using report intervals, if you specify start/end dates these -will be adjusted outward if necessary to contain a whole number of -intervals. -This ensures that the first and last intervals are full length and -comparable to the others in the report. -.SS Custom register output -.PP -register uses the full terminal width by default, except on windows. -You can override this by setting the \f[C]COLUMNS\f[] environment -variable (not a bash shell variable) or by using the -\f[C]\-\-width\f[]/\f[C]\-w\f[] option. -.PP -The description and account columns normally share the space equally -(about half of (width \- 40) each). -You can adjust this by adding a description width as part of -\[en]width's argument, comma\-separated: \f[C]\-\-width\ W,D\f[] . -Here's a diagram: -.IP -.nf -\f[C] -<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ width\ (W)\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-> -date\ (10)\ \ description\ (D)\ \ \ \ \ \ \ account\ (W\-41\-D)\ \ \ \ \ amount\ (12)\ \ \ balance\ (12) -DDDDDDDDDD\ dddddddddddddddddddd\ \ aaaaaaaaaaaaaaaaaaa\ \ AAAAAAAAAAAA\ \ AAAAAAAAAAAA -\f[] -.fi -.PP -and some examples: -.IP -.nf -\f[C] -$\ hledger\ reg\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ terminal\ width\ (or\ 80\ on\ windows) -$\ hledger\ reg\ \-w\ 100\ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ width\ 100 -$\ COLUMNS=100\ hledger\ reg\ \ \ \ \ \ \ \ \ #\ set\ with\ one\-time\ environment\ variable -$\ export\ COLUMNS=100;\ hledger\ reg\ #\ set\ till\ session\ end\ (or\ window\ resize) -$\ hledger\ reg\ \-w\ 100,40\ \ \ \ \ \ \ \ \ \ \ #\ set\ overall\ width\ 100,\ description\ width\ 40 -$\ hledger\ reg\ \-w\ $COLUMNS,40\ \ \ \ \ \ #\ use\ terminal\ width,\ and\ set\ description\ width -\f[] -.fi -.PP -This command also supports output destination and output format -selection. -.SS register\-match -.PP -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. -Helps ledger\-autosync detect already\-seen transactions when importing. -.SS rewrite -.PP -Print all transactions, adding custom postings to the matched ones. -.SS roi -.PP -Shows time\-weighted (TWR) and money\-weighted (IRR) rate of return on -your investments. -See \f[C]roi\ \-\-help\f[] for more. -.SS stats -.PP -Show some journal statistics. -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.IP -.nf -\f[C] -$\ hledger\ stats -Main\ journal\ file\ \ \ \ \ \ \ \ :\ /src/hledger/examples/sample.journal -Included\ journal\ files\ \ \ :\ -Transactions\ span\ \ \ \ \ \ \ \ :\ 2008\-01\-01\ to\ 2009\-01\-01\ (366\ days) -Last\ transaction\ \ \ \ \ \ \ \ \ :\ 2008\-12\-31\ (2333\ days\ ago) -Transactions\ \ \ \ \ \ \ \ \ \ \ \ \ :\ 5\ (0.0\ per\ day) -Transactions\ last\ 30\ days:\ 0\ (0.0\ per\ day) -Transactions\ last\ 7\ days\ :\ 0\ (0.0\ per\ day) -Payees/descriptions\ \ \ \ \ \ :\ 5 -Accounts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 8\ (depth\ 3) -Commodities\ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 1\ ($) -\f[] -.fi -.PP -The stats command displays summary information for the whole journal, or -a matched part of it. -With a reporting interval, it shows a report for each report period. -.PP -This command also supports output destination and output format -selection. -.SS tags -.PP -List all the tag names used in the journal. -With a TAGREGEX argument, only tag names matching the regular expression -(case insensitive) are shown. -With additional QUERY arguments, only transactions matching the query -are considered. -.SS test -.PP -Run built\-in unit tests. -.PP -Prints test names and their results on stdout. -If any test fails or gives an error, the exit code will be non\-zero. -.PP -Test names include a group prefix. -If a (exact, case sensitive) group prefix, or a full test name is -provided as the first argument, only that group or test is run. -.PP -If a numeric second argument is provided, it will set the randomness -seed, for repeatable results from tests using randomness (currently none -of them). -.PP -This is mainly used by developers, but it's nice to be able to -sanity\-check your installed hledger executable at any time. -All tests are expected to pass \- if you ever see otherwise, something -has gone wrong, please report a bug! -.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, but it's superseded now by the built\-in roi command. -.SS Experimental add\-ons -.PP -These are available in source form in the hledger repo's bin/ directory; -installing them is pretty easy. -They may be less mature and documented than built\-in commands. -Reading and tweaking these is a good way to start making your own! -.SS autosync -.PP -hledger\-autosync is a symbolic link for easily running -ledger\-autosync, if installed. -ledger\-autosync does deduplicating conversion of OFX data and some CSV -formats, and can also download the data if your bank offers OFX Direct -Connect. -.SS chart -.PP -hledger\-chart.hs is an old pie chart generator, in need of some love. -.SS check -.PP -hledger\-check.hs checks more powerful account balance assertions. -.SH ENVIRONMENT -.PP -\f[B]COLUMNS\f[] The screen width used by the register command. -Default: the full terminal width. -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede addon command options with \f[C]\-\-\f[] when -invoked from hledger is awkward. -.PP -When input data contains non\-ascii characters, a suitable system locale -must be configured (or there will be an unhelpful error). -Eg on POSIX, set LANG to something other than C. -.PP -In a Microsoft Windows CMD window, non\-ascii characters and colours are -not supported. -.PP -In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger -add. -.PP -Not all of Ledger's journal file syntax is supported. -See file format differences. -.PP -On large data files, hledger is slower and uses more memory than Ledger. -.SH TROUBLESHOOTING -.PP -Here are some issues you might encounter when you run hledger (and -remember you can also seek help from the IRC channel, mail list or bug -tracker): -.PP -\f[B]Successfully installed, but \[lq]No command `hledger' -found\[rq]\f[] -.PD 0 -.P -.PD -stack and cabal install binaries into a special directory, which should -be added to your PATH environment variable. -Eg on unix\-like systems, that is ~/.local/bin and ~/.cabal/bin -respectively. -.PP -\f[B]I set a custom LEDGER_FILE, but hledger is still using the default -file\f[] -.PD 0 -.P -.PD -\f[C]LEDGER_FILE\f[] should be a real environment variable, not just a -shell variable. -The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it. -You may need to use \f[C]export\f[]. -Here's an explanation. -.PP -\f[B]\[lq]Illegal byte sequence\[rq] or \[lq]Invalid or incomplete -multibyte or wide character\[rq] errors\f[] -.PD 0 -.P -.PD -In order to handle non\-ascii letters and symbols (like £), hledger -needs an appropriate locale. -This is usually configured system\-wide; you can also configure it -temporarily. -The locale may need to be one that supports UTF\-8, if you built hledger -with GHC < 7.2 (or possibly always, I'm not sure yet). -.PP -Here's an example of setting the locale temporarily, on ubuntu -gnu/linux: -.IP -.nf -\f[C] -$\ file\ my.journal -my.journal:\ UTF\-8\ Unicode\ text\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ the\ file\ is\ UTF8\-encoded -$\ locale\ \-a -C -en_US.utf8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ a\ UTF8\-aware\ locale\ is\ available -POSIX -$\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ this\ command -\f[] -.fi -.PP -Here's one way to set it permanently, there are probably better ways: +.TH "hledger" "1" "February 2019" "hledger 1.13" "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]\-\-separator=CHAR\f[] +Field separator to expect when reading CSV (default: \[aq],\[aq]) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +rename accounts named OLD to NEW +.RS +.RE +.TP +.B \f[C]\-\-anon\f[] +anonymize accounts and payees +.RS +.RE +.TP +.B \f[C]\-\-pivot\ FIELDNAME\f[] +use some other field or tag for the account name +.RS +.RE +.TP +.B \f[C]\-I\ \-\-ignore\-assertions\f[] +ignore any failing balance assertions +.RS +.RE +.PP +General reporting options: +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once using +period expressions syntax (overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\f[] +match the secondary date instead (see command help for other effects) +.RS +.RE +.TP +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) +.RS +.RE +.TP +.B \f[C]\-P\ \-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-NUM\ \-\-depth=NUM\f[] +hide/aggregate accounts or postings more than NUM levels deep +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show items with zero amount, normally hidden (and vice\-versa in +hledger\-ui/hledger\-web) +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +convert amounts to their cost at transaction time (using the transaction +price, if any) +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +convert amounts to their market value on the report end date (using the +most recent applicable market price, if any) +.RS +.RE +.TP +.B \f[C]\-\-auto\f[] +apply automated posting rules to modify transactions. +.RS +.RE +.TP +.B \f[C]\-\-forecast\f[] +apply periodic transaction rules to generate future transactions, to 6 +months from now or report end date. +.RS +.RE +.PP +When a reporting option appears more than once in the command line, the +last one takes precedence. +.PP +Some reporting options can also be written as query arguments. +.SS Command options +.PP +To see options for a particular command, including command\-specific +options, run: \f[C]hledger\ COMMAND\ \-h\f[]. +.PP +Command\-specific options must be written after the command name, eg: +\f[C]hledger\ print\ \-x\f[]. +.PP +Additionally, if the command is an addon, you may need to put its +options after a double\-hyphen, eg: +\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. +Or, you can run the addon executable directly: +\f[C]hledger\-ui\ \-\-watch\f[]. +.SS Command arguments +.PP +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. +.SS Argument files +.PP +You can save a set of command line options/arguments in a file, one per +line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command +line. +To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a +\f[C]\-\-\f[] argument. +For more, see Save frequently used options. +.SS Special characters in arguments and queries +.PP +In shell command lines, option and argument values which contain +"problematic" characters, ie spaces, and also characters significant to +your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], \f[C])\f[], +\f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing them in quotes +or by writing backslashes before the characters. +Eg: +.PP +\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. +.SS More escaping +.PP +Characters significant both to the shell and in regular expressions may +need one extra level of escaping. +These include parentheses, the pipe symbol and the dollar sign. +Eg, to match the dollar symbol, bash users should do: +.PP +\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] +.PP +or: +.PP +\f[C]hledger\ balance\ cur:\\\\$\f[] +.SS Even more escaping +.PP +When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[], +hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options +and arguments once, so you might need to \f[I]triple\f[]\-escape. +Eg in bash, running the ui command and matching the dollar sign, +it\[aq]s: +.PP +\f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] +.PP +or: +.PP +\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] +.PP +If you asked why \f[I]four\f[] slashes above, this may help: +.PP +.TS +tab(@); +l l. +T{ +unescaped: +T}@T{ +\f[C]$\f[] +T} +T{ +escaped: +T}@T{ +\f[C]\\$\f[] +T} +T{ +double\-escaped: +T}@T{ +\f[C]\\\\$\f[] +T} +T{ +triple\-escaped: +T}@T{ +\f[C]\\\\\\\\$\f[] +T} +.TE +.PP +(The number of backslashes in fish shell is left as an exercise for the +reader.) +.PP +You can always avoid the extra escaping for addons by running the addon +directly: +.PP +\f[C]hledger\-ui\ cur:\\\\$\f[] +.SS Less escaping +.PP +Inside an argument file, or in the search field of hledger\-ui or +hledger\-web, or at a GHCI prompt, you need one less level of escaping +than at the command line. +And backslashes may work better than quotes. +Eg: +.PP +\f[C]ghci>\ :main\ balance\ cur:\\$\f[] +.SS Command line tips +.PP +If in doubt, keep things simple: +.IP \[bu] 2 +write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[]) +.IP \[bu] 2 +run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[]) +.IP \[bu] 2 +enclose problematic args in single quotes +.IP \[bu] 2 +if needed, also add a backslash to escape regexp metacharacters +.PP +To find out exactly how a command line is being parsed, add +\f[C]\-\-debug=2\f[] to troubleshoot. +.SS Unicode characters +.PP +hledger is expected to handle unicode (non\-ascii) characters, but this +requires a well\-configured environment. +.PP +To handle unicode characters in the command line or input data, a system +locale that can decode them must be configured (POSIX\[aq]s default +\f[C]C\f[] locale will not work). +Eg in bash, you could do: +.IP +.nf +\f[C] +export\ LANG=en_US.UTF\-8 +\f[] +.fi +.PP +See Troubleshooting for more about this. +.PP +Unicode characters should appear correctly in hledger\[aq]s output. +For the hledger and hledger\-ui tools, this requires that +.IP \[bu] 2 +your terminal supports unicode +.IP \[bu] 2 +the terminal\[aq]s font includes the required unicode glyphs +.IP \[bu] 2 +the terminal is configured to display "wide" characters as double width +(otherwise report alignment will be off) +.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.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\[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]2004/10/1\f[], \f[C]2004\-01\-01\f[], \f[C]2004.9.1\f[] +T}@T{ +exact date, several separators allowed. +Year is 4+ digits, month is 1\-12, day is 1\-31 +T} +T{ +\f[C]2004\f[] +T}@T{ +start of year +T} +T{ +\f[C]2004/10\f[] +T}@T{ +start of month +T} +T{ +\f[C]10/1\f[] +T}@T{ +month and day in current year +T} +T{ +\f[C]21\f[] +T}@T{ +day in current month +T} +T{ +\f[C]october,\ oct\f[] +T}@T{ +start of month in current year +T} +T{ +\f[C]yesterday,\ today,\ tomorrow\f[] +T}@T{ +\-1, 0, 1 days from today +T} +T{ +\f[C]last/this/next\ day/week/month/quarter/year\f[] +T}@T{ +\-1, 0, 1 periods from the current period +T} +T{ +\f[C]20181201\f[] +T}@T{ +8 digit YYYYMMDD with valid year month and day +T} +T{ +\f[C]201812\f[] +T}@T{ +6 digit YYYYMM with valid year and month +T} +.TE +.PP +Counterexamples \- malformed digit sequences might give surprising +results: +.PP +.TS +tab(@); +l l. +T{ +\f[C]201813\f[] +T}@T{ +6 digits with an invalid month is parsed as start of 6\-digit year +T} +T{ +\f[C]20181301\f[] +T}@T{ +8 digits with an invalid month is parsed as start of 8\-digit year +T} +T{ +\f[C]20181232\f[] +T}@T{ +8 digits with an invalid day gives an error +T} +T{ +\f[C]201801012\f[] +T}@T{ +9+ digits beginning with a valid YYYYMMDD gives an error +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 +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[] \-\- starts on +2008/12/29, closest preceeding Monday +T} +T{ +\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \-\- 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[] \-\- periods will have boundaries +on 2008/01/01, 2008/03/01, ... +T} +T{ +\f[C]\-p\ "every\ 2\ weeks"\f[] \-\- starts on closest preceeding Monday +T} +T{ +\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \-\- 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[] \-\- periods will go from Tue +to Tue +T} +T{ +\f[C]\-p\ "every\ Tue"\f[] \-\- same +T} +T{ +\f[C]\-p\ "every\ 15th\ day"\f[] \-\- period boundaries will be on 15th +of each month +T} +T{ +\f[C]\-p\ "every\ 2nd\ Monday"\f[] \-\- period boundaries will be on +second Monday of each month +T} +T{ +\f[C]\-p\ "every\ 11/05"\f[] \-\- yearly periods with boundaries on 5th +of Nov +T} +T{ +\f[C]\-p\ "every\ 5th\ Nov"\f[] \-\- same +T} +T{ +\f[C]\-p\ "every\ Nov\ 5th"\f[] \-\- 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\[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 reported amounts to their +current market value. +.PD 0 +.P +.PD +Specifically, when there is a market price (P directive) for the +amount\[aq]s commodity, dated on or before today\[aq]s date (or the +report end date if specified), the amount will be converted to the +price\[aq]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\ \-N\ euros +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi +.PP +What are they worth at end of nov 3 ? +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V\ \-e\ 2016/11/4 +\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros +\f[] +.fi +.PP +What are they worth after 2016/12/21 ? +(no report end date specified, defaults to today) +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V +\ \ \ \ \ \ \ \ \ \ \ \ \ $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 +Currently, \-V has a limitation in multicolumn balance reports: it uses +the market prices on the report end date for all columns. +(Instead of the prices on each column\[aq]s end date.) +.SS Combining \-B and \-V +.PP +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. +.SS Output destination +.PP +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. +This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) +$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE +\f[] +.fi +.SS Output format +.PP +Some commands can write their output in other formats. +Eg print and register can output CSV, and the balance commands can +output CSV or HTML. +This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by +specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with +\f[C]\-o/\-\-output\-file\f[]. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout +$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv +\f[] +.fi +.SS Regular expressions +.PP +hledger uses regular expressions in a number of places: +.IP \[bu] 2 +query terms, on the command line and in the hledger\-web search form: +\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[], +\f[C]tag:...=REGEX\f[] +.IP \[bu] 2 +CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[] +.IP \[bu] 2 +account alias directives and options: +\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[], +\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[] +.PP +hledger\[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[BC]not:\f[B]\f[], eg to +exclude a particular subaccount. +.TP +.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[] +match account names by this regular expression. +(With no prefix, \f[C]acct:\f[] is assumed.) +.RS +.RE +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\[aq]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\[aq]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 +accounts, a +.PD 0 +.P +.PD +Show account names. +.PP +This command lists account names, either declared with account +directives (\-\-declared), posted to (\-\-used), or both (the default). +With query arguments, only matched account names and account names +referenced by matched postings are shown. +It shows a flat list by default. +With \f[C]\-\-tree\f[], it uses indentation to show the account +hierarchy. +In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few +account name components. +Account names can be depth\-clipped with \f[C]depth:N\f[] or +\f[C]\-\-depth\ N\f[] or \f[C]\-N\f[]. +.PP +Examples: +.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 +activity +.PD 0 +.P +.PD +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. +.PP +Examples: +.IP +.nf +\f[C] +$\ hledger\ activity\ \-\-quarterly +2008\-01\-01\ ** +2008\-04\-01\ ******* +2008\-07\-01\ +2008\-10\-01\ ** +\f[] +.fi +.SS add +.PP +add +.PD 0 +.P +.PD +Prompt for transactions and add them to the journal. +.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 (by +description) recent transaction (filtered by the query, if any) 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 +balance, bal, b +.PD 0 +.P +.PD +Show accounts and their balances. +.PP +The balance command is hledger\[aq]s most versatile command. +Note, despite the name, it is not always used for showing real\-world +account balances; the more accounting\-aware balancesheet and +incomestatement may be more convenient for that. +.PP +By default, it displays all accounts, and each account\[aq]s change in +balance during the entire period of the journal. +Balance changes are calculated by adding up the postings in each +account. +You can limit the postings matched, by a query, to see fewer accounts, +changes over a different time period, changes from only cleared +transactions, etc. +.PP +If you include an account\[aq]s complete history of postings in the +report, the balance change is equivalent to the account\[aq]s current +ending balance. +For a real\-world account, typically you won\[aq]t have all transactions +in the journal; instead you\[aq]ll have all transactions after a certain +date, and an "opening balances" transaction setting the correct starting +balance on that date. +Then the balance command will show real\-world account balances. +In some cases the \-H/\-\-historical flag is used to ensure this (more +below). +.PP +The balance command can produce several styles of report: +.SS Classic balance report +.PP +This is the original balance report, as found in Ledger. +It usually looks like this: +.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 +By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. +At each level of the tree, accounts are sorted by account code if any, +then by account name. +Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. +.PP +"Boring" accounts, which contain a single interesting subaccount and no +balance of their own, are elided into the following line for more +compact output. +(Eg above, the "liabilities" account.) Use \f[C]\-\-no\-elide\f[] to +prevent this. +.PP +Account balances are "inclusive" \- they include the balances of any +subaccounts. +.PP +Accounts which have zero balance (and no non\-zero subaccounts) are +omitted. +Use \f[C]\-E/\-\-empty\f[] to show them. +.PP +A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to +suppress it, eg: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\f[] +.fi +.SS Customising the classic balance report +.PP +You can customise the layout of classic balance reports with +\f[C]\-\-format\ FMT\f[]: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-format\ "%20(account)\ %12(total)" +\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ \ \ \ \ \ \ bank:saving\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ cash\ \ \ \ \ \ \ \ \ \ $\-2 +\ \ \ \ \ \ \ \ \ \ \ \ expenses\ \ \ \ \ \ \ \ \ \ \ $2 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ food\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ supplies\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ income\ \ \ \ \ \ \ \ \ \ $\-2 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ gifts\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ salary\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ $1 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. +It may contain any suitable text, with data fields interpolated like so: +.PP +\f[C]%[MIN][.MAX](FIELDNAME)\f[] +.IP \[bu] 2 +MIN pads with spaces to at least this width (optional) +.IP \[bu] 2 +MAX truncates at this width (optional) +.IP \[bu] 2 +FIELDNAME must be enclosed in parentheses, and can be one of: +.RS 2 +.IP \[bu] 2 +\f[C]depth_spacer\f[] \- a number of spaces equal to the account\[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 Flat mode +.PP +To see a flat list instead of the default hierarchical display, use +\f[C]\-\-flat\f[]. +In this mode, accounts (unless depth\-clipped) show their full names and +"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[] or \f[C]depth:N\f[] or just \f[C]\-N\f[], +balance reports show accounts only to the specified numeric depth. +This is very useful to summarise a complex set of accounts and get an +overview. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-N\ \-1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities +\f[] +.fi +.PP +Flat\-mode balance reports, which normally show exclusive balances, show +inclusive balances at the depth limit. +.SS Multicolumn balance report +.PP +Multicolumn or tabular balance reports are a very useful hledger +feature, and usually the preferred style. +They share many of the above features, but they show the report as a +table, with columns representing time periods. +This mode is activated by providing a reporting interval. +.PP +There are three types of multicolumn 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 +Multicolumn 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). +With \f[C]\-\-budget\f[], \f[C]\-\-empty\f[] also shows unbudgeted +accounts. +.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 +.PP +Limitations: +.PP +In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market +price on the report end date, for all columns (not the price on each +column\[aq]s end date). +.PP +Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. +.SS Budget report +.PP +With \f[C]\-\-budget\f[], extra columns are displayed showing budget +goals for each account and period, if any. +Budget goals are defined by periodic transactions. +This is very useful for comparing planned and actual income, expenses, +time usage, etc. +\-\-budget is most often combined with a report interval. +.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 report: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ \ $53\ [\ 106%\ of\ \ \ \ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $412\ [\ 103%\ of\ \ \ $400]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ \ \ 0\ [\ \ \ 0%\ of\ \ \ \ $30]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $2100\ [\ 105%\ of\ \ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +By default, only accounts with budget goals during the report period are +shown. +In the example above, transactions in \f[C]expenses:gifts\f[] and +\f[C]expenses:supplies\f[] are counted towards \f[C]expenses\f[] budget, +but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are +not shown, as they don\[aq]t have any budgets. +.PP +You can use \f[C]\-\-empty\f[] shows unbudgeted accounts as well: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget\ \-\-empty +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ \ $53\ [\ 106%\ of\ \ \ \ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $412\ [\ 103%\ of\ \ \ $400]\ +\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ \ \ 0\ [\ \ \ 0%\ of\ \ \ \ $30]\ +\ expenses:supplies\ \ \ \ ||\ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $2100\ [\ 105%\ of\ \ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\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 +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ $1060\ [\ 110%\ of\ \ \ $960]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ $102\ [\ 102%\ of\ \ \ $100]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $808\ [\ 101%\ of\ \ \ $800]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ $30\ [\ \ 50%\ of\ \ \ \ $60]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $4050\ [\ 101%\ of\ \ $4000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported +with \f[C]\-\-budget\f[]. +.PP +For more examples, see Budgeting and Forecasting. +.SS Nested budgets +.PP +You can add budgets to any account in your account hierarchy. +If you have budgets on both parent account and some of its children, +then budget(s) of the child account(s) would be added to the budget of +their parent, much like account balances behave. +.PP +In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. +.PP +To illustrate this, consider the following budget: +.IP +.nf +\f[C] +~\ monthly\ from\ 2019/01 +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 +\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 +\ \ \ \ liabilities +\f[] +.fi +.PP +With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both \f[C]expenses:personal\f[] and +\f[C]expenses\f[] is $1100. +.PP +Transactions in \f[C]expenses:personal:electronics\f[] will be counted +both towards its $100 budget and $1100 of \f[C]expenses:personal\f[] , +and transactions in any other subaccount of \f[C]expenses:personal\f[] +would be counted towards only towards the budget of +\f[C]expenses:personal\f[]. +.PP +For example, let\[aq]s consider these transactions: +.IP +.nf +\f[C] +~\ monthly\ from\ 2019/01 +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 +\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 +\ \ \ \ liabilities + +2019/01/01\ Google\ home\ hub +\ \ \ \ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ $90.00 +\ \ \ \ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-90.00 + +2019/01/02\ Phone\ screen\ protector +\ \ \ \ expenses:personal:electronics:upgrades\ \ \ \ \ \ \ \ \ \ $10.00 +\ \ \ \ liabilities + +2019/01/02\ Weekly\ train\ ticket +\ \ \ \ expenses:personal:train\ tickets\ \ \ \ \ \ \ $153.00 +\ \ \ \ liabilities + +2019/01/03\ Flowers +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ $30.00 +\ \ \ \ liabilities +\f[] +.fi +.PP +As you can see, we have transactions in +\f[C]expenses:personal:electronics:upgrades\f[] and +\f[C]expenses:personal:train\ tickets\f[], and since both of these +accounts are without explicitly defined budget, these transactions would +be counted towards budgets of \f[C]expenses:personal:electronics\f[] and +\f[C]expenses:personal\f[] accordingly: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-M +Budget\ performance\ in\ 2019/01: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ +===============================++=============================== +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal:electronics\ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ +\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +And with \f[C]\-\-empty\f[], we can get a better picture of budget +allocation and consumption: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-M\ \-\-empty +Budget\ performance\ in\ 2019/01: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ +========================================++=============================== +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ +\ expenses:personal:electronics:upgrades\ ||\ \ \ $10.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ expenses:personal:train\ tickets\ \ \ \ \ \ \ \ ||\ \ $153.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.SS Output format +.PP +The balance command supports output destination and output format +selection. +.SS balancesheet +.PP +balancesheet, bs +.PD 0 +.P +.PD +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). +It assumes that these accounts are under a top\-level \f[C]asset\f[] or +\f[C]liability\f[] account (case insensitive, plural forms also +allowed). +.PP +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ balancesheet +Balance\ Sheet + +Assets: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +Liabilities: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +As with multicolumn balance reports, you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +Normally balancesheet shows historical ending balances, which is what +you need for a balance sheet; note this means it ignores report begin +dates. +.PP +This command also supports output destination and output format +selection. +.SS balancesheetequity +.PP +balancesheetequity, bse +.PD 0 +.P +.PD +Just like balancesheet, but also reports Equity (which it assumes is +under a top\-level \f[C]equity\f[] account). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ balancesheetequity +Balance\ Sheet\ With\ Equity + +Assets: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-3\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +Liabilities: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 + +Equity: +\ \ \ \ \ \ \ \ \ \ $1\ \ equity:owner +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ $1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.SS cashflow +.PP +cashflow, cf +.PD 0 +.P +.PD +This command displays a simple cashflow statement, showing changes in +"cash" accounts. +It assumes that these accounts are under a top\-level \f[C]asset\f[] +account (case insensitive, plural forms also allowed) and do not contain +\f[C]receivable\f[] or \f[C]A/R\f[] in their name. +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ cashflow +Cashflow\ Statement + +Cash\ flows: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +Normally cashflow shows changes in assets per period, though as with +multicolumn balance reports you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. +.SS check\-dates +.PP +check\-dates +.PD 0 +.P +.PD +Check that transactions are sorted by increasing date. +With \-\-date2, checks secondary dates instead. +With \-\-strict, dates must also be unique. +With a query, only matched transactions\[aq] dates are checked. +Reads the default journal file, or another specified with \-f. +.SS check\-dupes +.PP +check\-dupes +.PD 0 +.P +.PD +Reports account names having the same leaf but different prefixes. +In other words, two or more leaves that are categorized differently. +Reads the default journal file, or another specified as an argument. +.PP +An example: http://stefanorodighiero.net/software/hledger\-dupes.html +.SS close +.PP +close, equity +.PD 0 +.P +.PD +Prints a "closing balances" transaction and an "opening balances" +transaction that bring account balances to and from zero, respectively. +Useful for bringing asset/liability balances forward into a new journal +file, or for closing out revenues/expenses to retained earnings at the +end of a period. +.PP +The closing transaction transfers balances to "equity:closing balances". +The opening transaction transfers balances from "equity:opening +balances". +You can chose to print just one of the transactions by using the +\f[C]\-\-opening\f[] or \f[C]\-\-closing\f[] flag. +.PP +If you split your journal files by time (eg yearly), you will typically +run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. +This makes the files self contained, so that correct balances are +reported no matter which of them are loaded. +Ie, if you load just one file, the balances are initialised correctly; +or if you load several files, the redundant closing/opening transactions +cancel each other out. +(They will show up in print or register reports; you can exclude them +with a query like +\f[C]not:desc:\[aq](opening|closing)\ balances\[aq]\f[].) +.PP +If you\[aq]re running a business, you might also use this command to +"close the books" at the end of an accounting period, transferring +income statement account balances to retained earnings. +(You may want to change the equity account name to something like +"equity:retained earnings".) +.PP +By default, the closing transaction is dated yesterday, the balances are +calculated as of end of yesterday, and the opening transaction is dated +today. +To close on some other date, use: +\f[C]hledger\ close\ \-e\ OPENINGDATE\f[]. +Eg, to close/open on the 2018/2019 boundary, use \f[C]\-e\ 2019\f[]. +You can also use \-p or \f[C]date:PERIOD\f[] (any starting date is +ignored). +.PP +Both transactions will include balance assertions for the +closed/reopened accounts. +You probably shouldn\[aq]t use status or realness filters (like \-C or +\-R or \f[C]status:\f[]) with this command, or the generated balance +assertions will depend on these flags. +Likewise, if you run this command with \-\-auto, the balance assertions +will probably always require \-\-auto. +.PP +Examples: +.PP +Carrying asset/liability balances into a new file for 2019, all from +command line: +.PP +\f[I]Warning: we use \f[CI]>>\f[I] here to append; be careful not to +type a single \f[CI]>\f[I] which would wipe your journal!\f[] +.IP +.nf +\f[C] +$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-opening\ >>2019.journal +$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-closing\ >>2018.journal +\f[] +.fi +.PP +Now: +.IP +.nf +\f[C] +$\ hledger\ bs\ \-f\ 2019.journal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ one\ file\ \-\ balances\ are\ correct +$\ hledger\ bs\ \-f\ 2018.journal\ \-f\ 2019.journal\ \ \ #\ two\ files\ \-\ balances\ still\ correct +$\ hledger\ bs\ \-f\ 2018.journal\ not:desc:closing\ \ #\ to\ see\ year\-end\ balances,\ must\ exclude\ closing\ txn +\f[] +.fi +.PP +Transactions spanning the closing date can complicate matters, breaking +balance assertions: +.IP +.nf +\f[C] +2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5 +\ \ \ \ assets:bank:checking\ \ \-5\ \ ;\ [2019/1/2] +\f[] +.fi +.PP +Here\[aq]s one way to resolve that: +.IP +.nf +\f[C] +;\ in\ 2018.journal: +2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5 +\ \ \ \ liabilities:pending + +;\ in\ 2019.journal: +2019/1/2\ clearance\ of\ last\ year\[aq]s\ pending\ transactions +\ \ \ \ liabilities:pending\ \ \ \ 5\ =\ 0 +\ \ \ \ assets:checking +\f[] +.fi +.SS files +.PP +files +.PD 0 +.P +.PD +List all files included in the journal. +With a REGEX argument, only file names matching the regular expression +(case sensitive) are shown. +.SS help +.PP +help +.PD 0 +.P +.PD +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. +.PP +Examples: +.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 +import +.PD 0 +.P +.PD +Read new transactions added to each FILE since last run, and add them to +the main journal file. +Or with \-\-dry\-run, just print the transactions that would be added. +.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\[aq]s just: \f[C]hledger\ import\ *.csv\f[] +.PP +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 \f[C]\&.latest.FILE\f[] state files. +.PP +The \-\-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 +incomestatement, is +.PD 0 +.P +.PD +This command displays a simple income statement, showing revenues and +expenses during a period. +It assumes that these accounts are under a top\-level \f[C]revenue\f[] +or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural +forms also allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +.PP +This command displays a simple income statement. +It currently assumes that you have top\-level accounts named +\f[C]income\f[] (or \f[C]revenue\f[]) and \f[C]expense\f[] (plural forms +also allowed.) +.IP +.nf +\f[C] +$\ hledger\ incomestatement +Income\ Statement + +Revenues: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +Expenses: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +Normally incomestatement shows revenues/expenses per period, though as +with multicolumn balance reports you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. +.SS prices +.PP +prices +.PD 0 +.P +.PD +Print market price directives from the journal. +With \-\-costs, also print synthetic market prices based on transaction +prices. +With \-\-inverted\-costs, also print inverse prices based on transaction +prices. +Prices (and postings providing prices) can be filtered by a query. +.SS print +.PP +print, txns, p +.PD 0 +.P +.PD +Show transaction journal entries, sorted by date. +.PP +The print command displays full journal entries (transactions) from the +journal file in date order, tidily formatted. +With \-\-date2, transactions are sorted by secondary date instead. +.PP +print\[aq]s output is always a valid hledger journal. +.PD 0 +.P +.PD +It preserves all transaction information, but it does not preserve +directives or inter\-transaction comments +.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 +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. +This can be used for troubleshooting. +.PP +With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show +at most one transaction: the one one whose description is most similar +to STR, and is most recent. +STR should contain at least two characters. +If there is no similar\-enough match, no transaction will be shown. +.PP +With \f[C]\-\-new\f[], for each FILE being read, hledger reads (and +writes) a special state file (\f[C]\&.latest.FILE\f[] in the same +directory), containing the latest transaction date(s) that were seen +last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. +This is useful for ignoring already\-seen entries in import data, such +as downloaded CSV files. +Eg: +.IP +.nf +\f[C] +$\ hledger\ \-f\ bank1.csv\ print\ \-\-new +#\ shows\ transactions\ added\ since\ last\ print\ \-\-new\ on\ this\ file +\f[] +.fi +.PP +This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. +See also the import command. +.PP +This command also supports output destination and output format +selection. +Here\[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\-unique +.PD 0 +.P +.PD +Print transactions which do not reuse an already\-seen description. +.PP +Example: +.IP +.nf +\f[C] +$\ cat\ unique.journal +1/1\ test +\ (acct:one)\ \ 1 +2/2\ test +\ (acct:two)\ \ 2 +$\ LEDGER_FILE=unique.journal\ hledger\ print\-unique +(\-f\ option\ not\ supported) +2015/01/01\ test +\ \ \ \ (acct:one)\ \ \ \ \ \ \ \ \ \ \ \ \ 1 +\f[] +.fi +.SS register +.PP +register, reg, r +.PD 0 +.P +.PD +Show postings and their running total. +.PP +The register command displays postings in date order, 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 +With \-\-date2, it shows and sorts by secondary date instead. +.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 (won\[aq]t display correctly in \-\-help): +.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,\ &\ description\ width\ 40 +\f[] +.fi +.PP +This command also supports output destination and output format +selection. +.SS register\-match +.PP +register\-match +.PD 0 +.P +.PD +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. +If there are multiple equally good matches, it shows the most recent. +Query options (options, not arguments) can be used to restrict the +search space. +Helps ledger\-autosync detect already\-seen transactions when importing. +.SS rewrite +.PP +rewrite +.PD 0 +.P +.PD +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +\-\-auto. +.PP +This is a start at a generic rewriter of transaction entries. +It reads the default journal and prints the transactions, like print, +but adds one or more specified postings to any transactions matching +QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction\[aq]s first posting amount. +.PP +Examples: +.IP +.nf +\f[C] +hledger\-rewrite.hs\ ^income\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\ \ ;\ income\ tax\[aq]\ \-\-add\-posting\ \[aq](reserve:gifts)\ \ $100\[aq] +hledger\-rewrite.hs\ expenses:gifts\ \-\-add\-posting\ \[aq](reserve:gifts)\ \ *\-1"\[aq] +hledger\-rewrite.hs\ \-f\ rewrites.hledger +\f[] +.fi +.PP +rewrites.hledger may consist of entries like: +.IP +.nf +\f[C] +=\ ^income\ amt:<0\ date:2017 +\ \ (liabilities:tax)\ \ *0.33\ \ ;\ tax\ on\ income +\ \ (reserve:grocery)\ \ *0.25\ \ ;\ reserve\ 25%\ for\ grocery +\ \ (reserve:)\ \ *0.25\ \ ;\ reserve\ 25%\ for\ grocery +\f[] +.fi +.PP +Note the single quotes to protect the dollar sign from bash, and the two +spaces between account and amount. +.PP +More: +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ [QUERY]\ \ \ \ \ \ \ \ \-\-add\-posting\ "ACCT\ \ AMTEXPR"\ ... +$\ hledger\ rewrite\ \-\-\ ^income\ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq] +$\ hledger\ rewrite\ \-\-\ expenses:gifts\ \-\-add\-posting\ \[aq](budget:gifts)\ \ *\-1"\[aq] +$\ hledger\ rewrite\ \-\-\ ^income\ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq](budget:foreign\ currency)\ \ *0.25\ JPY;\ diversify\[aq] +\f[] +.fi +.PP +Argument for \f[C]\-\-add\-posting\f[] option is a usual posting of +transaction with an exception for amount specification. +More precisely, you can use \f[C]\[aq]*\[aq]\f[] (star symbol) before +the amount to indicate that that this is a factor for an amount of +original matched posting. +If the amount includes a commodity name, the new posting amount will be +in the new commodity; otherwise, it will be in the matched posting +amount\[aq]s commodity. +.SS Re\-write rules in a file +.PP +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. +I.e instead of specifying this operations in command line you can put +them in a journal file. +.IP +.nf +\f[C] +$\ rewrite\-rules.journal +\f[] +.fi +.PP +Make contents look like this: +.IP +.nf +\f[C] +=\ ^income +\ \ \ \ (liabilities:tax)\ \ *.33 + +=\ expenses:gifts +\ \ \ \ budget:gifts\ \ *\-1 +\ \ \ \ assets:budget\ \ *1 +\f[] +.fi +.PP +Note that \f[C]\[aq]=\[aq]\f[] (equality symbol) that is used instead of +date in transactions you usually write. +It indicates the query by which you want to match the posting to add new +ones. +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-f\ input.journal\ \-f\ rewrite\-rules.journal\ >\ rewritten\-tidy\-output.journal +\f[] +.fi +.PP +This is something similar to the commands pipeline: +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-f\ input.journal\ \[aq]^income\[aq]\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq]\ \\ +\ \ |\ hledger\ rewrite\ \-\-\ \-f\ \-\ expenses:gifts\ \ \ \ \ \ \-\-add\-posting\ \[aq]budget:gifts\ \ *\-1\[aq]\ \ \ \ \ \ \ \\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq]assets:budget\ \ *1\[aq]\ \ \ \ \ \ \ \\ +\ \ >\ rewritten\-tidy\-output.journal +\f[] +.fi +.PP +It is important to understand that relative order of such entries in +journal is important. +You can re\-use result of previously added postings. +.SS Diff output format +.PP +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-\-diff\ \-f\ examples/sample.journal\ \[aq]^income\[aq]\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq] +\f[] +.fi +.PP +Output might look like: +.IP +.nf +\f[C] +\-\-\-\ /tmp/examples/sample.journal ++++\ /tmp/examples/sample.journal +\@\@\ \-18,3\ +18,4\ \@\@ +\ 2008/01/01\ income +\-\ \ \ \ assets:bank:checking\ \ $1 ++\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ income:salary ++\ \ \ \ (liabilities:tax)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\@\@\ \-22,3\ +23,4\ \@\@ +\ 2008/06/01\ gift +\-\ \ \ \ assets:bank:checking\ \ $1 ++\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ income:gifts ++\ \ \ \ (liabilities:tax)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +If you\[aq]ll pass this through \f[C]patch\f[] tool you\[aq]ll get +transactions containing the posting that matches your query be updated. +Note that multiple files might be update according to list of input +files specified via \f[C]\-\-file\f[] options and \f[C]include\f[] +directives inside of these files. +.PP +Be careful. +Whole transaction being re\-formatted in a style of output from +\f[C]hledger\ print\f[]. +.PP +See also: +.PP +https://github.com/simonmichael/hledger/issues/99 +.SS rewrite vs. print \-\-auto +.PP +This command predates print \-\-auto, and currently does much the same +thing, but with these differences: +.IP \[bu] 2 +with multiple files, rewrite lets rules in any file affect all other +files. +print \-\-auto uses standard directive scoping; rules affect only child +files. +.IP \[bu] 2 +rewrite\[aq]s query limits which transactions can be rewritten; all are +printed. +print \-\-auto\[aq]s query limits which transactions are printed. +.IP \[bu] 2 +rewrite applies rules specified on command line or in the journal. +print \-\-auto applies rules specified in the journal. +.SS roi +.PP +roi +.PD 0 +.P +.PD +Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return +on your investments. +.PP +This command assumes that you have account(s) that hold nothing but your +investments and whenever you record current appraisal/valuation of these +investments you offset unrealized profit and loss into account(s) that, +again, hold nothing but unrealized profit and loss. +.PP +Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. +.PP +At a minimum, you need to supply a query (which could be just an account +name) to select your investments with \f[C]\-\-inv\f[], and another +query to identify your profit and loss transactions with +\f[C]\-\-pnl\f[]. +.PP +It will compute and display the internalized rate of return (IRR) and +time\-weighted rate of return (TWR) for your investments for the time +period requested. +Both rates of return are annualized before display, regardless of the +length of reporting interval. +.SS stats +.PP +stats +.PD 0 +.P +.PD +Show some journal statistics. +.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 +Example: +.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 +This command also supports output destination and output format +selection. +.SS tags +.PP +tags +.PD 0 +.P +.PD +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. +.SS test +.PP +test +.PD 0 +.P +.PD +Run built\-in unit tests. +.PP +This command runs the unit tests built in to hledger\-lib and hledger, +printing test names and results on stdout. +If any test fails, the exit code will be non\-zero. +.PP +Test names include a group prefix. +If a (exact, case sensitive) group prefix, or a full test name is +provided as the first argument, only that group or test is run. +.PP +If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). +.PP +This is mainly used by developers, but it\[aq]s nice to be able to +sanity\-check your installed hledger executable at any time. +All tests are expected to pass \- if you ever see otherwise, something +has gone wrong, please report a bug! +.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, but it\[aq]s superseded now by the built\-in roi command. +.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 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] diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -3,2703 +3,2835 @@  File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.12 -*********************** - -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 in arguments and queries:: -* Command line tips:: -* Unicode characters:: -* Input files:: -* Smart dates:: -* Report start & end date:: -* Report intervals:: -* Period expressions:: -* Depth limiting:: -* Pivoting:: -* Cost:: -* Market value:: -* Combining -B and -V:: -* Output destination:: -* Output format:: -* Regular expressions:: - - -File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS - -2.1 General options -=================== - -To see general usage help, including general options which are supported -by most hledger commands, run 'hledger -h'. - - General help options: - -'-h --help' - - show general usage (or after COMMAND, command usage) -'--version' - - show version -'--debug[=N]' - - show debug output (levels 1-9, default: 1) - - General input options: - -'-f FILE --file=FILE' - - use a different input file. For stdin, use - (default: - '$LEDGER_FILE' or '$HOME/.hledger.journal') -'--rules-file=RULESFILE' - - Conversion rules file to use when reading CSV (default: FILE.rules) -'--separator=CHAR' - - Field separator to expect when reading CSV (default: ',') -'--alias=OLD=NEW' - - rename accounts named OLD to NEW -'--anon' - - anonymize accounts and payees -'--pivot FIELDNAME' - - use some other field or tag for the account name -'-I --ignore-assertions' - - ignore any failing balance assertions - - General reporting options: - -'-b --begin=DATE' - - include postings/txns on or after this date -'-e --end=DATE' - - include postings/txns before this date -'-D --daily' - - multiperiod/multicolumn report by day -'-W --weekly' - - multiperiod/multicolumn report by week -'-M --monthly' - - multiperiod/multicolumn report by month -'-Q --quarterly' - - multiperiod/multicolumn report by quarter -'-Y --yearly' - - multiperiod/multicolumn report by year -'-p --period=PERIODEXP' - - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) -'--date2' - - match the secondary date instead (see command help for other - effects) -'-U --unmarked' - - include only unmarked postings/txns (can combine with -P or -C) -'-P --pending' - - include only pending postings/txns -'-C --cleared' - - include only cleared postings/txns -'-R --real' - - include only non-virtual postings -'-NUM --depth=NUM' - - hide/aggregate accounts or postings more than NUM levels deep -'-E --empty' - - show items with zero amount, normally hidden (and vice-versa in - hledger-ui/hledger-web) -'-B --cost' - - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' - - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) -'--auto' - - apply automated posting rules to modify transactions. -'--forecast' - - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, -the last one takes precedence. - - Some reporting options can also be written as query arguments. - - -File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS - -2.2 Command options -=================== - -To see options for a particular command, including command-specific -options, run: 'hledger COMMAND -h'. - - Command-specific options must be written after the command name, eg: -'hledger print -x'. - - Additionally, if the command is an addon, you may need to put its -options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can -run the addon executable directly: 'hledger-ui --watch'. - - -File: hledger.info, Node: Command arguments, Next: Argument files, Prev: Command options, Up: OPTIONS - -2.3 Command arguments -===================== - -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. - - -File: hledger.info, Node: Argument files, Next: Special characters in arguments and queries, 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 in arguments and queries, Next: Command line tips, Prev: Argument files, Up: OPTIONS - -2.5 Special characters in arguments and queries -=============================================== - -In shell command lines, option and argument values which contain -"problematic" characters, ie spaces, and also characters significant to -your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by -enclosing them in quotes or by writing backslashes before the -characters. Eg: - - 'hledger register -p 'last year' "accounts receivable -(receivable|payable)" amt:\>100'. -* Menu: - -* More escaping:: -* Even more escaping:: -* Less escaping:: - - -File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries - -2.5.1 More escaping -------------------- - -Characters significant both to the shell and in regular expressions may -need one extra level of escaping. 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:\\$' - - -File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries - -2.5.2 Even more escaping ------------------------- - -When hledger runs an addon executable (eg you type 'hledger ui', hledger -runs 'hledger-ui'), it de-escapes command-line options and arguments -once, so you might need to _triple_-escape. Eg in bash, running the ui -command and matching the dollar sign, it's: - - 'hledger ui cur:'\\$'' - - or: - - 'hledger ui cur:\\\\$' - - If you asked why _four_ slashes above, this may help: - -unescaped: '$' -escaped: '\$' -double-escaped: '\\$' -triple-escaped: '\\\\$' - - (The number of backslashes in fish shell is left as an exercise for -the reader.) - - You can always avoid the extra escaping for addons by running the -addon directly: - - 'hledger-ui cur:\\$' - - -File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries - -2.5.3 Less escaping -------------------- - -Inside an argument file, or in the search field of hledger-ui or -hledger-web, or at a GHCI prompt, you need one less level of escaping -than at the command line. And backslashes may work better than quotes. -Eg: - - 'ghci> :main balance cur:\$' - - -File: hledger.info, Node: Command line tips, Next: Unicode characters, Prev: Special characters in arguments and queries, Up: OPTIONS - -2.6 Command line tips -===================== - -If in doubt, keep things simple: - - * write options after the command ('hledger CMD -OPTIONS ARGS') - * run add-on executables directly ('hledger-ui -OPTIONS ARGS') - * enclose problematic args in single quotes - * if needed, also add a backslash to escape regexp metacharacters - - To find out exactly how a command line is being parsed, add -'--debug=2' to troubleshoot. - - -File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Command line tips, Up: OPTIONS - -2.7 Unicode characters -====================== - -hledger is expected to handle unicode (non-ascii) characters, but this -requires a well-configured environment. - - To handle unicode characters in the command line or input data, a -system locale that can decode them must be configured (POSIX's default -'C' locale will not work). Eg in bash, you could do: - -export LANG=en_US.UTF-8 - - See Troubleshooting for more about this. - - Unicode characters should appear correctly in hledger's output. For -the hledger and hledger-ui tools, this requires that - - * your terminal supports unicode - * the terminal's font includes the required unicode glyphs - * the terminal is configured to display "wide" characters as double - width (otherwise report alignment will be off) - - -File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS - -2.8 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.9 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: - -'2004/10/1', '2004-01-01', '2004.9.1' exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 -'2004' start of year -'2004/10' start of month -'10/1' month and day in current year -'21' day in current month -'october, oct' start of month in current year -'yesterday, today, tomorrow' -1, 0, 1 days from today -'last/this/next -1, 0, 1 periods from the current period -day/week/month/quarter/year' -'20181201' 8 digit YYYYMMDD with valid year month and day -'201812' 6 digit YYYYMM with valid year and month - - Counterexamples - malformed digit sequences might give surprising -results: - -'201813' 6 digits with an invalid month is parsed as start of 6-digit year -'20181301' 8 digits with an invalid month is parsed as start of 8-digit year -'20181232' 8 digits with an invalid day gives an error -'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error - - -File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS - -2.10 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.11 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.12 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.13 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.14 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.15 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.16 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 -N euros - €100 assets:euros - - What are they worth at end of nov 3 ? - -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date -specified, defaults to today) - -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - Currently, hledger's -V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). - - Currently, -V has a limitation in multicolumn balance reports: it -uses the market prices on the report end date for all columns. (Instead -of the prices on each column's end date.) - - -File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS - -2.17 Combining -B and -V -======================== - -Using -B/-cost and -V/-value together is currently allowed, but the -results are probably not meaningful. Let us know if you find a use for -this. - - -File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS - -2.18 Output destination -======================= - -Some commands (print, register, stats, the balance commands) can write -their output to a destination other than the console. This is -controlled by the '-o/--output-file' option. - -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE - - -File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS - -2.19 Output format -================== - -Some commands can write their output in other formats. Eg print and -register can output CSV, and the balance commands can output CSV or -HTML. This is controlled by the '-O/--output-format' option, or by -specifying a '.csv' or '.html' file extension with '-o/--output-file'. - -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv - - -File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS - -2.20 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', 'acct:REGEX'* - - match account names by this regular expression. (With no prefix, - 'acct:' is assumed.) same as above - -*'amt:N, amt:N, amt:>=N'* - - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not - tested, and will always match.) The comparison has two modes: if N - is preceded by a + or - sign (or is 0), the two signed numbers are - compared. Otherwise, the absolute magnitudes are compared, - ignoring sign. -*'code:REGEX'* - - match by transaction code (eg check number) -*'cur:REGEX'* - - match postings or transactions including any amounts whose - currency/commodity symbol is fully matched by REGEX. (For a partial - match, use '.*REGEX.*'). Note, to match characters which are - regex-significant, like the dollar sign ('$'), you need to prepend - '\'. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: 'hledger - print cur:'\$'' or 'hledger print cur:\\$'. -*'desc:REGEX'* - - match transaction descriptions. -*'date:PERIODEXPR'* - - match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: 'date:2016', - 'date:thismonth', 'date:2000/2/1-2/15', 'date:lastweek-'. If the - '--date2' command line flag is present, this matches secondary - dates instead. -*'date2:PERIODEXPR'* - - match secondary dates within the specified period. -*'depth:N'* - - match (or display, depending on command) accounts at or above this - depth -*'note:REGEX'* - - match transaction notes (part of description right of '|', or whole - description when there's no '|') -*'payee:REGEX'* - - match transaction payee/payer names (part of description left of - '|', or whole description when there's no '|') -*'real:, real:0'* - - match real or virtual postings respectively -*'status:, status:!, status:*'* - - match unmarked, pending, or cleared transactions respectively -*'tag:REGEX[=REGEX]'* - - match by tag name, and optionally also by tag value. Note a tag: - query is considered to match a transaction if it matches any of the - postings. Also remember that postings inherit the tags of their - parent transaction. - - The following special search term is used automatically in -hledger-web, only: - -*'inacct:ACCTNAME'* - - tells hledger-web to show the transaction register for this - account. Can be filtered further with 'acct' etc. - - Some of these can also be expressed as command-line options (eg -'depth:2' is equivalent to '--depth 2'). Generally you can mix options -and query arguments, and the resulting query will be their intersection -(perhaps excluding the '-p/--period' option). - - -File: hledger.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top - -4 COMMANDS -********** - -hledger provides a number of subcommands; 'hledger' with no arguments -shows a list. - - If you install additional 'hledger-*' packages, or if you put -programs or scripts named 'hledger-NAME' in your PATH, these will also -be listed as subcommands. - - Run a subcommand by writing its name as first argument (eg 'hledger -incomestatement'). You can also write one of the standard short aliases -displayed in parentheses in the command list ('hledger b'), or any any -unambiguous prefix of a command name ('hledger inc'). - - Here are all the builtin commands in alphabetical order. See also -'hledger' for a more organised command list, and 'hledger CMD -h' for -detailed command help. -* Menu: - -* accounts:: -* activity:: -* add:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check-dates:: -* check-dupes:: -* close:: -* files:: -* help:: -* import:: -* incomestatement:: -* prices:: -* print:: -* print-unique:: -* register:: -* register-match:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: - - -File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS - -4.1 accounts -============ - -Show account names. Alias: a. - -'--declared' - - show account names declared with account directives -'--used' - - show account names posted to by transactions -'--tree' - - show short account names and their parents, as a tree -'--flat' - - show full account names, as a list (default) -'--drop=N' - - in flat mode: omit N leading account name parts - - This command lists account names, either declared with account -directives (-declared), posted to (-used), or both (default). With -query arguments, only matched account names and account names referenced -by matched postings are shown. It shows a flat list by default. With -'--tree', it uses indentation to show the account hierarchy. In flat -mode you can add '--drop N' to omit the first few account name -components. Account names can be depth-clipped with '--depth N' or -depth:N. - - Examples: - -$ hledger accounts --tree -assets - bank - checking - saving - cash -expenses - food - supplies -income - gifts - salary -liabilities - debts - -$ hledger accounts --drop 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS - -4.2 activity -============ - -Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS - -4.3 add -======= - -Prompt for transactions and add them to the journal. - -'--no-new-accounts' - - don't allow creating new accounts; helps prevent typos when - entering account names - - Many hledger users edit their journals directly with a text editor, -or generate them from CSV. For more interactive data entry, there is the -'add' command, which prompts interactively on the console for new -transactions, and appends them to the journal file (if there are -multiple '-f FILE' options, the first file is used.) Existing -transactions are not changed. This is the only hledger command that -writes to the journal file. - - To use it, just run 'hledger add' and follow the prompts. You can -add as many transactions as you like; when you are finished, enter '.' -or press control-d or control-c to exit. - - Features: - - * add tries to provide useful defaults, using the most similar recent - transaction (by description) as a template. - * You can also set the initial defaults with command line arguments. - * Readline-style edit keys can be used during data entry. - * The tab key will auto-complete whenever possible - accounts, - descriptions, dates ('yesterday', 'today', 'tomorrow'). If the - input area is empty, it will insert the default value. - * If the journal defines a default commodity, it will be added to any - bare numbers entered. - * A parenthesised transaction code may be entered following a date. - * Comments and tags may be entered following a description or amount. - * If you make a mistake, enter '<' at any prompt to restart the - transaction. - * Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see the tutorial for a detailed explanation): - -$ hledger add -Adding transactions to journal file /src/hledger/examples/sample.journal -Any command line arguments will be used as defaults. -Use tab key to complete, readline keys to edit, enter to accept defaults. -An optional (CODE) may follow transaction dates. -An optional ; COMMENT may follow descriptions or amounts. -If you make a mistake, enter < at any prompt to restart the transaction. -To end a transaction, enter . when prompted. -To quit, enter . at a date prompt or press control-d or control-c. -Date [2015/05/22]: -Description: supermarket -Account 1: expenses:food -Amount 1: $10 -Account 2: assets:checking -Amount 2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): . -2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - -Save this transaction to the journal ? [y]: -Saved. -Starting the next transaction (. or ctrl-D/ctrl-C to quit) -Date [2015/05/22]: $ - - -File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS - -4.4 balance -=========== - -Show accounts and their balances. Aliases: b, bal. - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports) -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date) -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'-O FMT --output-format=FMT' - - select the output format. Supported formats: txt, csv, html. -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. -'--pretty-tables' - - use unicode to display prettier tables. -'--sort-amount' - - sort by amount instead of account code/name (in flat mode). With - multiple columns, sorts by the row total, or by row average if that - is displayed. -'--invert' - - display all amounts with reversed sign -'--budget' - - show performance compared to budget goals defined by periodic - transactions -'--show-unbudgeted' - - with -budget, show unbudgeted accounts also - - The balance command is hledger's most versatile command. Note, -despite the name, it is not always used for showing real-world account -balances; the more accounting-aware balancesheet and incomestatement may -be more convenient for that. - - By default, it displays all accounts, and each account's change in -balance during the entire period of the journal. Balance changes are -calculated by adding up the postings in each account. You can limit the -postings matched, by a query, to see fewer accounts, changes over a -different time period, changes from only cleared transactions, etc. - - If you include an account's complete history of postings in the -report, the balance change is equivalent to the account's current ending -balance. For a real-world account, typically you won't have all -transactions in the journal; instead you'll have all transactions after -a certain date, and an "opening balances" transaction setting the -correct starting balance on that date. Then the balance command will -show real-world account balances. In some cases the -H/-historical flag -is used to ensure this (more below). - - The balance command can produce several styles of report: -* Menu: - -* Classic balance report:: -* Customising the classic balance report:: -* Colour support:: -* Flat mode:: -* Depth limited balance reports:: -* Multicolumn balance report:: -* Budget report:: -* Output format:: - - -File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance - -4.4.1 Classic balance report ----------------------------- - -This is the original balance report, as found in Ledger. It usually -looks like this: - -$ 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 - - By default, accounts are displayed hierarchically, with subaccounts -indented below their parent. At each level of the tree, accounts are -sorted by account code if any, then by account name. Or with -'-S/--sort-amount', by their balance amount. - - "Boring" accounts, which contain a single interesting subaccount and -no balance of their own, are elided into the following line for more -compact output. (Eg above, the "liabilities" account.) Use -'--no-elide' to prevent this. - - Account balances are "inclusive" - they include the balances of any -subaccounts. - - Accounts which have zero balance (and no non-zero subaccounts) are -omitted. Use '-E/--empty' to show them. - - A final total is displayed by default; use '-N/--no-total' to -suppress it, eg: - -$ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies - - -File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance - -4.4.2 Customising the classic balance report --------------------------------------------- - -You can customise the layout of classic balance reports with '--format -FMT': - -$ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 - - The FMT format string (plus a newline) specifies the formatting -applied to each account/balance pair. It may contain any suitable text, -with data fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - * MAX truncates at this width (optional) - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance - -4.4.3 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: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance - -4.4.4 Flat mode ---------------- - -To see a flat list instead of the default hierarchical display, use -'--flat'. In this mode, accounts (unless depth-clipped) show their full -names and "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 report, Prev: Flat mode, Up: balance - -4.4.5 Depth limited balance reports ------------------------------------ - -With '--depth N' or 'depth:N' or just '-N', balance reports show -accounts only to the specified numeric depth. This is very useful to -summarise a complex set of accounts and get an overview. - -$ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Flat-mode balance reports, which normally show exclusive balances, -show inclusive balances at the depth limit. - - -File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance - -4.4.6 Multicolumn balance report --------------------------------- - -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. They share many of the above -features, but they show the report as a table, with columns representing -time periods. This mode is activated by providing a reporting interval. - - There are three types of multicolumn 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 - - Multicolumn 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 - - Limitations: - - In multicolumn reports the '-V/--value' flag uses the market price on -the report end date, for all columns (not the price on each column's end -date). - - Eliding of boring parent accounts in tree mode, as in the classic -balance report, is not yet supported in multicolumn reports. - - -File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance - -4.4.7 Budget report -------------------- - -With '--budget', extra columns are displayed showing budget goals for -each account and period, if any. Budget goals are defined by periodic -transactions. This is very useful for comparing planned and actual -income, expenses, time usage, etc. -budget is most often combined with -a report interval. - - 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 report: - -$ hledger balance -M --budget -Budget performance in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 -======================++================================================= - || $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 - - By default, only accounts with budget goals during the report period -are shown. '--show-unbudgeted' shows unbudgeted accounts as well. -Top-level accounts with no budget goals anywhere below them are grouped -under ''. - - You can roll over unspent budgets to next period with '--cumulative': - -$ hledger balance -M --budget --cumulative -Budget performance in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 -======================++================================================= - || $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 - - Note, the '-S/--sort-amount' flag is not yet fully supported with -'--budget'. - - For more examples, see Budgeting and Forecasting. - -4.4.8 Output format -------------------- - -The balance command supports output destination and output format -selection. - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS - -4.5 balancesheet -================ - -This command displays a simple balance sheet, showing historical ending -balances of asset and liability accounts (ignoring any report begin -date). It assumes that these accounts are under a top-level 'asset' or -'liability' account (case insensitive, plural forms also allowed). Note -this report shows all account balances with normal positive sign (like -conventional financial statements, unlike balance/print/register) -(experimental). (bs) - -'--change' - - show balance change in each period, instead of historical ending - balances -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of historical ending balances -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date) (default) -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'--sort-amount' - - sort by amount instead of account code/name - - Example: - -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for -each report period. As with multicolumn balance reports, you can alter -the report mode with '--change'/'--cumulative'/'--historical'. Normally -balancesheet shows historical ending balances, which is what you need -for a balance sheet; note this means it ignores report begin dates. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS - -4.6 balancesheetequity -====================== - -Just like balancesheet, but also reports Equity (which it assumes is -under a top-level 'equity' account). - - Example: - -$ hledger balancesheetequity -Balance Sheet With Equity - -Assets: - $-2 assets - $1 bank:saving - $-3 cash --------------------- - $-2 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Equity: - $1 equity:owner --------------------- - $1 - -Total: --------------------- - 0 - - -File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS - -4.7 cashflow -============ - -This command displays a simple cashflow statement, showing changes in -"cash" accounts. It assumes that these accounts are under a top-level -'asset' account (case insensitive, plural forms also allowed) and do not -contain 'receivable' or 'A/R' in their name. Note this report shows all -account balances with normal positive sign (like conventional financial -statements, unlike balance/print/register) (experimental). (cf) - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row (in simple reports) -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'--sort-amount' - - sort by amount instead of account code/name - - Example: - -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 - - With a reporting interval, multiple columns will be shown, one for -each report period. Normally cashflow shows changes in assets per -period, though as with multicolumn balance reports you can alter the -report mode with '--change'/'--cumulative'/'--historical'. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS - -4.8 check-dates -=============== - -Check that transactions are sorted by increasing date. With a query, -only matched transactions' dates are checked. - - -File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS - -4.9 check-dupes -=============== - -Report account names having the same leaf but different prefixes. An -example: http://stefanorodighiero.net/software/hledger-dupes.html - - -File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS - -4.10 close -========== - -Print closing/opening transactions that bring some or all account -balances to zero and back. Can be useful for bringing asset/liability -balances across file boundaries, or for closing out income/expenses for -a period. This was formerly called "equity", as in Ledger, and that -alias is also accepted. See close -help for more. - - -File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS - -4.11 files -========== - -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - - -File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS - -4.12 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.13 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.14 incomestatement -==================== - -This command displays a simple income statement, showing revenues and -expenses during a period. It assumes that these accounts are under a -top-level 'revenue' or 'income' or 'expense' account (case insensitive, -plural forms also allowed). Note this report shows all account balances -with normal positive sign (like conventional financial statements, -unlike balance/print/register) (experimental). (is) - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'--sort-amount' - - sort by amount instead of account code/name - - This command displays a simple income statement. It currently -assumes that you have top-level accounts named 'income' (or 'revenue') -and 'expense' (plural forms also allowed.) - -$ hledger incomestatement -Income Statement - -Revenues: - $-2 income - $-1 gifts - $-1 salary --------------------- - $-2 - -Expenses: - $2 expenses - $1 food - $1 supplies --------------------- - $2 - -Total: --------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for -each report period. Normally incomestatement shows revenues/expenses -per period, though as with multicolumn balance reports you can alter the -report mode with '--change'/'--cumulative'/'--historical'. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS - -4.15 prices -=========== - -Print market price directives from the journal. With -costs, also print -synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction prices. -Prices (and postings providing prices) can be filtered by a query. - - -File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS - -4.16 print -========== - -Show transactions from the journal. Aliases: p, txns. - -'-m STR --match=STR' - - show the transaction whose description is most similar to STR, and - is most recent -'--new' - - show only newer-dated transactions added in each file since last - run -'-x --explicit' - - show all amounts explicitly -'-O FMT --output-format=FMT' - - select the output format. Supported formats: txt, csv. -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. - -$ hledger print -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - -2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - -2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - -2008/12/31 * pay off - liabilities:debts $1 - assets:bank:checking $-1 - - The print command displays full journal entries (transactions) from -the journal file in date order, tidily formatted. print's output is -always a valid hledger journal. It preserves all transaction -information, but it does not preserve directives or inter-transaction -comments - - Normally, the journal entry's explicit or implicit amount style is -preserved. Ie when an amount is omitted in the journal, it will be -omitted in the output. You can use the '-x'/'--explicit' flag to make -all amounts explicit, which can be useful for troubleshooting or for -making your journal more readable and robust against data entry errors. -Note, '-x' will cause postings with a multi-commodity amount (these can -arise when a multi-commodity transaction has an implicit amount) will be -split into multiple single-commodity postings, for valid journal output. - - With '-B'/'--cost', amounts with transaction prices are converted to -cost using that price. This can be used for troubleshooting. - - With '-m'/'--match' and a STR argument, print will show at most one -transaction: the one one whose description is most similar to STR, and -is most recent. STR should contain at least two characters. If there -is no similar-enough match, no transaction will be shown. - - With '--new', for each FILE being read, hledger reads (and writes) a -special state file ('.latest.FILE' in the same directory), containing -the latest transaction date(s) that were seen last time FILE was read. -When this file is found, only transactions with newer dates (and new -transactions on the latest date) are printed. This is useful for -ignoring already-seen entries in import data, such as downloaded CSV -files. Eg: - -$ hledger -f bank1.csv print --new -# shows transactions added since last print --new on this file - - This assumes that transactions added to FILE always have same or -increasing dates, and that transactions on the same day do not get -reordered. See also the import command. - - This command also supports output destination and output format -selection. Here's an example of print's CSV output: - -$ hledger print -Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" -"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" -"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - * There is one CSV record per posting, with the parent transaction's - fields repeated. - * The "txnidx" (transaction index) field shows which postings belong - to the same transaction. (This number might change if transactions - are reordered within the file, files are parsed/included in a - different order, etc.) - * The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - * The numeric amount is repeated in either the "credit" or "debit" - column, for convenience. (Those names are not accurate in the - accounting sense; it just puts negative amounts under credit and - zero or greater amounts under debit.) - - -File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS - -4.17 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.18 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.18.1 Custom register output ------------------------------ - -register uses the full terminal width by default, except on windows. -You can override this by setting the 'COLUMNS' environment variable (not -a bash shell variable) or by using the '--width'/'-w' option. - - The description and account columns normally share the space equally -(about half of (width - 40) each). You can adjust this by adding a -description width as part of -width's argument, comma-separated: -'--width W,D' . Here's a diagram: - -<--------------------------------- width (W) ----------------------------------> -date (10) description (D) account (W-41-D) amount (12) balance (12) -DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - and some examples: - -$ hledger reg # use terminal width (or 80 on windows) -$ hledger reg -w 100 # use width 100 -$ COLUMNS=100 hledger reg # set with one-time environment variable -$ export COLUMNS=100; hledger reg # set till session end (or window resize) -$ hledger reg -w 100,40 # set overall width 100, description width 40 -$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS - -4.19 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: roi, Prev: register-match, Up: COMMANDS - -4.20 rewrite -============ - -Print all transactions, adding custom postings to the matched ones. - - -File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS - -4.21 roi -======== - -Shows time-weighted (TWR) and money-weighted (IRR) rate of return on -your investments. See 'roi --help' for more. - - -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS - -4.22 stats -========== - -Show some journal statistics. - -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. - -$ hledger stats -Main journal file : /src/hledger/examples/sample.journal -Included journal files : -Transactions span : 2008-01-01 to 2009-01-01 (366 days) -Last transaction : 2008-12-31 (2333 days ago) -Transactions : 5 (0.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 5 -Accounts : 8 (depth 3) -Commodities : 1 ($) - - The stats command displays summary information for the whole journal, -or a matched part of it. With a reporting interval, it shows a report -for each report period. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS - -4.23 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.24 test -========= - -Run built-in unit tests. - - Prints test names and their results on stdout. If any test fails or -gives an error, the exit code will be non-zero. - - Test names include a group prefix. If a (exact, case sensitive) -group prefix, or a full test name is provided as the first argument, -only that group or test is run. - - If a numeric second argument is provided, it will set the randomness -seed, for repeatable results from tests using randomness (currently none -of them). - - This is mainly used by developers, but it's nice to be able to -sanity-check your installed hledger executable at any time. All tests -are expected to pass - if you ever see otherwise, something has gone -wrong, please report a bug! - - -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, but it's superseded now by the built-in roi command. - - -File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS - -5.3 Experimental add-ons -======================== - -These are available in source form in the hledger repo's bin/ directory; -installing them is pretty easy. They may be less mature and documented -than built-in commands. Reading and tweaking these is a good way to -start making your own! -* Menu: - -* autosync:: -* chart:: -* check:: - - -File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons - -5.3.1 autosync --------------- - -hledger-autosync is a symbolic link for easily running ledger-autosync, -if installed. ledger-autosync does deduplicating conversion of OFX data -and some CSV formats, and can also download the data if your bank offers -OFX Direct Connect. - - -File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons - -5.3.2 chart ------------ - -hledger-chart.hs is an old pie chart generator, in need of some love. - - -File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons - -5.3.3 check ------------ - -hledger-check.hs checks more powerful account balance assertions. - - -Tag Table: -Node: Top68 -Node: EXAMPLES1884 -Ref: #examples1984 -Node: OPTIONS3630 -Ref: #options3732 -Node: General options4167 -Ref: #general-options4292 -Node: Command options6974 -Ref: #command-options7125 -Node: Command arguments7523 -Ref: #command-arguments7677 -Node: Argument files7798 -Ref: #argument-files7974 -Node: Special characters in arguments and queries8240 -Ref: #special-characters-in-arguments-and-queries8474 -Node: More escaping8924 -Ref: #more-escaping9086 -Node: Even more escaping9382 -Ref: #even-more-escaping9576 -Node: Less escaping10247 -Ref: #less-escaping10409 -Node: Command line tips10654 -Ref: #command-line-tips10840 -Node: Unicode characters11217 -Ref: #unicode-characters11373 -Node: Input files12098 -Ref: #input-files12234 -Node: Smart dates14204 -Ref: #smart-dates14345 -Node: Report start & end date15751 -Ref: #report-start-end-date15923 -Node: Report intervals16988 -Ref: #report-intervals17153 -Node: Period expressions17554 -Ref: #period-expressions17714 -Node: Depth limiting21671 -Ref: #depth-limiting21815 -Node: Pivoting22157 -Ref: #pivoting22275 -Node: Cost23951 -Ref: #cost24059 -Node: Market value24177 -Ref: #market-value24312 -Node: Combining -B and -V25678 -Ref: #combining--b-and--v25841 -Node: Output destination25988 -Ref: #output-destination26150 -Node: Output format26433 -Ref: #output-format26585 -Node: Regular expressions26970 -Ref: #regular-expressions27107 -Node: QUERIES28468 -Ref: #queries28570 -Node: COMMANDS32532 -Ref: #commands32644 -Node: accounts33644 -Ref: #accounts33742 -Node: activity34988 -Ref: #activity35098 -Node: add35458 -Ref: #add35557 -Node: balance38218 -Ref: #balance38329 -Node: Classic balance report41412 -Ref: #classic-balance-report41585 -Node: Customising the classic balance report42954 -Ref: #customising-the-classic-balance-report43182 -Node: Colour support45256 -Ref: #colour-support45423 -Node: Flat mode45596 -Ref: #flat-mode45744 -Node: Depth limited balance reports46157 -Ref: #depth-limited-balance-reports46357 -Node: Multicolumn balance report46813 -Ref: #multicolumn-balance-report47011 -Node: Budget report52191 -Ref: #budget-report52334 -Ref: #output-format-155368 -Node: balancesheet55446 -Ref: #balancesheet55582 -Node: balancesheetequity57893 -Ref: #balancesheetequity58042 -Node: cashflow58579 -Ref: #cashflow58707 -Node: check-dates60830 -Ref: #check-dates60957 -Node: check-dupes61074 -Ref: #check-dupes61198 -Node: close61335 -Ref: #close61443 -Node: files61773 -Ref: #files61874 -Node: help62015 -Ref: #help62115 -Node: import63189 -Ref: #import63303 -Node: incomestatement64033 -Ref: #incomestatement64167 -Node: prices66571 -Ref: #prices66686 -Node: print66958 -Ref: #print67068 -Node: print-unique71962 -Ref: #print-unique72088 -Node: register72156 -Ref: #register72283 -Node: Custom register output76784 -Ref: #custom-register-output76913 -Node: register-match78143 -Ref: #register-match78277 -Node: rewrite78460 -Ref: #rewrite78575 -Node: roi78644 -Ref: #roi78742 -Node: stats78858 -Ref: #stats78957 -Node: tags79827 -Ref: #tags79925 -Node: test80161 -Ref: #test80245 -Node: ADD-ON COMMANDS80953 -Ref: #add-on-commands81063 -Node: Official add-ons82350 -Ref: #official-add-ons82490 -Node: api82577 -Ref: #api82666 -Node: ui82718 -Ref: #ui82817 -Node: web82875 -Ref: #web82964 -Node: Third party add-ons83010 -Ref: #third-party-add-ons83185 -Node: diff83320 -Ref: #diff83417 -Node: iadd83516 -Ref: #iadd83630 -Node: interest83713 -Ref: #interest83834 -Node: irr83929 -Ref: #irr84027 -Node: Experimental add-ons84158 -Ref: #experimental-add-ons84310 -Node: autosync84590 -Ref: #autosync84701 -Node: chart84940 -Ref: #chart85059 -Node: check85130 -Ref: #check85232 +hledger(1) hledger 1.13 +*********************** + +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 in arguments and queries:: +* Command line tips:: +* Unicode characters:: +* Input files:: +* Smart dates:: +* Report start & end date:: +* Report intervals:: +* Period expressions:: +* Depth limiting:: +* Pivoting:: +* Cost:: +* Market value:: +* Combining -B and -V:: +* Output destination:: +* Output format:: +* Regular expressions:: + + +File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS + +2.1 General options +=================== + +To see general usage help, including general options which are supported +by most hledger commands, run 'hledger -h'. + + General help options: + +'-h --help' + + show general usage (or after COMMAND, command usage) +'--version' + + show version +'--debug[=N]' + + show debug output (levels 1-9, default: 1) + + General input options: + +'-f FILE --file=FILE' + + use a different input file. For stdin, use - (default: + '$LEDGER_FILE' or '$HOME/.hledger.journal') +'--rules-file=RULESFILE' + + Conversion rules file to use when reading CSV (default: FILE.rules) +'--separator=CHAR' + + Field separator to expect when reading CSV (default: ',') +'--alias=OLD=NEW' + + rename accounts named OLD to NEW +'--anon' + + anonymize accounts and payees +'--pivot FIELDNAME' + + use some other field or tag for the account name +'-I --ignore-assertions' + + ignore any failing balance assertions + + General reporting options: + +'-b --begin=DATE' + + include postings/txns on or after this date +'-e --end=DATE' + + include postings/txns before this date +'-D --daily' + + multiperiod/multicolumn report by day +'-W --weekly' + + multiperiod/multicolumn report by week +'-M --monthly' + + multiperiod/multicolumn report by month +'-Q --quarterly' + + multiperiod/multicolumn report by quarter +'-Y --yearly' + + multiperiod/multicolumn report by year +'-p --period=PERIODEXP' + + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) +'--date2' + + match the secondary date instead (see command help for other + effects) +'-U --unmarked' + + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' + + include only pending postings/txns +'-C --cleared' + + include only cleared postings/txns +'-R --real' + + include only non-virtual postings +'-NUM --depth=NUM' + + hide/aggregate accounts or postings more than NUM levels deep +'-E --empty' + + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) +'-B --cost' + + convert amounts to their cost at transaction time (using the + transaction price, if any) +'-V --value' + + convert amounts to their market value on the report end date (using + the most recent applicable market price, if any) +'--auto' + + apply automated posting rules to modify transactions. +'--forecast' + + apply periodic transaction rules to generate future transactions, + to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, +the last one takes precedence. + + Some reporting options can also be written as query arguments. + + +File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS + +2.2 Command options +=================== + +To see options for a particular command, including command-specific +options, run: 'hledger COMMAND -h'. + + Command-specific options must be written after the command name, eg: +'hledger print -x'. + + Additionally, if the command is an addon, you may need to put its +options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can +run the addon executable directly: 'hledger-ui --watch'. + + +File: hledger.info, Node: Command arguments, Next: Argument files, Prev: Command options, Up: OPTIONS + +2.3 Command arguments +===================== + +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. + + +File: hledger.info, Node: Argument files, Next: Special characters in arguments and queries, 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 in arguments and queries, Next: Command line tips, Prev: Argument files, Up: OPTIONS + +2.5 Special characters in arguments and queries +=============================================== + +In shell command lines, option and argument values which contain +"problematic" characters, ie spaces, and also characters significant to +your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by +enclosing them in quotes or by writing backslashes before the +characters. Eg: + + 'hledger register -p 'last year' "accounts receivable +(receivable|payable)" amt:\>100'. +* Menu: + +* More escaping:: +* Even more escaping:: +* Less escaping:: + + +File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries + +2.5.1 More escaping +------------------- + +Characters significant both to the shell and in regular expressions may +need one extra level of escaping. 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:\\$' + + +File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries + +2.5.2 Even more escaping +------------------------ + +When hledger runs an addon executable (eg you type 'hledger ui', hledger +runs 'hledger-ui'), it de-escapes command-line options and arguments +once, so you might need to _triple_-escape. Eg in bash, running the ui +command and matching the dollar sign, it's: + + 'hledger ui cur:'\\$'' + + or: + + 'hledger ui cur:\\\\$' + + If you asked why _four_ slashes above, this may help: + +unescaped: '$' +escaped: '\$' +double-escaped: '\\$' +triple-escaped: '\\\\$' + + (The number of backslashes in fish shell is left as an exercise for +the reader.) + + You can always avoid the extra escaping for addons by running the +addon directly: + + 'hledger-ui cur:\\$' + + +File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries + +2.5.3 Less escaping +------------------- + +Inside an argument file, or in the search field of hledger-ui or +hledger-web, or at a GHCI prompt, you need one less level of escaping +than at the command line. And backslashes may work better than quotes. +Eg: + + 'ghci> :main balance cur:\$' + + +File: hledger.info, Node: Command line tips, Next: Unicode characters, Prev: Special characters in arguments and queries, Up: OPTIONS + +2.6 Command line tips +===================== + +If in doubt, keep things simple: + + * write options after the command ('hledger CMD -OPTIONS ARGS') + * run add-on executables directly ('hledger-ui -OPTIONS ARGS') + * enclose problematic args in single quotes + * if needed, also add a backslash to escape regexp metacharacters + + To find out exactly how a command line is being parsed, add +'--debug=2' to troubleshoot. + + +File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Command line tips, Up: OPTIONS + +2.7 Unicode characters +====================== + +hledger is expected to handle unicode (non-ascii) characters, but this +requires a well-configured environment. + + To handle unicode characters in the command line or input data, a +system locale that can decode them must be configured (POSIX's default +'C' locale will not work). Eg in bash, you could do: + +export LANG=en_US.UTF-8 + + See Troubleshooting for more about this. + + Unicode characters should appear correctly in hledger's output. For +the hledger and hledger-ui tools, this requires that + + * your terminal supports unicode + * the terminal's font includes the required unicode glyphs + * the terminal is configured to display "wide" characters as double + width (otherwise report alignment will be off) + + +File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS + +2.8 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.9 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: + +'2004/10/1', '2004-01-01', '2004.9.1' exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 +'2004' start of year +'2004/10' start of month +'10/1' month and day in current year +'21' day in current month +'october, oct' start of month in current year +'yesterday, today, tomorrow' -1, 0, 1 days from today +'last/this/next -1, 0, 1 periods from the current period +day/week/month/quarter/year' +'20181201' 8 digit YYYYMMDD with valid year month and day +'201812' 6 digit YYYYMM with valid year and month + + Counterexamples - malformed digit sequences might give surprising +results: + +'201813' 6 digits with an invalid month is parsed as start of 6-digit year +'20181301' 8 digits with an invalid month is parsed as start of 8-digit year +'20181232' 8 digits with an invalid day gives an error +'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error + + +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS + +2.10 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.11 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.12 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.13 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.14 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.15 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.16 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 -N euros + €100 assets:euros + + What are they worth at end of nov 3 ? + +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date +specified, defaults to today) + +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P +directives, not transaction prices (unlike Ledger). + + Currently, -V has a limitation in multicolumn balance reports: it +uses the market prices on the report end date for all columns. (Instead +of the prices on each column's end date.) + + +File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS + +2.17 Combining -B and -V +======================== + +Using -B/-cost and -V/-value together is currently allowed, but the +results are probably not meaningful. Let us know if you find a use for +this. + + +File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS + +2.18 Output destination +======================= + +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. This is +controlled by the '-o/--output-file' option. + +$ hledger balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE + + +File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS + +2.19 Output format +================== + +Some commands can write their output in other formats. Eg print and +register can output CSV, and the balance commands can output CSV or +HTML. This is controlled by the '-O/--output-format' option, or by +specifying a '.csv' or '.html' file extension with '-o/--output-file'. + +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv + + +File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS + +2.20 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', 'acct:REGEX'* + + match account names by this regular expression. (With no prefix, + 'acct:' is assumed.) same as above + +*'amt:N, amt:N, amt:>=N'* + + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not + tested, and will always match.) The comparison has two modes: if N + is preceded by a + or - sign (or is 0), the two signed numbers are + compared. Otherwise, the absolute magnitudes are compared, + ignoring sign. +*'code:REGEX'* + + match by transaction code (eg check number) +*'cur:REGEX'* + + match postings or transactions including any amounts whose + currency/commodity symbol is fully matched by REGEX. (For a partial + match, use '.*REGEX.*'). Note, to match characters which are + regex-significant, like the dollar sign ('$'), you need to prepend + '\'. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: 'hledger + print cur:'\$'' or 'hledger print cur:\\$'. +*'desc:REGEX'* + + match transaction descriptions. +*'date:PERIODEXPR'* + + match dates within the specified period. PERIODEXPR is a period + expression (with no report interval). Examples: 'date:2016', + 'date:thismonth', 'date:2000/2/1-2/15', 'date:lastweek-'. If the + '--date2' command line flag is present, this matches secondary + dates instead. +*'date2:PERIODEXPR'* + + match secondary dates within the specified period. +*'depth:N'* + + match (or display, depending on command) accounts at or above this + depth +*'note:REGEX'* + + match transaction notes (part of description right of '|', or whole + description when there's no '|') +*'payee:REGEX'* + + match transaction payee/payer names (part of description left of + '|', or whole description when there's no '|') +*'real:, real:0'* + + match real or virtual postings respectively +*'status:, status:!, status:*'* + + match unmarked, pending, or cleared transactions respectively +*'tag:REGEX[=REGEX]'* + + match by tag name, and optionally also by tag value. Note a tag: + query is considered to match a transaction if it matches any of the + postings. Also remember that postings inherit the tags of their + parent transaction. + + The following special search term is used automatically in +hledger-web, only: + +*'inacct:ACCTNAME'* + + tells hledger-web to show the transaction register for this + account. Can be filtered further with 'acct' etc. + + Some of these can also be expressed as command-line options (eg +'depth:2' is equivalent to '--depth 2'). Generally you can mix options +and query arguments, and the resulting query will be their intersection +(perhaps excluding the '-p/--period' option). + + +File: hledger.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top + +4 COMMANDS +********** + +hledger provides a number of subcommands; 'hledger' with no arguments +shows a list. + + If you install additional 'hledger-*' packages, or if you put +programs or scripts named 'hledger-NAME' in your PATH, these will also +be listed as subcommands. + + Run a subcommand by writing its name as first argument (eg 'hledger +incomestatement'). You can also write one of the standard short aliases +displayed in parentheses in the command list ('hledger b'), or any any +unambiguous prefix of a command name ('hledger inc'). + + Here are all the builtin commands in alphabetical order. See also +'hledger' for a more organised command list, and 'hledger CMD -h' for +detailed command help. +* Menu: + +* accounts:: +* activity:: +* add:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check-dates:: +* check-dupes:: +* close:: +* files:: +* help:: +* import:: +* incomestatement:: +* prices:: +* print:: +* print-unique:: +* register:: +* register-match:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS + +4.1 accounts +============ + +accounts, a +Show account names. + + This command lists account names, either declared with account +directives (-declared), posted to (-used), or both (the default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +'--tree', it uses indentation to show the account hierarchy. In flat +mode you can add '--drop N' to omit the first few account name +components. Account names can be depth-clipped with 'depth:N' or +'--depth N' or '-N'. + + Examples: + +$ 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 +============ + +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. + + Examples: + +$ 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 +======= + +add +Prompt for transactions and add them to the journal. + + 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 (by + description) recent transaction (filtered by the query, if any) 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 +=========== + +balance, bal, b +Show accounts and their balances. + + The balance command is hledger's most versatile command. Note, +despite the name, it is not always used for showing real-world account +balances; the more accounting-aware balancesheet and incomestatement may +be more convenient for that. + + By default, it displays all accounts, and each account's change in +balance during the entire period of the journal. Balance changes are +calculated by adding up the postings in each account. You can limit the +postings matched, by a query, to see fewer accounts, changes over a +different time period, changes from only cleared transactions, etc. + + If you include an account's complete history of postings in the +report, the balance change is equivalent to the account's current ending +balance. For a real-world account, typically you won't have all +transactions in the journal; instead you'll have all transactions after +a certain date, and an "opening balances" transaction setting the +correct starting balance on that date. Then the balance command will +show real-world account balances. In some cases the -H/-historical flag +is used to ensure this (more below). + + The balance command can produce several styles of report: +* Menu: + +* Classic balance report:: +* Customising the classic balance report:: +* Colour support:: +* Flat mode:: +* Depth limited balance reports:: +* Multicolumn balance report:: +* Budget report:: +* Output format:: + + +File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance + +4.4.1 Classic balance report +---------------------------- + +This is the original balance report, as found in Ledger. It usually +looks like this: + +$ 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 + + By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. At each level of the tree, accounts are +sorted by account code if any, then by account name. Or with +'-S/--sort-amount', by their balance amount. + + "Boring" accounts, which contain a single interesting subaccount and +no balance of their own, are elided into the following line for more +compact output. (Eg above, the "liabilities" account.) Use +'--no-elide' to prevent this. + + Account balances are "inclusive" - they include the balances of any +subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are +omitted. Use '-E/--empty' to show them. + + A final total is displayed by default; use '-N/--no-total' to +suppress it, eg: + +$ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + + +File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance + +4.4.2 Customising the classic balance report +-------------------------------------------- + +You can customise the layout of classic balance reports with '--format +FMT': + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + * MAX truncates at this width (optional) + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance + +4.4.3 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: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance + +4.4.4 Flat mode +--------------- + +To see a flat list instead of the default hierarchical display, use +'--flat'. In this mode, accounts (unless depth-clipped) show their full +names and "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 report, Prev: Flat mode, Up: balance + +4.4.5 Depth limited balance reports +----------------------------------- + +With '--depth N' or 'depth:N' or just '-N', balance reports show +accounts only to the specified numeric depth. This is very useful to +summarise a complex set of accounts and get an overview. + +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Flat-mode balance reports, which normally show exclusive balances, +show inclusive balances at the depth limit. + + +File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance + +4.4.6 Multicolumn balance report +-------------------------------- + +Multicolumn or tabular balance reports are a very useful hledger +feature, and usually the preferred style. They share many of the above +features, but they show the report as a table, with columns representing +time periods. This mode is activated by providing a reporting interval. + + There are three types of multicolumn 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 + + Multicolumn 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). With '--budget', '--empty' also shows unbudgeted +accounts. + + 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 + + Limitations: + + In multicolumn reports the '-V/--value' flag uses the market price on +the report end date, for all columns (not the price on each column's end +date). + + Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. + + +File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance + +4.4.7 Budget report +------------------- + +With '--budget', extra columns are displayed showing budget goals for +each account and period, if any. Budget goals are defined by periodic +transactions. This is very useful for comparing planned and actual +income, expenses, time usage, etc. -budget is most often combined with +a report interval. + + 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 report: + +$ hledger balance -M --budget +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + By default, only accounts with budget goals during the report period +are shown. In the example above, transactions in 'expenses:gifts' and +'expenses:supplies' are counted towards 'expenses' budget, but accounts +'expenses:gifts' and 'expenses:supplies' are not shown, as they don't +have any budgets. + + You can use '--empty' shows unbudgeted accounts as well: + +$ hledger balance -M --budget --empty +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with '--cumulative': + +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + Note, the '-S/--sort-amount' flag is not yet fully supported with +'--budget'. + + For more examples, see Budgeting and Forecasting. +* Menu: + +* Nested budgets:: + + +File: hledger.info, Node: Nested budgets, Up: Budget report + +4.4.7.1 Nested budgets +...................... + +You can add budgets to any account in your account hierarchy. If you +have budgets on both parent account and some of its children, then +budget(s) of the child account(s) would be added to the budget of their +parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both 'expenses:personal' and 'expenses' is $1100. + + Transactions in 'expenses:personal:electronics' will be counted both +towards its $100 budget and $1100 of 'expenses:personal' , and +transactions in any other subaccount of 'expenses:personal' would be +counted towards only towards the budget of 'expenses:personal'. + + For example, let's consider these transactions: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + +2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + +2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + +2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in +'expenses:personal:electronics:upgrades' and 'expenses:personal:train +tickets', and since both of these accounts are without explicitly +defined budget, these transactions would be counted towards budgets of +'expenses:personal:electronics' and 'expenses:personal' accordingly: + +$ hledger balance --budget -M +Budget performance in 2019/01: + + || Jan +===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++------------------------------- + || 0 [ 0] + + And with '--empty', we can get a better picture of budget allocation +and consumption: + +$ hledger balance --budget -M --empty +Budget performance in 2019/01: + + || Jan +========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++------------------------------- + || 0 [ 0] + +4.4.8 Output format +------------------- + +The balance command supports output destination and output format +selection. + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS + +4.5 balancesheet +================ + +balancesheet, bs +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). It assumes that these accounts are under a top-level 'asset' or +'liability' account (case insensitive, plural forms also allowed). + + Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for +each report period. As with multicolumn balance reports, you can alter +the report mode with '--change'/'--cumulative'/'--historical'. Normally +balancesheet shows historical ending balances, which is what you need +for a balance sheet; note this means it ignores report begin dates. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS + +4.6 balancesheetequity +====================== + +balancesheetequity, bse +Just like balancesheet, but also reports Equity (which it assumes is +under a top-level 'equity' account). + + Example: + +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 + + +File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS + +4.7 cashflow +============ + +cashflow, cf +This command displays a simple cashflow statement, showing changes in +"cash" accounts. It assumes that these accounts are under a top-level +'asset' account (case insensitive, plural forms also allowed) and do not +contain 'receivable' or 'A/R' in their name. Note this report shows all +account balances with normal positive sign (like conventional financial +statements, unlike balance/print/register) (experimental). + + Example: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + With a reporting interval, multiple columns will be shown, one for +each report period. Normally cashflow shows changes in assets per +period, though as with multicolumn balance reports you can alter the +report mode with '--change'/'--cumulative'/'--historical'. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS + +4.8 check-dates +=============== + +check-dates +Check that transactions are sorted by increasing date. With -date2, +checks secondary dates instead. With -strict, dates must also be +unique. With a query, only matched transactions' dates are checked. +Reads the default journal file, or another specified with -f. + + +File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS + +4.9 check-dupes +=============== + +check-dupes +Reports account names having the same leaf but different prefixes. In +other words, two or more leaves that are categorized differently. Reads +the default journal file, or another specified as an argument. + + An example: http://stefanorodighiero.net/software/hledger-dupes.html + + +File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS + +4.10 close +========== + +close, equity +Prints a "closing balances" transaction and an "opening balances" +transaction that bring account balances to and from zero, respectively. +Useful for bringing asset/liability balances forward into a new journal +file, or for closing out revenues/expenses to retained earnings at the +end of a period. + + The closing transaction transfers balances to "equity:closing +balances". The opening transaction transfers balances from +"equity:opening balances". You can chose to print just one of the +transactions by using the '--opening' or '--closing' flag. + + If you split your journal files by time (eg yearly), you will +typically run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. This makes the files self +contained, so that correct balances are reported no matter which of them +are loaded. Ie, if you load just one file, the balances are initialised +correctly; or if you load several files, the redundant closing/opening +transactions cancel each other out. (They will show up in print or +register reports; you can exclude them with a query like +'not:desc:'(opening|closing) balances''.) + + If you're running a business, you might also use this command to +"close the books" at the end of an accounting period, transferring +income statement account balances to retained earnings. (You may want +to change the equity account name to something like "equity:retained +earnings".) + + By default, the closing transaction is dated yesterday, the balances +are calculated as of end of yesterday, and the opening transaction is +dated today. To close on some other date, use: 'hledger close -e +OPENINGDATE'. Eg, to close/open on the 2018/2019 boundary, use '-e +2019'. You can also use -p or 'date:PERIOD' (any starting date is +ignored). + + Both transactions will include balance assertions for the +closed/reopened accounts. You probably shouldn't use status or realness +filters (like -C or -R or 'status:') with this command, or the generated +balance assertions will depend on these flags. Likewise, if you run +this command with -auto, the balance assertions will probably always +require -auto. + + Examples: + + Carrying asset/liability balances into a new file for 2019, all from +command line: + + _Warning: we use '>>' here to append; be careful not to type a single +'>' which would wipe your journal!_ + +$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + + Now: + +$ hledger bs -f 2019.journal # one file - balances are correct +$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct +$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + + Transactions spanning the closing date can complicate matters, +breaking balance assertions: + +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + + Here's one way to resolve that: + +; in 2018.journal: +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + +; in 2019.journal: +2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking + + +File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS + +4.11 files +========== + +files +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + + +File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS + +4.12 help +========= + +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. + + Examples: + +$ 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.13 import +=========== + +import +Read new transactions added to each FILE since last run, and add them to +the main journal file. Or with -dry-run, just print the transactions +that would be added. + + 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.14 incomestatement +==================== + +incomestatement, is +This command displays a simple income statement, showing revenues and +expenses during a period. It assumes that these accounts are under a +top-level 'revenue' or 'income' or 'expense' account (case insensitive, +plural forms also allowed). Note this report shows all account balances +with normal positive sign (like conventional financial statements, +unlike balance/print/register) (experimental). + + This command displays a simple income statement. It currently +assumes that you have top-level accounts named 'income' (or 'revenue') +and 'expense' (plural forms also allowed.) + +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for +each report period. Normally incomestatement shows revenues/expenses +per period, though as with multicolumn balance reports you can alter the +report mode with '--change'/'--cumulative'/'--historical'. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS + +4.15 prices +=========== + +prices +Print market price directives from the journal. With -costs, also print +synthetic market prices based on transaction prices. With +-inverted-costs, also print inverse prices based on transaction prices. +Prices (and postings providing prices) can be filtered by a query. + + +File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS + +4.16 print +========== + +print, txns, p +Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from +the journal file in date order, tidily formatted. With -date2, +transactions are sorted by secondary date instead. + + print's output is always a valid hledger journal. +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments + +$ 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 + + Normally, the journal entry's explicit or implicit amount style is +preserved. Ie when an amount is omitted in the journal, it will be +omitted in the output. You can use the '-x'/'--explicit' flag to make +all amounts explicit, which can be useful for troubleshooting or for +making your journal more readable and robust against data entry errors. +Note, '-x' will cause postings with a multi-commodity amount (these can +arise when a multi-commodity transaction has an implicit amount) will be +split into multiple single-commodity postings, for valid journal output. + + With '-B'/'--cost', amounts with transaction prices are converted to +cost using that price. This can be used for troubleshooting. + + With '-m'/'--match' and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there +is no similar-enough match, no transaction will be shown. + + With '--new', for each FILE being read, hledger reads (and writes) a +special state file ('.latest.FILE' in the same directory), containing +the latest transaction date(s) that were seen last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. This is useful for +ignoring already-seen entries in import data, such as downloaded CSV +files. Eg: + +$ hledger -f bank1.csv print --new +# shows transactions added since last print --new on this file + + This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. See also the import command. + + This command also supports output destination and output format +selection. Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS + +4.17 print-unique +================= + +print-unique +Print transactions which do not reuse an already-seen description. + + Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 + + +File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS + +4.18 register +============= + +register, reg, r +Show postings and their running total. + + The register command displays postings in date order, 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 + + With -date2, it shows and sorts by secondary date instead. + + 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.18.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 (won't display correctly in -help): + +<--------------------------------- 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, & description width 40 + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS + +4.19 register-match +=================== + +register-match +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. If there are multiple equally +good matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS + +4.20 rewrite +============ + +rewrite +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: + + +File: hledger.info, Node: Re-write rules in a file, Up: rewrite + +4.20.1 Re-write rules in a file +------------------------------- + +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. I.e instead of specifying this +operations in command line you can put them in a journal file. + +$ rewrite-rules.journal + + Make contents look like this: + += ^income + (liabilities:tax) *.33 + += expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that ''='' (equality symbol) that is used instead of date in +transactions you usually write. It indicates the query by which you +want to match the posting to add new ones. + +$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + +$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in +journal is important. You can re-use result of previously added +postings. + +* Menu: + +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file + +4.20.1.1 Diff output format +........................... + +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. + +$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + +--- /tmp/examples/sample.journal ++++ /tmp/examples/sample.journal +@@ -18,3 +18,4 @@ + 2008/01/01 income +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:salary ++ (liabilities:tax) 0 +@@ -22,3 +23,4 @@ + 2008/06/01 gift +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:gifts ++ (liabilities:tax) 0 + + If you'll pass this through 'patch' tool you'll get transactions +containing the posting that matches your query be updated. Note that +multiple files might be update according to list of input files +specified via '--file' options and 'include' directives inside of these +files. + + Be careful. Whole transaction being re-formatted in a style of +output from 'hledger print'. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + +File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file + +4.20.1.2 rewrite vs. print -auto +................................ + +This command predates print -auto, and currently does much the same +thing, but with these differences: + + * with multiple files, rewrite lets rules in any file affect all + other files. print -auto uses standard directive scoping; rules + affect only child files. + + * rewrite's query limits which transactions can be rewritten; all are + printed. print -auto's query limits which transactions are + printed. + + * rewrite applies rules specified on command line or in the journal. + print -auto applies rules specified in the journal. + + +File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS + +4.21 roi +======== + +roi +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + + This command assumes that you have account(s) that hold nothing but +your investments and whenever you record current appraisal/valuation of +these investments you offset unrealized profit and loss into account(s) +that, again, hold nothing but unrealized profit and loss. + + Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. + + At a minimum, you need to supply a query (which could be just an +account name) to select your investments with '--inv', and another query +to identify your profit and loss transactions with '--pnl'. + + It will compute and display the internalized rate of return (IRR) and +time-weighted rate of return (TWR) for your investments for the time +period requested. Both rates of return are annualized before display, +regardless of the length of reporting interval. + + +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS + +4.22 stats +========== + +stats +Show some journal statistics. + + 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. + + Example: + +$ 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 ($) + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS + +4.23 tags +========= + +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 QUERY arguments, only transactions matching the query are +considered. + + +File: hledger.info, Node: test, Prev: tags, Up: COMMANDS + +4.24 test +========= + +test +Run built-in unit tests. + + This command runs the unit tests built in to hledger-lib and hledger, +printing test names and results on stdout. If any test fails, the exit +code will be non-zero. + + Test names include a group prefix. If a (exact, case sensitive) +group prefix, or a full test name is provided as the first argument, +only that group or test is run. + + If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). + + This is mainly used by developers, but it's nice to be able to +sanity-check your installed hledger executable at any time. All tests +are expected to pass - if you ever see otherwise, something has gone +wrong, please report a bug! + + +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, but it's superseded now by the built-in roi command. + + +File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS + +5.3 Experimental add-ons +======================== + +These are available in source form in the hledger repo's bin/ directory; +installing them is pretty easy. They may be less mature and documented +than built-in commands. Reading and tweaking these is a good way to +start making your own! +* Menu: + +* autosync:: +* chart:: +* check:: + + +File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons + +5.3.1 autosync +-------------- + +hledger-autosync is a symbolic link for easily running ledger-autosync, +if installed. ledger-autosync does deduplicating conversion of OFX data +and some CSV formats, and can also download the data if your bank offers +OFX Direct Connect. + + +File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons + +5.3.2 chart +----------- + +hledger-chart.hs is an old pie chart generator, in need of some love. + + +File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons + +5.3.3 check +----------- + +hledger-check.hs checks more powerful account balance assertions. + + +Tag Table: +Node: Top68 +Node: EXAMPLES1884 +Ref: #examples1984 +Node: OPTIONS3630 +Ref: #options3732 +Node: General options4167 +Ref: #general-options4292 +Node: Command options6974 +Ref: #command-options7125 +Node: Command arguments7523 +Ref: #command-arguments7677 +Node: Argument files7798 +Ref: #argument-files7974 +Node: Special characters in arguments and queries8240 +Ref: #special-characters-in-arguments-and-queries8474 +Node: More escaping8924 +Ref: #more-escaping9086 +Node: Even more escaping9382 +Ref: #even-more-escaping9576 +Node: Less escaping10247 +Ref: #less-escaping10409 +Node: Command line tips10654 +Ref: #command-line-tips10840 +Node: Unicode characters11217 +Ref: #unicode-characters11373 +Node: Input files12098 +Ref: #input-files12234 +Node: Smart dates14204 +Ref: #smart-dates14345 +Node: Report start & end date15751 +Ref: #report-start-end-date15923 +Node: Report intervals16989 +Ref: #report-intervals17154 +Node: Period expressions17555 +Ref: #period-expressions17715 +Node: Depth limiting21672 +Ref: #depth-limiting21816 +Node: Pivoting22158 +Ref: #pivoting22276 +Node: Cost23952 +Ref: #cost24060 +Node: Market value24178 +Ref: #market-value24313 +Node: Combining -B and -V25679 +Ref: #combining--b-and--v25842 +Node: Output destination25989 +Ref: #output-destination26151 +Node: Output format26434 +Ref: #output-format26586 +Node: Regular expressions26971 +Ref: #regular-expressions27108 +Node: QUERIES28469 +Ref: #queries28571 +Node: COMMANDS32533 +Ref: #commands32645 +Node: accounts33645 +Ref: #accounts33743 +Node: activity34442 +Ref: #activity34552 +Node: add34935 +Ref: #add35034 +Node: balance37621 +Ref: #balance37732 +Node: Classic balance report39173 +Ref: #classic-balance-report39346 +Node: Customising the classic balance report40715 +Ref: #customising-the-classic-balance-report40943 +Node: Colour support43017 +Ref: #colour-support43184 +Node: Flat mode43357 +Ref: #flat-mode43505 +Node: Depth limited balance reports43918 +Ref: #depth-limited-balance-reports44118 +Node: Multicolumn balance report44574 +Ref: #multicolumn-balance-report44772 +Node: Budget report50012 +Ref: #budget-report50155 +Node: Nested budgets54839 +Ref: #nested-budgets54951 +Ref: #output-format-158431 +Node: balancesheet58509 +Ref: #balancesheet58645 +Node: balancesheetequity59879 +Ref: #balancesheetequity60028 +Node: cashflow60589 +Ref: #cashflow60717 +Node: check-dates61745 +Ref: #check-dates61872 +Node: check-dupes62151 +Ref: #check-dupes62275 +Node: close62568 +Ref: #close62676 +Node: files66089 +Ref: #files66190 +Node: help66337 +Ref: #help66437 +Node: import67530 +Ref: #import67644 +Node: incomestatement68388 +Ref: #incomestatement68522 +Node: prices69858 +Ref: #prices69973 +Node: print70252 +Ref: #print70362 +Node: print-unique74855 +Ref: #print-unique74981 +Node: register75266 +Ref: #register75393 +Node: Custom register output79262 +Ref: #custom-register-output79391 +Node: register-match80653 +Ref: #register-match80787 +Node: rewrite81138 +Ref: #rewrite81253 +Node: Re-write rules in a file83102 +Ref: #re-write-rules-in-a-file83236 +Node: Diff output format84446 +Ref: #diff-output-format84615 +Node: rewrite vs print --auto85707 +Ref: #rewrite-vs.-print---auto85886 +Node: roi86442 +Ref: #roi86540 +Node: stats87552 +Ref: #stats87651 +Node: tags88405 +Ref: #tags88503 +Node: test88733 +Ref: #test88817 +Node: ADD-ON COMMANDS89578 +Ref: #add-on-commands89688 +Node: Official add-ons90975 +Ref: #official-add-ons91115 +Node: api91202 +Ref: #api91291 +Node: ui91343 +Ref: #ui91442 +Node: web91500 +Ref: #web91589 +Node: Third party add-ons91635 +Ref: #third-party-add-ons91810 +Node: diff91945 +Ref: #diff92042 +Node: iadd92141 +Ref: #iadd92255 +Node: interest92338 +Ref: #interest92459 +Node: irr92554 +Ref: #irr92652 +Node: Experimental add-ons92783 +Ref: #experimental-add-ons92935 +Node: autosync93215 +Ref: #autosync93326 +Node: chart93565 +Ref: #chart93684 +Node: check93755 +Ref: #check93857  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -135,2155 +135,2269 @@ FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') - - --alias=OLD=NEW - rename accounts named OLD to NEW - - --anon anonymize accounts and payees - - --pivot FIELDNAME - use some other field or tag for the account name - - -I --ignore-assertions - ignore any failing balance assertions - - General reporting options: - - -b --begin=DATE - include postings/txns on or after this date - - -e --end=DATE - include postings/txns before this date - - -D --daily - multiperiod/multicolumn report by day - - -W --weekly - multiperiod/multicolumn report by week - - -M --monthly - multiperiod/multicolumn report by month - - -Q --quarterly - multiperiod/multicolumn report by quarter - - -Y --yearly - multiperiod/multicolumn report by year - - -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) - - --date2 - match the secondary date instead (see command help for other - effects) - - -U --unmarked - include only unmarked postings/txns (can combine with -P or -C) - - -P --pending - include only pending postings/txns - - -C --cleared - include only cleared postings/txns - - -R --real - include only non-virtual postings - - -NUM --depth=NUM - hide/aggregate accounts or postings more than NUM levels deep - - -E --empty - show items with zero amount, normally hidden (and vice-versa in - hledger-ui/hledger-web) - - -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) - - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) - - --auto apply automated posting rules to modify transactions. - - --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, the - last one takes precedence. - - Some reporting options can also be written as query arguments. - - Command options - To see options for a particular command, including command-specific - options, run: hledger COMMAND -h. - - Command-specific options must be written after the command name, eg: - hledger print -x. - - Additionally, if the command is an addon, you may need to put its - options after a double-hyphen, eg: hledger ui -- --watch. Or, you can - run the addon executable directly: hledger-ui --watch. - - Command arguments - Most hledger commands accept arguments after the command name, which - are often a query, filtering the data in some way. - - Argument files - You can save a set of command line options/arguments in a file, one per - line, and then reuse them by writing @FILENAME in a command line. To - prevent this expansion of @-arguments, precede them with a -- argument. - For more, see Save frequently used options. - - Special characters in arguments and queries - In shell command lines, option and argument values which contain "prob- - lematic" characters, ie spaces, and also characters significant to your - shell such as <, >, (, ), | and $, should be escaped by enclosing them - in quotes or by writing backslashes before the characters. Eg: - - hledger register -p 'last year' "accounts receivable (receiv- - able|payable)" amt:\>100. - - More escaping - Characters significant both to the shell and in regular expressions may - need one extra level of escaping. 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:\\$ - - Even more escaping - When hledger runs an addon executable (eg you type hledger ui, hledger - runs hledger-ui), it de-escapes command-line options and arguments - once, so you might need to triple-escape. Eg in bash, running the ui - command and matching the dollar sign, it's: - - hledger ui cur:'\\$' - - or: - - hledger ui cur:\\\\$ - - If you asked why four slashes above, this may help: - - - unescaped: $ - escaped: \$ - double-escaped: \\$ - triple-escaped: \\\\$ - - (The number of backslashes in fish shell is left as an exercise for the - reader.) - - You can always avoid the extra escaping for addons by running the addon - directly: - - hledger-ui cur:\\$ - - Less escaping - Inside an argument file, or in the search field of hledger-ui or - hledger-web, or at a GHCI prompt, you need one less level of escaping - than at the command line. And backslashes may work better than quotes. - Eg: - - ghci> :main balance cur:\$ - - Command line tips - If in doubt, keep things simple: - - o write options after the command (hledger CMD -OPTIONS ARGS) - - o run add-on executables directly (hledger-ui -OPTIONS ARGS) - - o enclose problematic args in single quotes - - o if needed, also add a backslash to escape regexp metacharacters - - To find out exactly how a command line is being parsed, add --debug=2 - to troubleshoot. - - Unicode characters - hledger is expected to handle unicode (non-ascii) characters, but this - requires a well-configured environment. - - To handle unicode characters in the command line or input data, a sys- - tem locale that can decode them must be configured (POSIX's default C - locale will not work). Eg in bash, you could do: - - export LANG=en_US.UTF-8 - - See Troubleshooting for more about this. - - Unicode characters should appear correctly in hledger's output. For - the hledger and hledger-ui tools, this requires that - - o your terminal supports unicode - - o the terminal's font includes the required unicode glyphs - - o the terminal is configured to display "wide" characters as double - width (otherwise report alignment will be off) - - 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: - - - 2004/10/1, 2004-01-01, exact date, several sepa- - 2004.9.1 rators allowed. Year is - 4+ digits, month is 1-12, - day is 1-31 - 2004 start of year - - 2004/10 start of month - 10/1 month and day in current - year - 21 day in current month - october, oct start of month in current - year - yesterday, today, tomorrow -1, 0, 1 days from today - last/this/next day/week/month/quar- -1, 0, 1 periods from the - ter/year current period - 20181201 8 digit YYYYMMDD with - valid year month and day - 201812 6 digit YYYYMM with valid - year and month - - Counterexamples - malformed digit sequences might give surprising - results: - - - 201813 6 digits with an invalid - month is parsed as start - of 6-digit year - 20181301 8 digits with an invalid - month is parsed as start - of 8-digit year - 20181232 8 digits with an invalid - day gives an error - 201801012 9+ digits beginning with a - valid YYYYMMDD gives an - error - - 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 commod- - ity. - - 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 -N euros - 100 assets:euros - - What are they worth at end of nov 3 ? - - $ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date specified, - defaults to today) - - $ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - Currently, hledger's -V only uses market prices recorded with P direc- - tives, not transaction prices (unlike Ledger). - - Currently, -V has a limitation in multicolumn balance reports: it uses - the market prices on the report end date for all columns. (Instead of - the prices on each column's end date.) - - Combining -B and -V - Using -B/-cost and -V/-value together is currently allowed, but the - results are probably not meaningful. Let us know if you find a use for - this. - - Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- - trolled by the -o/--output-file option. - - $ hledger balance -o - # write to stdout (the default) - $ hledger balance -o FILE # write to FILE - - Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or - HTML. This is controlled by the -O/--output-format option, or by spec- - ifying a .csv or .html file extension with -o/--output-file. - - $ hledger balance -O csv # write CSV to stdout - $ hledger balance -o FILE.csv # write CSV to FILE.csv - - Regular expressions - hledger uses regular expressions in a number of places: - - o query terms, on the command line and in the hledger-web search form: - REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX - - o CSV rules conditional blocks: if REGEX ... - - o account alias directives and options: alias /REGEX/ = REPLACEMENT, - --alias /REGEX/=REPLACEMENT - - hledger's regular expressions come from the regex-tdfa library. In - general they: - - o are case insensitive - - o are infix matching (do not need to match the entire thing being - matched) - - o are POSIX extended regular expressions - - o also support GNU word boundaries (\<, \>, \b, \B) - - o and parenthesised capturing groups and numeric backreferences in - replacement strings - - o do not support mode modifiers like (?s) - - Some things to note: - - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, - these are not required. - - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts - with the dollar sign in hledger-web, write cur:\$. - - o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped at least once more. See Spe- - cial characters. - -QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a - web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate - the match. - - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match - (or negatively match): - - o any of the description terms AND - - o any of the account terms AND - - o any of the status terms AND - - o all the other terms. - - The print command instead shows transactions which: - - o match any of the description terms AND - - o have any postings matching any of the positive account terms AND - - o have no postings matching any of the negative account terms AND - - o match all the other terms. - - The following kinds of search terms can be used. Remember these can - also be prefixed with not:, eg to exclude a particular subaccount. - - REGEX, acct:REGEX - match account names by this regular expression. (With no pre- - fix, acct: is assumed.) - same as above - - amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not - tested, and will always match.) The comparison has two modes: if - N is preceded by a + or - sign (or is 0), the two signed numbers - are compared. Otherwise, the absolute magnitudes are compared, - ignoring sign. - - code:REGEX - match by transaction code (eg check number) - - cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- - tial match, use .*REGEX.*). Note, to match characters which are - regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: - hledger print cur:'\$' or hledger print cur:\\$. - - desc:REGEX - match transaction descriptions. - - date:PERIODEXPR - match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary - dates instead. - - date2:PERIODEXPR - match secondary dates within the specified period. - - depth:N - match (or display, depending on command) accounts at or above - this depth - - note:REGEX - match transaction notes (part of description right of |, or - whole description when there's no |) - - payee:REGEX - match transaction payee/payer names (part of description left of - |, or whole description when there's no |) - - real:, real:0 - match real or virtual postings respectively - - status:, status:!, status:* - match unmarked, pending, or cleared transactions respectively - - tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the - tags of their parent transaction. - - The following special search term is used automatically in hledger-web, - only: - - inacct:ACCTNAME - tells hledger-web to show the transaction register for this - account. Can be filtered further with acct etc. - - Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps - excluding the -p/--period option). - -COMMANDS - hledger provides a number of subcommands; hledger with no arguments - shows a list. - - If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as - subcommands. - - Run a subcommand by writing its name as first argument (eg - hledger incomestatement). You can also write one of the standard short - aliases displayed in parentheses in the command list (hledger b), or - any any unambiguous prefix of a command name (hledger inc). - - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for - detailed command help. - - accounts - Show account names. Alias: a. - - --declared - show account names declared with account directives - - --used show account names posted to by transactions - - --tree show short account names and their parents, as a tree - - --flat show full account names, as a list (default) - - --drop=N - in flat mode: omit N leading account name parts - - This command lists account names, either declared with account direc- - tives (-declared), posted to (-used), or both (default). With query - arguments, only matched account names and account names referenced by - matched postings are shown. It shows a flat list by default. With - --tree, it uses indentation to show the account hierarchy. In flat - mode you can add --drop N to omit the first few account name compo- - nents. Account names can be depth-clipped with --depth N or depth:N. - - Examples: - - $ hledger accounts --tree - assets - bank - checking - saving - cash - expenses - food - supplies - income - gifts - salary - liabilities - debts - - $ hledger accounts --drop 1 - bank:checking - bank:saving - cash - food - supplies - gifts - salary - debts - - $ hledger accounts - assets:bank:checking - assets:bank:saving - assets:cash - expenses:food - expenses:supplies - income:gifts - income:salary - liabilities:debts - - activity - Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the - default). With query arguments, it counts only matched transactions. - - $ hledger activity --quarterly - 2008-01-01 ** - 2008-04-01 ******* - 2008-07-01 - 2008-10-01 ** - - add - Prompt for transactions and add them to the journal. - - --no-new-accounts - don't allow creating new accounts; helps prevent typos when - entering account names - - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the journal file (if there are multiple - -f FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal - file. - - To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press - control-d or control-c to exit. - - Features: - - o add tries to provide useful defaults, using the most similar recent - transaction (by description) as a template. - - o You can also set the initial defaults with command line arguments. - - o Readline-style edit keys can be used during data entry. - - o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is - empty, it will insert the default value. - - o If the journal defines a default commodity, it will be added to any - bare numbers entered. - - o A parenthesised transaction code may be entered following a date. - - o Comments and tags may be entered following a description or amount. - - o If you make a mistake, enter < at any prompt to restart the transac- - tion. - - o Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see the tutorial for a detailed explanation): - - $ hledger add - Adding transactions to journal file /src/hledger/examples/sample.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to restart the transaction. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2015/05/22]: - Description: supermarket - Account 1: expenses:food - Amount 1: $10 - Account 2: assets:checking - Amount 2 [$-10.0]: - Account 3 (or . or enter to finish this transaction): . - 2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2015/05/22]: $ - - balance - Show accounts and their balances. Aliases: b, bal. - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports) - - -H --historical - show historical ending balance in each period (includes postings - before report start date) - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv, html. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - --pretty-tables - use unicode to display prettier tables. - - --sort-amount - sort by amount instead of account code/name (in flat mode). - With multiple columns, sorts by the row total, or by row average - if that is displayed. - - --invert - display all amounts with reversed sign - - --budget - show performance compared to budget goals defined by periodic - transactions - - --show-unbudgeted - with -budget, show unbudgeted accounts also - - The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may - be more convenient for that. - - By default, it displays all accounts, and each account's change in bal- - ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a - different time period, changes from only cleared transactions, etc. - - If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- - tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show - real-world account balances. In some cases the -H/-historical flag is - used to ensure this (more below). - - The balance command can produce several styles of report: - - Classic balance report - This is the original balance report, as found in Ledger. It usually - looks like this: - - $ 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 - - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with - -S/--sort-amount, by their balance amount. - - "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to - prevent this. - - Account balances are "inclusive" - they include the balances of any - subaccounts. - - Accounts which have zero balance (and no non-zero subaccounts) are - omitted. Use -E/--empty to show them. - - A final total is displayed by default; use -N/--no-total to suppress - it, eg: - - $ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies - - Customising the classic balance report - You can customise the layout of classic balance reports with --for- - mat 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 - - Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "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 or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise - a complex set of accounts and get an overview. - - $ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Flat-mode balance reports, which normally show exclusive balances, show - inclusive balances at the depth limit. - - Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting - interval. - - There are three types of multicolumn 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 - - Multicolumn 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 - - Limitations: - - In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end - date). - - Eliding of boring parent accounts in tree mode, as in the classic bal- - ance report, is not yet supported in multicolumn reports. - - Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. -budget is most often combined with - a report interval. - - 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 report: - - $ hledger balance -M --budget - Budget performance in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 - ======================++================================================= - || $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 - - By default, only accounts with budget goals during the report period - are shown. --show-unbudgeted shows unbudgeted accounts as well. - Top-level accounts with no budget goals anywhere below them are grouped - under . - - You can roll over unspent budgets to next period with --cumulative: - - $ hledger balance -M --budget --cumulative - Budget performance in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 - ======================++================================================= - || $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 - - Note, the -S/--sort-amount flag is not yet fully supported with --bud- - get. - - For more examples, see Budgeting and Forecasting. - - Output format - The balance command supports output destination and output format - selection. - - balancesheet - This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or - liability account (case insensitive, plural forms also allowed). Note - this report shows all account balances with normal positive sign (like - conventional financial statements, unlike balance/print/register) - (experimental). (bs) - - --change - show balance change in each period, instead of historical ending - balances - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of historical ending balances - - -H --historical - show historical ending balance in each period (includes postings - before report start date) (default) - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - --sort-amount - sort by amount instead of account code/name - - Example: - - $ hledger balancesheet - Balance Sheet - - Assets: - $-1 assets - $1 bank:saving - $-2 cash - -------------------- - $-1 - - Liabilities: - $1 liabilities:debts - -------------------- - $1 - - Total: - -------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for - a balance sheet; note this means it ignores report begin dates. - - This command also supports output destination and output format selec- - tion. - - balancesheetequity - Just like balancesheet, but also reports Equity (which it assumes is - under a top-level equity account). - - Example: - - $ hledger balancesheetequity - Balance Sheet With Equity - - Assets: - $-2 assets - $1 bank:saving - $-3 cash - -------------------- - $-2 - - Liabilities: - $1 liabilities:debts - -------------------- - $1 - - Equity: - $1 equity:owner - -------------------- - $1 - - Total: - -------------------- - 0 - - cashflow - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all - account balances with normal positive sign (like conventional financial - statements, unlike balance/print/register) (experimental). (cf) - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods - - -H --historical - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row (in simple reports) - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - --sort-amount - sort by amount instead of account code/name - - Example: - - $ hledger cashflow - Cashflow Statement - - Cash flows: - $-1 assets - $1 bank:saving - $-2 cash - -------------------- - $-1 - - Total: - -------------------- - $-1 - - With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report - mode with --change/--cumulative/--historical. - - This command also supports output destination and output format selec- - tion. - - check-dates - Check that transactions are sorted by increasing date. With a query, - only matched transactions' dates are checked. - - check-dupes - Report account names having the same leaf but different prefixes. An - example: http://stefanorodighiero.net/software/hledger-dupes.html - - close - Print closing/opening transactions that bring some or all account bal- - ances to zero and back. Can be useful for bringing asset/liability - balances across file boundaries, or for closing out income/expenses for - a period. This was formerly called "equity", as in Ledger, and that - alias is also accepted. See close -help for more. - - files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - help - Show any of the hledger manuals. - - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide - a full or partial manual name to select one. - - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can - force a particular viewer with the --info, --man, --pager, --cat flags. - - $ hledger help - Please choose a manual by typing "hledger help MANUAL" (a substring is ok). - Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot - - $ hledger help h --man - - hledger(1) hledger User Manuals hledger(1) - - NAME - hledger - a command-line accounting tool - - SYNOPSIS - hledger [-f FILE] COMMAND [OPTIONS] [ARGS] - hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] - hledger - - DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any - ... - - import - Read new transactions added to each FILE since last run, and add them - to the main journal file. - - --dry-run - just show the transactions to be imported - - The input files are specified as arguments - no need to write -f before - each one. So eg to add new transactions from all CSV files to the main - journal, it's just: hledger import *.csv - - New transactions are detected in the same way as print -new: by assum- - ing transactions are always added to the input files in increasing date - order, and by saving .latest.FILE state files. - - The -dry-run output is in journal format, so you can filter it, eg to - see only uncategorised transactions: - - $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions - - incomestatement - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, - unlike balance/print/register) (experimental). (is) - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods - - -H --historical - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - --sort-amount - sort by amount instead of account code/name - - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense - (plural forms also allowed.) - - $ hledger incomestatement - Income Statement - - Revenues: - $-2 income - $-1 gifts - $-1 salary - -------------------- - $-2 - - Expenses: - $2 expenses - $1 food - $1 supplies - -------------------- - $2 - - Total: - -------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the - report mode with --change/--cumulative/--historical. - - This command also supports output destination and output format selec- - tion. - - prices - Print market price directives from the journal. With -costs, also - print synthetic market prices based on transaction prices. With - -inverted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. - - print - Show transactions from the journal. Aliases: p, txns. - - -m STR --match=STR - show the transaction whose description is most similar to STR, - and is most recent - - --new show only newer-dated transactions added in each file since last - run - - -x --explicit - show all amounts explicitly - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - $ hledger print - 2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - 2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - - 2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - - 2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - - 2008/12/31 * pay off - liabilities:debts $1 - assets:bank:checking $-1 - - The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. print's output is always - a valid hledger journal. It preserves all transaction information, but - it does not preserve directives or inter-transaction comments - - Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all - amounts explicit, which can be useful for troubleshooting or for making - your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- - put. - - With -B/--cost, amounts with transaction prices are converted to cost - using that price. This can be used for troubleshooting. - - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is - no similar-enough match, no transaction will be shown. - - With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV - files. Eg: - - $ hledger -f bank1.csv print --new - # shows transactions added since last print --new on this file - - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get - reordered. See also the import command. - - This command also supports output destination and output format selec- - tion. Here's an example of print's CSV output: - - $ hledger print -Ocsv - "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" - "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" - "1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" - "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" - "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" - "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" - "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" - "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" - "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" - "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" - "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" - "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - o There is one CSV record per posting, with the parent transaction's - fields repeated. - - o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different - order, etc.) - - o The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - - o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or - greater amounts under debit.) - - print-unique - Print transactions which do not reuse an already-seen description. - - register - Show postings and their running total. Aliases: r, reg. - - --cumulative - show running total from report start date (default) - - -H --historical - show historical running total/balance (includes postings before - report start date) - - -A --average - show running average of posting amounts instead of total - (implies -empty) - - -r --related - show postings' siblings instead - - -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M - sets description width as well) - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular - account, to see that account's activity: - - $ hledger register checking - 2008/01/01 income assets:bank:checking $1 $1 - 2008/06/01 gift assets:bank:checking $1 $2 - 2008/06/02 save assets:bank:checking $-1 $1 - 2008/12/31 pay off assets:bank:checking $-1 0 - - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see - only recent activity, with a historically accurate running balance: - - $ hledger register checking -b 2008/6 --historical - 2008/06/01 gift assets:bank:checking $1 $2 - 2008/06/02 save assets:bank:checking $-1 $1 - 2008/12/31 pay off assets:bank:checking $-1 0 - - The --depth option limits the amount of sub-account detail displayed. - - The --average/-A flag shows the running average posting amount instead - of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one - account and one commodity. - - The --related/-r flag shows the other postings in the transactions of - the postings which would normally be shown. - - With a reporting interval, register shows summary postings, one per - interval, aggregating the postings to each account: - - $ hledger register --monthly income - 2008/01 income:salary $-1 $-1 - 2008/06 income:gifts $-1 $-2 - - Periods with no activity, and summary postings with a zero amount, are - not shown by default; use the --empty/-E flag to see them: - - $ hledger register --monthly income -E - 2008/01 income:salary $-1 $-1 - 2008/02 0 $-1 - 2008/03 0 $-1 - 2008/04 0 $-1 - 2008/05 0 $-1 - 2008/06 income:gifts $-1 $-2 - 2008/07 0 $-2 - 2008/08 0 $-2 - 2008/09 0 $-2 - 2008/10 0 $-2 - 2008/11 0 $-2 - 2008/12 0 $-2 - - Often, you'll want to see just one line per interval. The --depth - option helps with this, causing subaccounts to be aggregated: - - $ hledger register --monthly assets --depth 1h - 2008/01 assets $1 $1 - 2008/06 assets $-1 0 - 2008/12 assets $-1 $-1 - - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full - length and comparable to the others in the report. - - Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not - a bash shell variable) or by using the --width/-w option. - - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of -width's argument, comma-separated: - --width W,D . Here's a diagram: - - <--------------------------------- width (W) ----------------------------------> - date (10) description (D) account (W-41-D) amount (12) balance (12) - DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - and some examples: - - $ hledger reg # use terminal width (or 80 on windows) - $ hledger reg -w 100 # use width 100 - $ COLUMNS=100 hledger reg # set with one-time environment variable - $ export COLUMNS=100; hledger reg # set till session end (or window resize) - $ hledger reg -w 100,40 # set overall width 100, description width 40 - $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - - This command also supports output destination and output format selec- - tion. - - register-match - Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect - already-seen transactions when importing. - - rewrite - Print all transactions, adding custom postings to the matched ones. - - roi - Shows time-weighted (TWR) and money-weighted (IRR) rate of return on - your investments. See roi --help for more. - - stats - Show some journal statistics. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - $ hledger stats - Main journal file : /src/hledger/examples/sample.journal - Included journal files : - Transactions span : 2008-01-01 to 2009-01-01 (366 days) - Last transaction : 2008-12-31 (2333 days ago) - Transactions : 5 (0.0 per day) - Transactions last 30 days: 0 (0.0 per day) - Transactions last 7 days : 0 (0.0 per day) - Payees/descriptions : 5 - Accounts : 8 (depth 3) - Commodities : 1 ($) - - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report - for each report period. - - This command also supports output destination and output format selec- - tion. - - tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With additional QUERY arguments, only transactions matching the - query are considered. - - test - Run built-in unit tests. - - Prints test names and their results on stdout. If any test fails or - gives an error, the exit code will be non-zero. - - Test names include a group prefix. If a (exact, case sensitive) group - prefix, or a full test name is provided as the first argument, only - that group or test is run. - - If a numeric second argument is provided, it will set the randomness - seed, for repeatable results from tests using randomness (currently - none of them). - - This is mainly used by developers, but it's nice to be able to san- - ity-check your installed hledger executable at any time. All tests are - expected to pass - if you ever see otherwise, something has gone wrong, - please report a bug! - -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, but it's superseded now by the built-in roi command. - - Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- - tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good - way to start making your own! - - autosync - hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank - offers OFX Direct Connect. - - chart - hledger-chart.hs is an old pie chart generator, in need of some love. - - check - hledger-check.hs checks more powerful account balance assertions. - -ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the - full terminal width. - - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede addon command options with -- when invoked from - hledger is awkward. - - When input data contains non-ascii characters, a suitable system locale - must be configured (or there will be an unhelpful error). Eg on POSIX, - set LANG to something other than C. - - In a Microsoft Windows CMD window, non-ascii characters and colours are - not supported. - - In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger - add. - - Not all of Ledger's journal file syntax is supported. See file format - differences. - - On large data files, hledger is slower and uses more memory than - Ledger. - -TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug - tracker): - - Successfully installed, but "No command `hledger' found" - stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, - that is ~/.local/bin and ~/.cabal/bin respectively. - - I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may - need to use export. Here's an explanation. - - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide - character" errors - In order to handle non-ascii letters and symbols (like ), hledger needs - an appropriate locale. This is usually configured system-wide; you can - also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, - I'm not sure yet). - - Here's an example of setting the locale temporarily, on ubuntu - gnu/linux: - - $ file my.journal - my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded - $ locale -a - C - en_US.utf8 # <- a UTF8-aware locale is available - POSIX - $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command - - Here's one way to set it permanently, there are probably better ways: - - $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile - $ bash --login - - If we preferred to use eg fr_FR.utf8, we might have to install that - first: - - $ apt-get install language-pack-fr - $ locale -a - C - en_US.utf8 - fr_BE.utf8 - fr_CA.utf8 - fr_CH.utf8 - fr_FR.utf8 - fr_LU.utf8 - POSIX - $ LANG=fr_FR.utf8 hledger -f my.journal print - - Note some platforms allow variant locale spellings, but not all (ubuntu - accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger 1.12 December 2018 hledger(1) + Field separator to expect when reading CSV (default: ',') + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot FIELDNAME + use some other field or tag for the account name + + -I --ignore-assertions + ignore any failing balance assertions + + General reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) + + --date2 + match the secondary date instead (see command help for other + effects) + + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) + + -P --pending + include only pending postings/txns + + -C --cleared + include only cleared postings/txns + + -R --real + include only non-virtual postings + + -NUM --depth=NUM + hide/aggregate accounts or postings more than NUM levels deep + + -E --empty + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + --auto apply automated posting rules to modify transactions. + + --forecast + apply periodic transaction rules to generate future transac- + tions, to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, the + last one takes precedence. + + Some reporting options can also be written as query arguments. + + Command options + To see options for a particular command, including command-specific + options, run: hledger COMMAND -h. + + Command-specific options must be written after the command name, eg: + hledger print -x. + + Additionally, if the command is an addon, you may need to put its + options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + run the addon executable directly: hledger-ui --watch. + + Command arguments + Most hledger commands accept arguments after the command name, which + are often a query, filtering the data in some way. + + Argument files + You can save a set of command line options/arguments in a file, one per + line, and then reuse them by writing @FILENAME in a command line. To + prevent this expansion of @-arguments, precede them with a -- argument. + For more, see Save frequently used options. + + Special characters in arguments and queries + In shell command lines, option and argument values which contain "prob- + lematic" characters, ie spaces, and also characters significant to your + shell such as <, >, (, ), | and $, should be escaped by enclosing them + in quotes or by writing backslashes before the characters. Eg: + + hledger register -p 'last year' "accounts receivable (receiv- + able|payable)" amt:\>100. + + More escaping + Characters significant both to the shell and in regular expressions may + need one extra level of escaping. 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:\\$ + + Even more escaping + When hledger runs an addon executable (eg you type hledger ui, hledger + runs hledger-ui), it de-escapes command-line options and arguments + once, so you might need to triple-escape. Eg in bash, running the ui + command and matching the dollar sign, it's: + + hledger ui cur:'\\$' + + or: + + hledger ui cur:\\\\$ + + If you asked why four slashes above, this may help: + + + unescaped: $ + escaped: \$ + double-escaped: \\$ + triple-escaped: \\\\$ + + (The number of backslashes in fish shell is left as an exercise for the + reader.) + + You can always avoid the extra escaping for addons by running the addon + directly: + + hledger-ui cur:\\$ + + Less escaping + Inside an argument file, or in the search field of hledger-ui or + hledger-web, or at a GHCI prompt, you need one less level of escaping + than at the command line. And backslashes may work better than quotes. + Eg: + + ghci> :main balance cur:\$ + + Command line tips + If in doubt, keep things simple: + + o write options after the command (hledger CMD -OPTIONS ARGS) + + o run add-on executables directly (hledger-ui -OPTIONS ARGS) + + o enclose problematic args in single quotes + + o if needed, also add a backslash to escape regexp metacharacters + + To find out exactly how a command line is being parsed, add --debug=2 + to troubleshoot. + + Unicode characters + hledger is expected to handle unicode (non-ascii) characters, but this + requires a well-configured environment. + + To handle unicode characters in the command line or input data, a sys- + tem locale that can decode them must be configured (POSIX's default C + locale will not work). Eg in bash, you could do: + + export LANG=en_US.UTF-8 + + See Troubleshooting for more about this. + + Unicode characters should appear correctly in hledger's output. For + the hledger and hledger-ui tools, this requires that + + o your terminal supports unicode + + o the terminal's font includes the required unicode glyphs + + o the terminal is configured to display "wide" characters as double + width (otherwise report alignment will be off) + + 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: + + + 2004/10/1, 2004-01-01, exact date, several sepa- + 2004.9.1 rators allowed. Year is + 4+ digits, month is 1-12, + day is 1-31 + 2004 start of year + + 2004/10 start of month + 10/1 month and day in current + year + 21 day in current month + october, oct start of month in current + year + yesterday, today, tomorrow -1, 0, 1 days from today + last/this/next day/week/month/quar- -1, 0, 1 periods from the + ter/year current period + 20181201 8 digit YYYYMMDD with + valid year month and day + 201812 6 digit YYYYMM with valid + year and month + + Counterexamples - malformed digit sequences might give surprising + results: + + + 201813 6 digits with an invalid + month is parsed as start + of 6-digit year + 20181301 8 digits with an invalid + month is parsed as start + of 8-digit year + 20181232 8 digits with an invalid + day gives an error + 201801012 9+ digits beginning with a + valid YYYYMMDD gives an + error + + 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 pre- + ceeding 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" -- + 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 bound- + aries 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 commod- + ity. + + 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 -N euros + 100 assets:euros + + What are they worth at end of nov 3 ? + + $ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date specified, + defaults to today) + + $ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P direc- + tives, not transaction prices (unlike Ledger). + + Currently, -V has a limitation in multicolumn balance reports: it uses + the market prices on the report end date for all columns. (Instead of + the prices on each column's end date.) + + Combining -B and -V + Using -B/--cost and -V/--value together is currently allowed, but the + results are probably not meaningful. Let us know if you find a use for + this. + + Output destination + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- + trolled by the -o/--output-file option. + + $ hledger balance -o - # write to stdout (the default) + $ hledger balance -o FILE # write to FILE + + Output format + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or + HTML. This is controlled by the -O/--output-format option, or by spec- + ifying a .csv or .html file extension with -o/--output-file. + + $ hledger balance -O csv # write CSV to stdout + $ hledger balance -o FILE.csv # write CSV to FILE.csv + + Regular expressions + hledger uses regular expressions in a number of places: + + o query terms, on the command line and in the hledger-web search form: + REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX + + o CSV rules conditional blocks: if REGEX ... + + o account alias directives and options: alias /REGEX/ = REPLACEMENT, + --alias /REGEX/=REPLACEMENT + + hledger's regular expressions come from the regex-tdfa library. In + general they: + + o are case insensitive + + o are infix matching (do not need to match the entire thing being + matched) + + o are POSIX extended regular expressions + + o also support GNU word boundaries (\<, \>, \b, \B) + + o and parenthesised capturing groups and numeric backreferences in + replacement strings + + o do not support mode modifiers like (?s) + + Some things to note: + + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + these are not required. + + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write cur:\$. + + o On the command line, some metacharacters like $ have a special mean- + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. + +QUERIES + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a + web search: one or more space-separated search terms, quotes to enclose + whitespace, prefixes to match specific fields, a not: prefix to negate + the match. + + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match + (or negatively match): + + o any of the description terms AND + + o any of the account terms AND + + o any of the status terms AND + + o all the other terms. + + The print command instead shows transactions which: + + o match any of the description terms AND + + o have any postings matching any of the positive account terms AND + + o have no postings matching any of the negative account terms AND + + o match all the other terms. + + The following kinds of search terms can be used. Remember these can + also be prefixed with not:, eg to exclude a particular subaccount. + + REGEX, acct:REGEX + match account names by this regular expression. (With no pre- + fix, acct: is assumed.) + 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 + accounts, a + Show account names. + + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N + or -N. + + Examples: + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + activity + 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. + + Examples: + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + + add + add + Prompt for transactions and add them to the journal. + + 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 (by + description) recent transaction (filtered by the query, if any) 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 + balance, bal, b + Show accounts and their balances. + + The balance command is hledger's most versatile command. Note, despite + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may + be more convenient for that. + + By default, it displays all accounts, and each account's change in bal- + ance during the entire period of the journal. Balance changes are cal- + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a + different time period, changes from only cleared transactions, etc. + + If you include an account's complete history of postings in the report, + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- + tions in the journal; instead you'll have all transactions after a cer- + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show + real-world account balances. In some cases the -H/--historical flag is + used to ensure this (more below). + + The balance command can produce several styles of report: + + Classic balance report + This is the original balance report, as found in Ledger. It usually + looks like this: + + $ 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 + + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with + -S/--sort-amount, by their balance amount. + + "Boring" accounts, which contain a single interesting subaccount and no + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to + prevent this. + + Account balances are "inclusive" - they include the balances of any + subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are + omitted. Use -E/--empty to show them. + + A final total is displayed by default; use -N/--no-total to suppress + it, eg: + + $ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + + Customising the classic balance report + You can customise the layout of classic balance reports with --for- + mat 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 + + Flat mode + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "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 or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise + a complex set of accounts and get an overview. + + $ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Flat-mode balance reports, which normally show exclusive balances, show + inclusive balances at the depth limit. + + Multicolumn balance report + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting + interval. + + There are three types of multicolumn 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 + + Multicolumn 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). With --budget, --empty also shows unbudgeted + accounts. + + 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 + + Limitations: + + In multicolumn reports the -V/--value flag uses the market price on the + report end date, for all columns (not the price on each column's end + date). + + Eliding of boring parent accounts in tree mode, as in the classic bal- + ance report, is not yet supported in multicolumn reports. + + Budget report + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual + income, expenses, time usage, etc. --budget is most often combined + with a report interval. + + 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 report: + + $ hledger balance -M --budget + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + By default, only accounts with budget goals during the report period + are shown. In the example above, transactions in expenses:gifts and + expenses:supplies are counted towards expenses budget, but accounts + expenses:gifts and expenses:supplies are not shown, as they don't have + any budgets. + + You can use --empty shows unbudgeted accounts as well: + + $ hledger balance -M --budget --empty + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with --cumulative: + + $ hledger balance -M --budget --cumulative + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + Note, the -S/--sort-amount flag is not yet fully supported with --bud- + get. + + For more examples, see Budgeting and Forecasting. + + Nested budgets + You can add budgets to any account in your account hierarchy. If you + have budgets on both parent account and some of its children, then bud- + get(s) of the child account(s) would be added to the budget of their + parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any + account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity + means that budget for both expenses:personal and expenses is $1100. + + Transactions in expenses:personal:electronics will be counted both + towards its $100 budget and $1100 of expenses:personal , and transac- + tions in any other subaccount of expenses:personal would be counted + towards only towards the budget of expenses:personal. + + For example, let's consider these transactions: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + 2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + + 2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + + 2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + + 2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- + tions would be counted towards budgets of expenses:personal:electronics + and expenses:personal accordingly: + + $ hledger balance --budget -M + Budget performance in 2019/01: + + || Jan + ===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] + -------------------------------++------------------------------- + || 0 [ 0] + + And with --empty, we can get a better picture of budget allocation and + consumption: + + $ hledger balance --budget -M --empty + Budget performance in 2019/01: + + || Jan + ========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] + ----------------------------------------++------------------------------- + || 0 [ 0] + + Output format + The balance command supports output destination and output format + selection. + + balancesheet + balancesheet, bs + This command displays a simple balance sheet, showing historical ending + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). + + Note this report shows all account balances with normal positive sign + (like conventional financial statements, unlike balance/print/register) + (experimental). + + Example: + + $ hledger balancesheet + Balance Sheet + + Assets: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Total: + -------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for each + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates. + + This command also supports output destination and output format selec- + tion. + + balancesheetequity + balancesheetequity, bse + Just like balancesheet, but also reports Equity (which it assumes is + under a top-level equity account). + + Example: + + $ hledger balancesheetequity + Balance Sheet With Equity + + Assets: + $-2 assets + $1 bank:saving + $-3 cash + -------------------- + $-2 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Equity: + $1 equity:owner + -------------------- + $1 + + Total: + -------------------- + 0 + + cashflow + cashflow, cf + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all + account balances with normal positive sign (like conventional financial + statements, unlike balance/print/register) (experimental). + + Example: + + $ hledger cashflow + Cashflow Statement + + Cash flows: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Total: + -------------------- + $-1 + + With a reporting interval, multiple columns will be shown, one for each + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report + mode with --change/--cumulative/--historical. + + This command also supports output destination and output format selec- + tion. + + check-dates + check-dates + Check that transactions are sorted by increasing date. With --date2, + checks secondary dates instead. With --strict, dates must also be + unique. With a query, only matched transactions' dates are checked. + Reads the default journal file, or another specified with -f. + + check-dupes + check-dupes + Reports account names having the same leaf but different prefixes. In + other words, two or more leaves that are categorized differently. + Reads the default journal file, or another specified as an argument. + + An example: http://stefanorodighiero.net/software/hledger-dupes.html + + close + close, equity + Prints a "closing balances" transaction and an "opening balances" + transaction that bring account balances to and from zero, respectively. + Useful for bringing asset/liability balances forward into a new journal + file, or for closing out revenues/expenses to retained earnings at the + end of a period. + + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- + ing balances". You can chose to print just one of the transactions by + using the --opening or --closing flag. + + If you split your journal files by time (eg yearly), you will typically + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- + ing|closing) balances'.) + + If you're running a business, you might also use this command to "close + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to + change the equity account name to something like "equity:retained earn- + ings".) + + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + You can also use -p or date:PERIOD (any starting date is ignored). + + Both transactions will include balance assertions for the + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- + erated balance assertions will depend on these flags. Likewise, if you + run this command with --auto, the balance assertions will probably + always require --auto. + + Examples: + + Carrying asset/liability balances into a new file for 2019, all from + command line: + + Warning: we use >> here to append; be careful not to type a single > + which would wipe your journal! + + $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal + $ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + + Now: + + $ hledger bs -f 2019.journal # one file - balances are correct + $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct + $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + + Transactions spanning the closing date can complicate matters, breaking + balance assertions: + + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + + Here's one way to resolve that: + + ; in 2018.journal: + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + + ; in 2019.journal: + 2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking + + files + files + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + help + 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. + + Examples: + + $ 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 + import + Read new transactions added to each FILE since last run, and add them + to the main journal file. Or with --dry-run, just print the transac- + tions that would be added. + + 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 + incomestatement, is + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, + unlike balance/print/register) (experimental). + + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense + (plural forms also allowed.) + + $ hledger incomestatement + Income Statement + + Revenues: + $-2 income + $-1 gifts + $-1 salary + -------------------- + $-2 + + Expenses: + $2 expenses + $1 food + $1 supplies + -------------------- + $2 + + Total: + -------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for each + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. + + This command also supports output destination and output format selec- + tion. + + prices + prices + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With + --inverted-costs, also print inverse prices based on transaction + prices. Prices (and postings providing prices) can be filtered by a + query. + + print + print, txns, p + Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from the + journal file in date order, tidily formatted. With --date2, transac- + tions are sorted by secondary date instead. + + print's output is always a valid hledger journal. + It preserves all transaction information, but it does not preserve + directives or inter-transaction comments + + $ 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 + + Normally, the journal entry's explicit or implicit amount style is pre- + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all + amounts explicit, which can be useful for troubleshooting or for making + your journal more readable and robust against data entry errors. Note, + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- + put. + + With -B/--cost, amounts with transaction prices are converted to cost + using that price. This can be used for troubleshooting. + + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is + no similar-enough match, no transaction will be shown. + + With --new, for each FILE being read, hledger reads (and writes) a spe- + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for + ignoring already-seen entries in import data, such as downloaded CSV + files. Eg: + + $ hledger -f bank1.csv print --new + # shows transactions added since last print --new on this file + + This assumes that transactions added to FILE always have same or + increasing dates, and that transactions on the same day do not get + reordered. See also the import command. + + This command also supports output destination and output format selec- + tion. Here's an example of print's CSV output: + + $ hledger print -Ocsv + "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" + "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" + "1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" + "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" + "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" + "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" + "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" + "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" + "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" + "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o The "txnidx" (transaction index) field shows which postings belong to + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different + order, etc.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + print-unique + print-unique + Print transactions which do not reuse an already-seen description. + + Example: + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + + register + register, reg, r + Show postings and their running total. + + The register command displays postings in date order, 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 + + With --date2, it shows and sorts by secondary date instead. + + 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 (won't display correctly in --help): + + <--------------------------------- 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, & description width 40 + + This command also supports output destination and output format selec- + tion. + + register-match + register-match + Print the one posting whose transaction description is closest to DESC, + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps + ledger-autosync detect already-seen transactions when importing. + + rewrite + rewrite + Print all transactions, rewriting the postings of matched transactions. + For now the only rewrite available is adding new postings, like print + --auto. + + This is a start at a generic rewriter of transaction entries. It reads + the default journal and prints the transactions, like print, but adds + one or more specified postings to any transactions matching QUERY. The + posting amounts can be fixed, or a multiplier of the existing transac- + tion's first posting amount. + + Examples: + + hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' + hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' + hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + + = ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the + two spaces between account and amount. + + More: + + $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... + $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' + $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' + $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can + use '*' (star symbol) before the amount to indicate that that this is a + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- + modity. + + Re-write rules in a file + During the run this tool will execute so called "Automated Transac- + tions" found in any journal it process. I.e instead of specifying this + operations in command line you can put them in a journal file. + + $ rewrite-rules.journal + + Make contents look like this: + + = ^income + (liabilities:tax) *.33 + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that '=' (equality symbol) that is used instead of date in trans- + actions you usually write. It indicates the query by which you want to + match the posting to add new ones. + + $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + + $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- + ings. + + Diff output format + To use this tool for batch modification of your journal files you may + find useful output in form of unified diff. + + $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + + --- /tmp/examples/sample.journal + +++ /tmp/examples/sample.journal + @@ -18,3 +18,4 @@ + 2008/01/01 income + - assets:bank:checking $1 + + assets:bank:checking $1 + income:salary + + (liabilities:tax) 0 + @@ -22,3 +23,4 @@ + 2008/06/01 gift + - assets:bank:checking $1 + + assets:bank:checking $1 + income:gifts + + (liabilities:tax) 0 + + If you'll pass this through patch tool you'll get transactions contain- + ing the posting that matches your query be updated. Note that multiple + files might be update according to list of input files specified via + --file options and include directives inside of these files. + + Be careful. Whole transaction being re-formatted in a style of output + from hledger print. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + rewrite vs. print --auto + This command predates print --auto, and currently does much the same + thing, but with these differences: + + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + + o rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + + o rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. + + roi + roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + on your investments. + + This command assumes that you have account(s) that hold nothing but + your investments and whenever you record current appraisal/valuation of + these investments you offset unrealized profit and loss into account(s) + that, again, hold nothing but unrealized profit and loss. + + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to + be your investments or withdrawals. + + At a minimum, you need to supply a query (which could be just an + account name) to select your investments with --inv, and another query + to identify your profit and loss transactions with --pnl. + + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, + regardless of the length of reporting interval. + + stats + stats + Show some journal statistics. + + 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. + + Example: + + $ 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 ($) + + This command also supports output destination and output format selec- + tion. + + tags + 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 QUERY arguments, only transactions matching the query are + considered. + + test + test + Run built-in unit tests. + + This command runs the unit tests built in to hledger-lib and hledger, + printing test names and results on stdout. If any test fails, the exit + code will be non-zero. + + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only + that group or test is run. + + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently + none of them). + + This is mainly used by developers, but it's nice to be able to san- + ity-check your installed hledger executable at any time. All tests are + expected to pass - if you ever see otherwise, something has gone wrong, + please report a bug! + +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, but it's superseded now by the built-in roi command. + + Experimental add-ons + These are available in source form in the hledger repo's bin/ direc- + tory; installing them is pretty easy. They may be less mature and doc- + umented than built-in commands. Reading and tweaking these is a good + way to start making your own! + + autosync + hledger-autosync is a symbolic link for easily running ledger-autosync, + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank + offers OFX Direct Connect. + + chart + hledger-chart.hs is an old pie chart generator, in need of some love. + + check + hledger-check.hs checks more powerful account balance assertions. + +ENVIRONMENT + COLUMNS The screen width used by the register command. Default: the + full terminal width. + + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede addon command options with -- when invoked from + hledger is awkward. + + When input data contains non-ascii characters, a suitable system locale + must be configured (or there will be an unhelpful error). Eg on POSIX, + set LANG to something other than C. + + In a Microsoft Windows CMD window, non-ascii characters and colours are + not supported. + + In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger + add. + + Not all of Ledger's journal file syntax is supported. See file format + differences. + + On large data files, hledger is slower and uses more memory than + Ledger. + +TROUBLESHOOTING + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug + tracker): + + Successfully installed, but "No command 'hledger' found" + stack and cabal install binaries into a special directory, which should + be added to your PATH environment variable. Eg on unix-like systems, + that is ~/.local/bin and ~/.cabal/bin respectively. + + I set a custom LEDGER_FILE, but hledger is still using the default file + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may + need to use export. Here's an explanation. + + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + character" errors + In order to handle non-ascii letters and symbols (like ), hledger needs + an appropriate locale. This is usually configured system-wide; you can + also configure it temporarily. The locale may need to be one that sup- + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + I'm not sure yet). + + Here's an example of setting the locale temporarily, on ubuntu + gnu/linux: + + $ file my.journal + my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded + $ locale -a + C + en_US.utf8 # <- a UTF8-aware locale is available + POSIX + $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command + + Here's one way to set it permanently, there are probably better ways: + + $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile + $ bash --login + + If we preferred to use eg fr_FR.utf8, we might have to install that + first: + + $ apt-get install language-pack-fr + $ locale -a + C + en_US.utf8 + fr_BE.utf8 + fr_CA.utf8 + fr_CH.utf8 + fr_FR.utf8 + fr_LU.utf8 + POSIX + $ LANG=fr_FR.utf8 hledger -f my.journal print + + Note some platforms allow variant locale spellings, but not all (ubuntu + accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.13 February 2019 hledger(1) diff --git a/embeddedfiles/hledger_csv.5 b/embeddedfiles/hledger_csv.5 --- a/embeddedfiles/hledger_csv.5 +++ b/embeddedfiles/hledger_csv.5 @@ -1,5 +1,5 @@ -.TH "hledger_csv" "5" "December 2018" "hledger 1.12" "hledger User Manuals" +.TH "hledger_csv" "5" "February 2019" "hledger 1.13" "hledger User Manuals" @@ -29,7 +29,7 @@ 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. +some example rules, which you\[aq]ll need to adjust. .PP At minimum, the rules file must identify the \f[C]date\f[] and \f[C]amount\f[] fields. @@ -90,7 +90,7 @@ \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. +You\[aq]ll need this whenever your CSV data contains header lines. Eg: .IP .nf @@ -104,23 +104,23 @@ \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. +\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 +#\ for\ dates\ like\ "11/06/2013": +date\-format\ %m/%d/%Y \f[] .fi .IP .nf \f[C] -#\ for\ dates\ like\ "11/06/2013": -date\-format\ %m/%d/%Y +#\ for\ dates\ like\ "6/11/2013"\ (note\ the\ \-\ to\ make\ leading\ zeros\ optional): +date\-format\ %\-d/%\-m/%Y \f[] .fi .IP @@ -140,7 +140,7 @@ .SS field list .PP \f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[], -\f[I]\f[CI]FIELDNAME2\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 @@ -192,7 +192,7 @@ .PD 0 .P .PD -\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... +\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]... .PP \f[C]if\f[] .PD 0 @@ -202,16 +202,16 @@ .PD 0 .P .PD -\f[I]\f[CI]PATTERN\f[I]\f[]\&... +\f[I]\f[CI]PATTERN\f[I]\f[]... .PD 0 .P .PD -\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... +\ \ \ \ \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 +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. @@ -244,7 +244,7 @@ .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. +the current file\[aq]s directory. Eg: .IP .nf @@ -261,9 +261,9 @@ 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. +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 @@ -274,8 +274,9 @@ .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 +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 diff --git a/embeddedfiles/hledger_csv.info b/embeddedfiles/hledger_csv.info --- a/embeddedfiles/hledger_csv.info +++ b/embeddedfiles/hledger_csv.info @@ -3,7 +3,7 @@  File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir) -hledger_csv(5) hledger 1.12 +hledger_csv(5) hledger 1.13 *************************** hledger can read CSV (comma-separated value) files as if they were @@ -113,12 +113,12 @@ 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 "6/11/2013" (note the - to make leading zeros optional): +date-format %-d/%-m/%Y + # for dates like "2013-Nov-06": date-format %Y-%h-%d @@ -323,27 +323,27 @@ Ref: #skip2627 Node: date-format2799 Ref: #date-format2926 -Node: field list3432 -Ref: #field-list3569 -Node: field assignment4274 -Ref: #field-assignment4429 -Node: conditional block4933 -Ref: #conditional-block5087 -Node: include5983 -Ref: #include6113 -Node: newest-first6344 -Ref: #newest-first6458 -Node: CSV TIPS6869 -Ref: #csv-tips6963 -Node: CSV ordering7081 -Ref: #csv-ordering7199 -Node: CSV accounts7380 -Ref: #csv-accounts7518 -Node: CSV amounts7772 -Ref: #csv-amounts7918 -Node: CSV balance assertions8693 -Ref: #csv-balance-assertions8875 -Node: Reading multiple CSV files9080 -Ref: #reading-multiple-csv-files9250 +Node: field list3476 +Ref: #field-list3613 +Node: field assignment4318 +Ref: #field-assignment4473 +Node: conditional block4977 +Ref: #conditional-block5131 +Node: include6027 +Ref: #include6157 +Node: newest-first6388 +Ref: #newest-first6502 +Node: CSV TIPS6913 +Ref: #csv-tips7007 +Node: CSV ordering7125 +Ref: #csv-ordering7243 +Node: CSV accounts7424 +Ref: #csv-accounts7562 +Node: CSV amounts7816 +Ref: #csv-amounts7962 +Node: CSV balance assertions8737 +Ref: #csv-balance-assertions8919 +Node: Reading multiple CSV files9124 +Ref: #reading-multiple-csv-files9294  End Tag Table diff --git a/embeddedfiles/hledger_csv.txt b/embeddedfiles/hledger_csv.txt --- a/embeddedfiles/hledger_csv.txt +++ b/embeddedfiles/hledger_csv.txt @@ -88,12 +88,12 @@ 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 "6/11/2013" (note the - to make leading zeros optional): + date-format %-d/%-m/%Y + # for dates like "2013-Nov-06": date-format %Y-%h-%d @@ -249,4 +249,4 @@ -hledger 1.12 December 2018 hledger_csv(5) +hledger 1.13 February 2019 hledger_csv(5) diff --git a/embeddedfiles/hledger_journal.5 b/embeddedfiles/hledger_journal.5 --- a/embeddedfiles/hledger_journal.5 +++ b/embeddedfiles/hledger_journal.5 @@ -1,34 +1,36 @@ .\"t -.TH "hledger_journal" "5" "December 2018" "hledger 1.12" "hledger User Manuals" +.TH "hledger_journal" "5" "February 2019" "hledger 1.13" "hledger User Manuals" .SH NAME .PP -Journal \- hledger's default file format, representing a General Journal +Journal \- hledger\[aq]s default file format, representing a General +Journal .SH DESCRIPTION .PP -hledger's usual data source is a plain text file containing journal +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's not required. +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'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. +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's an example: +Here\[aq]s an example: .IP .nf \f[C] @@ -81,7 +83,7 @@ semicolon until end of line) .PP Then comes zero or more (but usually at least 2) indented lines -representing\&... +representing... .SS Postings .PP A posting is an addition of some amount to, or removal of some amount @@ -134,12 +136,12 @@ 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. +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's an example. +Here\[aq]s an example. Note that a secondary date will use the year of the primary date if unspecified. .IP @@ -203,14 +205,14 @@ .fi .PP DATE should be a simple date; if the year is not specified it will use -the year of the transaction's date. +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's earlier, more compact bracketed date syntax is also supported: -\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]. +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 @@ -254,11 +256,11 @@ \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]. +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's behaviour of also matching +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 @@ -268,9 +270,8 @@ 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: +What "uncleared", "pending", and "cleared" actually mean is up to you. +Here\[aq]s one suggestion: .PP .TS tab(@); @@ -304,10 +305,10 @@ 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. +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 @@ -380,8 +381,8 @@ .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]). +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. @@ -400,8 +401,8 @@ .IP \[bu] 2 scientific E\-notation is allowed. Be careful not to use a digit group separator character in scientific -notation, as it's not supported and it might get mistaken for a decimal -point. +notation, as it\[aq]s not supported and it might get mistaken for a +decimal point. (Declaring the digit group separator character explicitly with a commodity directive will prevent this.) .PP @@ -439,13 +440,13 @@ 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 \f[C]D\f[] directives usually don't affect -amount format inference, but in some situations they can do so +Price amounts and amounts in \f[C]D\f[] directives usually don\[aq]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. +(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 @@ -456,7 +457,7 @@ 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 +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 @@ -490,7 +491,8 @@ .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. +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 @@ -515,7 +517,7 @@ troubleshooting or for reading Ledger files. .SS Assertions and ordering .PP -hledger sorts an account's postings and assertions first by date and +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. @@ -534,31 +536,31 @@ 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. +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't work well across files specified with multiple -\-f options. +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's balance within the +fact the assertion checks only this commodity\[aq]s balance within the (possibly multi\-commodity) account balance. .PD 0 .P .PD This is how assertions work in Ledger also. -We could call this a \[lq]partial\[rq] balance assertion. +We could call this a "partial" balance assertion. .PP To assert the balance of more than one commodity in an account, you can -write multiple postings, each asserting one commodity's balance. +write multiple postings, each asserting one commodity\[aq]s balance. .PP You can make a stronger kind of balance assertion, by writing a double equals sign (\f[C]==EXPECTEDBALANCE\f[]). -This \[lq]complete\[rq] balance assertion asserts the absence of other +This "complete" balance assertion asserts the absence of other commodities (or, that their balance is 0, which to hledger is equivalent.) .IP @@ -581,8 +583,8 @@ \f[] .fi .PP -It's not yet possible to make a complete assertion about a balance that -has multiple commodities. +It\[aq]s not yet possible to make a complete assertion about a balance +that has multiple commodities. One workaround is to isolate each commodity into its own subaccount: .IP .nf @@ -598,10 +600,27 @@ \ \ a:euro\ \ \ 0\ ==\ \ 1€ \f[] .fi +.SS Assertions and prices +.PP +Balance assertions ignore transaction prices, and should normally be +written without one: +.IP +.nf +\f[C] +2019/1/1 +\ \ (a)\ \ \ \ \ $1\ \@\ €1\ =\ $1 +\f[] +.fi +.PP +We do allow prices to be written there, however, and print shows them, +even though they don\[aq]t affect whether the assertion passes or fails. +This is for backward compatibility (hledger\[aq]s close command used to +generate balance assertions with prices), and because balance +\f[I]assignments\f[] do use them (see below). .SS Assertions and subaccounts .PP Balance assertions do not count the balance from subaccounts; they check -the posted account's exclusive balance. +the posted account\[aq]s exclusive balance. For example: .IP .nf @@ -613,7 +632,7 @@ \f[] .fi .PP -The balance report's flat mode shows these exclusive balances more +The balance report\[aq]s flat mode shows these exclusive balances more clearly: .IP .nf @@ -631,6 +650,13 @@ virtual. They are not affected by the \f[C]\-\-real/\-R\f[] flag or \f[C]real:\f[] query. +.SS Assertions and precision +.PP +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. +Eg a commodity directive may limit the display precision, but this will +not affect balance assertions. +Balance assertion failure messages show exact amounts. .SS Balance Assignments .PP Ledger\-style balance assignments are also supported. @@ -662,16 +688,35 @@ \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 +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 Balance assignments and prices +.PP +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: +.IP +.nf +\f[C] +2019/1/1 +\ \ (a)\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $1\ \@\ €2 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ print\ \-\-explicit +2019/01/01 +\ \ \ \ (a)\ \ \ \ \ \ \ \ \ $1\ \@\ €2\ =\ $1\ \@\ €2 +\f[] +.fi .SS Transaction prices .PP -Within a transaction, you can note an amount's price in another +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). @@ -725,8 +770,8 @@ \f[C]{=UNITPRICE}\f[], which hledger currently ignores). .PP Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their -transaction price's commodity, if any. -(mnemonic: \[lq]B\[rq] is from \[lq]cost Basis\[rq], as in Ledger). +transaction price\[aq]s commodity, if any. +(mnemonic: "B" is from "cost Basis", as in Ledger). Eg here is how \-B affects the balance report for the example above: .IP .nf @@ -743,7 +788,7 @@ 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 +So if example 3\[aq]s postings are reversed, while the transaction is equivalent, \-B shows something different: .IP .nf @@ -826,7 +871,8 @@ \f[] .fi .PP -Note this means hledger's tag values can not contain commas or newlines. +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 @@ -838,13 +884,12 @@ .PP Here, .IP \[bu] 2 -\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a -tag +"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag .IP \[bu] 2 -\[lq]\f[C]tag1\f[]\[rq] is a tag with no value +"\f[C]tag1\f[]" 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] +"\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. @@ -860,18 +905,19 @@ \f[] .fi .PP -Tags are like Ledger's metadata feature, except hledger's tag values are -simple strings. +Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag +values are simple strings. .SS Directives .PP A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. -hledger's directives are based on a subset of Ledger's, but there are -many differences (and also some differences between hledger versions). +hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but +there are many differences (and also some differences between hledger +versions). .PP -Directives' behaviour and interactions can get a little bit complex, so -here is a table summarising the directives and their effects, with links -to more detailed docs. +Directives\[aq] behaviour and interactions can get a little bit complex, +so here is a table summarising the directives and their effects, with +links to more detailed docs. .PP .TS tab(@); @@ -1053,8 +1099,8 @@ It can include journal, timeclock or timedot files, but not CSV files. .SS Default year .PP -You can set a default year to be used for subsequent dates which don't -specify a year. +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 @@ -1094,7 +1140,7 @@ \f[] .fi .PP -or on multiple lines, using the \[lq]format\[rq] subdirective. +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 @@ -1123,7 +1169,7 @@ .PP The \f[C]D\f[] 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 +(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 \f[C]D\f[] directive. .IP @@ -1145,9 +1191,9 @@ .PP The \f[C]P\f[] directive declares a market price, which is an exchange rate between two commodities on a certain date. -(In Ledger, they are called \[lq]historical prices\[rq].) These are -often obtained from a stock exchange, cryptocurrency exchange, or the -foreign exchange market. +(In Ledger, they are called "historical prices".) These are often +obtained from a stock exchange, cryptocurrency exchange, or the foreign +exchange market. .PP Here is the format: .IP @@ -1178,8 +1224,7 @@ to another commodity using these prices. .SS Declaring accounts .PP -\f[C]account\f[] directives can be used to pre\-declare some or all -accounts. +\f[C]account\f[] directives can be used to pre\-declare accounts. Though not required, they can provide several benefits: .IP \[bu] 2 They can document your intended chart of accounts, providing a @@ -1188,7 +1233,7 @@ They can store extra information about accounts (account numbers, notes, etc.) .IP \[bu] 2 -They can help hledger know your accounts' types (asset, liability, +They can help hledger know your accounts\[aq] types (asset, liability, equity, revenue, expense), useful for reports like balancesheet and incomestatement. .IP \[bu] 2 @@ -1198,41 +1243,89 @@ They help with account name completion in the add command, hledger\-iadd, hledger\-web, ledger\-mode etc. .PP -Here is the full syntax: +The simplest form is just the word \f[C]account\f[] followed by a +hledger\-style account name, eg: .IP .nf \f[C] -account\ ACCTNAME\ \ [ACCTTYPE] -\ \ [COMMENTS] +account\ assets:bank:checking \f[] .fi +.SS Account comments .PP -The simplest form just declares a hledger\-style account name, eg: +Comments, beginning with a semicolon, optionally including tags, can be +written after the account name, and/or on following lines. +Eg: .IP .nf \f[C] +account\ assets:bank:checking\ \ ;\ a\ comment +\ \ ;\ another\ comment +\ \ ;\ acctno:12345,\ a\ tag +\f[] +.fi +.PP +Tip: comments on the same line require hledger 1.12+. +If you need your journal to be compatible with older hledger versions, +write comments on the next line instead. +.SS Account subdirectives +.PP +We also allow (and ignore) Ledger\-style indented subdirectives, just +for compatibility.: +.IP +.nf +\f[C] account\ assets:bank:checking +\ \ format\ blah\ blah\ \ ;\ <\-\ subdirective,\ ignored \f[] .fi +.PP +Here is the full syntax of account directives: +.IP +.nf +\f[C] +account\ ACCTNAME\ \ [ACCTTYPE]\ [;COMMENT] +\ \ [;COMMENTS] +\ \ [LEDGER\-STYLE\ SUBDIRECTIVES,\ IGNORED] +\f[] +.fi .SS Account types .PP -hledger recognises five types of account: asset, liability, equity, -revenue, expense. -This is useful for certain accounting\-aware reports, in particular -balancesheet, incomestatement and cashflow. +hledger recognises five types (or classes) of account: Asset, Liability, +Equity, Revenue, Expense. +This is used by a few accounting\-aware reports such as balancesheet, +incomestatement and cashflow. +.SS Auto\-detected account types .PP If you name your top\-level accounts with some variation of \f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[], \f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are detected automatically. +.SS Account types declared with tags .PP -More generally, you can declare an account's type by adding one of the -letters \f[C]ALERX\f[] to its account directive, separated from the -account name by two or more spaces. -Eg: +More generally, you can declare an account\[aq]s type with an account +directive, by writing a \f[C]type:\f[] tag in a comment, followed by one +of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[], +\f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[] +(case insensitive): .IP .nf \f[C] +account\ assets\ \ \ \ \ \ \ ;\ type:Asset +account\ liabilities\ \ ;\ type:Liability +account\ equity\ \ \ \ \ \ \ ;\ type:Equity +account\ revenues\ \ \ \ \ ;\ type:Revenue +account\ expenses\ \ \ \ \ ;\ type:Expenses +\f[] +.fi +.SS Account types declared with account type codes +.PP +Or, you can write one of those letters separated from the account name +by two or more spaces, but this should probably be considered deprecated +as of hledger 1.13: +.IP +.nf +\f[C] account\ assets\ \ \ \ \ \ \ A account\ liabilities\ \ L account\ equity\ \ \ \ \ \ \ E @@ -1240,46 +1333,29 @@ account\ expenses\ \ \ \ \ X \f[] .fi +.SS Overriding auto\-detected types .PP -Note: if you ever override the types of those auto\-detected english -account names mentioned above, you might need to help the reports a bit: +If you ever override the types of those auto\-detected english account +names mentioned above, you might need to help the reports a bit. +Eg: .IP .nf \f[C] -;\ make\ "liabilities"\ not\ have\ the\ liability\ type,\ who\ knows\ why -account\ liabilities\ \ \ E +;\ make\ "liabilities"\ not\ have\ the\ liability\ type\ \-\ who\ knows\ why +account\ liabilities\ \ \ ;\ type:E -;\ better\ ensure\ some\ other\ account\ has\ the\ liability\ type,\ +;\ we\ need\ to\ ensure\ some\ other\ account\ has\ the\ liability\ type,\ ;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\ -account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ L -\f[] -.fi -.PP -) -.SS Account comments -.PP -An account directive can also have indented comments on following lines, -eg: -.IP -.nf -\f[C] -account\ assets:bank:checking -\ \ ;\ acctno:12345 -\ \ ;\ a\ comment +account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ ;\ type:L \f[] .fi -.PP -We also allow (and ignore) Ledger\-style subdirectives, with no leading -semicolon, for compatibility. -.PP -Tags in account comments, like \f[C]acctno\f[] above, currently have no -effect. .SS Account display order .PP -Account directives also set the order in which accounts are displayed in -reports, the hledger\-ui accounts screen, the hledger\-web sidebar, etc. -Normally accounts are listed in alphabetical order, but if you have eg -these account directives in the journal: +Account directives also set the order in which accounts are displayed, +eg in reports, the hledger\-ui accounts screen, and the hledger\-web +sidebar. +By default accounts are listed in alphabetical order. +But if you have these account directives in the journal: .IP .nf \f[C] @@ -1291,7 +1367,7 @@ \f[] .fi .PP -you'll see those accounts listed in declaration order, not +you\[aq]ll see those accounts displayed in declaration order, not alphabetically: .IP .nf @@ -1317,13 +1393,14 @@ \f[] .fi .PP -would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s +would influence the position of \f[C]zoo\f[] among \f[C]other\f[]\[aq]s subaccounts, but not the position of \f[C]other\f[] among the top\-level accounts. This means: \- you will sometimes declare parent accounts (eg -\f[C]account\ other\f[] above) that you don't intend to post to, just to -customize their display order \- sibling accounts stay together (you -couldn't display \f[C]x:y\f[] in between \f[C]a:b\f[] and \f[C]a:c\f[]). +\f[C]account\ other\f[] above) that you don\[aq]t intend to post to, +just to customize their display order \- sibling accounts stay together +(you couldn\[aq]t display \f[C]x:y\f[] in between \f[C]a:b\f[] and +\f[C]a:c\f[]). .SS Rewriting accounts .PP You can define account alias rules which rewrite your account names, or @@ -1362,7 +1439,7 @@ 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. +It\[aq]s useful for trying out aliases interactively. .PP OLD and NEW are case sensitive full account names. hledger will replace any occurrence of the old account name with the new @@ -1508,23 +1585,22 @@ .PP Partial or relative dates (M/D, D, tomorrow, last week) in the period expression can work (useful or not). -They will be relative to today's date, unless a Y default year directive -is in effect, in which case they will be relative to Y/1/1. +They will be relative to today\[aq]s date, unless a Y default year +directive is in effect, in which case they will be relative to Y/1/1. +.SS Two spaces after the period expression .PP -Period expressions must be terminated by \f[B]two or more spaces\f[] if -followed by additional fields. -For example, the periodic transaction given below includes a transaction -description \[lq]paycheck\[rq], which is separated from the period -expression by a double space. -If not for the second space, hledger would attempt (and fail) to parse -\[lq]paycheck\[rq] as a part of the period expression. +If the period expression is followed by a transaction description, these +must be separated by \f[B]two or more spaces\f[]. +This helps hledger know where the period expression ends, so that +descriptions can not accidentally alter their meaning, as in this +example: .IP .nf \f[C] -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv -~\ every\ 2\ weeks\ from\ 2018/6/4\ to\ 2018/9\ \ paycheck +;\ 2\ or\ more\ spaces\ needed\ here,\ so\ the\ period\ is\ not\ understood\ as\ "every\ 2\ months\ in\ 2020" +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv +~\ every\ 2\ months\ \ in\ 2020,\ we\ will\ review \ \ \ \ assets:bank:checking\ \ \ $1500 \ \ \ \ income:acme\ inc \f[] @@ -1553,9 +1629,9 @@ ends on the report end date if specified with \-e/\-p/date:, or 180 days from today. .PP -where \[lq]today\[rq] means the current date at report time. -The \[lq]later of\[rq] rule ensures that forecast transactions do not -overlap normal transactions in time; they will begin only after normal +where "today" means the current date at report time. +The "later of" rule ensures that forecast transactions do not overlap +normal transactions in time; they will begin only after normal transactions end. .PP Forecasting can be useful for estimating balances into the future, and @@ -1583,18 +1659,19 @@ For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. .PP -.SS Transaction Modifiers +.SS Transaction modifiers .PP Transaction modifier rules describe changes that should be applied automatically to certain transactions. -Currently, this means adding extra postings (also known as -\[lq]automated postings\[rq]). -Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. +They can be enabled by using the \f[C]\-\-auto\f[] flag. +Currently, just one kind of change is possible: adding extra postings. +These rule\-generated postings are known as "automated postings" or +"auto postings". .PP A transaction modifier rule looks quite like a normal transaction, except the first line is an equals sign followed by a query that matches certain postings (mnemonic: \f[C]=\f[] suggests matching). -And each \[lq]posting\[rq] is actually a posting\-generating rule: +And each "posting" is actually a posting\-generating rule: .IP .nf \f[C] @@ -1605,8 +1682,7 @@ \f[] .fi .PP -The posting rules look just like normal postings, except the amount can -be: +These posting rules look like normal postings, except the amount can be: .IP \[bu] 2 a normal amount with a commodity symbol, eg \f[C]$2\f[]. This will be used as\-is. @@ -1616,13 +1692,13 @@ this. .IP \[bu] 2 a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N). -The matched posting's amount (and total price, if any) will be +The matched posting\[aq]s amount (and total price, if any) will be multiplied by N. .IP \[bu] 2 a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N, and symbol S). -The matched posting's amount will be multiplied by N, and its commodity -symbol will be replaced with S. +The matched posting\[aq]s amount will be multiplied by N, and its +commodity symbol will be replaced with S. .PP Some examples: .IP @@ -1662,10 +1738,19 @@ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20 \f[] .fi +.SS Auto postings and transaction balancing / inferred amounts / balance +assertions .PP -Postings added by transaction modifiers participate in transaction -balancing, missing amount inference and balance assertions, like regular -postings. +Currently, transaction modifiers are applied / auto postings are added: +.IP \[bu] 2 +after missing amounts are inferred, and transactions are checked for +balancedness, +.IP \[bu] 2 +but before balance assertions are checked. +.PP +Note this means that journal entries must be balanced both before and +after auto postings are added. +This changed in hledger 1.12+; see #893 for background. .SH EDITOR SUPPORT .PP Add\-on modes exist for various text editors, to make working with diff --git a/embeddedfiles/hledger_journal.info b/embeddedfiles/hledger_journal.info --- a/embeddedfiles/hledger_journal.info +++ b/embeddedfiles/hledger_journal.info @@ -4,7 +4,7 @@  File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_journal(5) hledger 1.12 +hledger_journal(5) hledger 1.13 ******************************* hledger's usual data source is a plain text file containing journal @@ -82,7 +82,7 @@ * Tags:: * Directives:: * Periodic transactions:: -* Transaction Modifiers:: +* Transaction modifiers::  File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT @@ -473,8 +473,10 @@ * Assertions and included files:: * Assertions and multiple -f options:: * Assertions and commodities:: +* Assertions and prices:: * Assertions and subaccounts:: * Assertions and virtual postings:: +* Assertions and precision::  File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions @@ -517,7 +519,7 @@ -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 +File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance Assertions 1.9.4 Assertions and commodities -------------------------------- @@ -566,9 +568,27 @@ a:euro 0 == 1€  -File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions +File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance Assertions -1.9.5 Assertions and subaccounts +1.9.5 Assertions and prices +--------------------------- + +Balance assertions ignore transaction prices, and should normally be +written without one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below). + + +File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance Assertions + +1.9.6 Assertions and subaccounts -------------------------------- Balance assertions do not count the balance from subaccounts; they check @@ -589,9 +609,9 @@ 2  -File: hledger_journal.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions +File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions -1.9.6 Assertions and virtual postings +1.9.7 Assertions and virtual postings ------------------------------------- Balance assertions are checked against all postings, both real and @@ -599,6 +619,17 @@ query.  +File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance Assertions + +1.9.8 Assertions and precision +------------------------------ + +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. Eg a commodity directive may limit the +display precision, but this will not affect balance assertions. Balance +assertion failure messages show exact amounts. + + File: hledger_journal.info, Node: Balance Assignments, Next: Transaction prices, Prev: Balance Assertions, Up: FILE FORMAT 1.10 Balance Assignments @@ -630,8 +661,27 @@ 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. +* Menu: +* Balance assignments and prices:: +  +File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance Assignments + +1.10.1 Balance assignments and prices +------------------------------------- + +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019/01/01 + (a) $1 @ €2 = $1 @ €2 + + File: hledger_journal.info, Node: Transaction prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT 1.11 Transaction prices @@ -1033,8 +1083,8 @@ 1.14.7 Declaring accounts ------------------------- -'account' directives can be used to pre-declare some or all accounts. -Though not required, they can provide several benefits: +'account' directives can be used to pre-declare accounts. Though not +required, they can provide several benefits: * They can document your intended chart of accounts, providing a reference. @@ -1048,86 +1098,108 @@ * They help with account name completion in the add command, hledger-iadd, hledger-web, ledger-mode etc. - Here is the full syntax: - -account ACCTNAME [ACCTTYPE] - [COMMENTS] - - The simplest form just declares a hledger-style account name, eg: + The simplest form is just the word 'account' followed by a +hledger-style account name, eg: account assets:bank:checking * Menu: -* Account types:: * Account comments:: +* Account subdirectives:: +* Account types:: * Account display order::  -File: hledger_journal.info, Node: Account types, Next: Account comments, Up: Declaring accounts +File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts -1.14.7.1 Account types -...................... +1.14.7.1 Account comments +......................... -hledger recognises five types of account: asset, liability, equity, -revenue, expense. This is useful for certain accounting-aware reports, -in particular balancesheet, incomestatement and cashflow. +Comments, beginning with a semicolon, optionally including tags, can be +written after the account name, and/or on following lines. Eg: - If you name your top-level accounts with some variation of 'assets', -'liabilities'/'debts', 'equity', 'revenues'/'income', or 'expenses', -their types are detected automatically. +account assets:bank:checking ; a comment + ; another comment + ; acctno:12345, a tag - More generally, you can declare an account's type by adding one of -the letters 'ALERX' to its account directive, separated from the account -name by two or more spaces. Eg: + Tip: comments on the same line require hledger 1.12+. If you need +your journal to be compatible with older hledger versions, write +comments on the next line instead. -account assets A -account liabilities L -account equity E -account revenues R -account expenses X + +File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts - Note: if you ever override the types of those auto-detected english -account names mentioned above, you might need to help the reports a bit: +1.14.7.2 Account subdirectives +.............................. -; make "liabilities" not have the liability type, who knows why -account liabilities E +We also allow (and ignore) Ledger-style indented subdirectives, just for +compatibility.: -; better ensure some other account has the liability type, -; otherwise balancesheet would still show "liabilities" under Liabilities -account - L +account assets:bank:checking + format blah blah ; <- subdirective, ignored - ) + Here is the full syntax of account directives: +account ACCTNAME [ACCTTYPE] [;COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] +  -File: hledger_journal.info, Node: Account comments, Next: Account display order, Prev: Account types, Up: Declaring accounts +File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts -1.14.7.2 Account comments -......................... +1.14.7.3 Account types +...................... -An account directive can also have indented comments on following lines, -eg: +hledger recognises five types (or classes) of account: Asset, Liability, +Equity, Revenue, Expense. This is used by a few accounting-aware +reports such as balancesheet, incomestatement and cashflow. +Auto-detected account types If you name your top-level accounts with +some variation of 'assets', 'liabilities'/'debts', 'equity', +'revenues'/'income', or 'expenses', their types are detected +automatically. Account types declared with tags More generally, you can +declare an account's type with an account directive, by writing a +'type:' tag in a comment, followed by one of the words 'Asset', +'Liability', 'Equity', 'Revenue', 'Expense', or one of the letters +'ALERX' (case insensitive): -account assets:bank:checking - ; acctno:12345 - ; a comment +account assets ; type:Asset +account liabilities ; type:Liability +account equity ; type:Equity +account revenues ; type:Revenue +account expenses ; type:Expenses - We also allow (and ignore) Ledger-style subdirectives, with no -leading semicolon, for compatibility. + Account types declared with account type codes Or, you can write one +of those letters separated from the account name by two or more spaces, +but this should probably be considered deprecated as of hledger 1.13: - Tags in account comments, like 'acctno' above, currently have no -effect. +account assets A +account liabilities L +account equity E +account revenues R +account expenses X + Overriding auto-detected types If you ever override the types of +those auto-detected english account names mentioned above, you might +need to help the reports a bit. Eg: + +; make "liabilities" not have the liability type - who knows why +account liabilities ; type:E + +; we need to ensure some other account has the liability type, +; otherwise balancesheet would still show "liabilities" under Liabilities +account - ; type:L +  -File: hledger_journal.info, Node: Account display order, Prev: Account comments, Up: Declaring accounts +File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts -1.14.7.3 Account display order +1.14.7.4 Account display order .............................. -Account directives also set the order in which accounts are displayed in -reports, the hledger-ui accounts screen, the hledger-web sidebar, etc. -Normally accounts are listed in alphabetical order, but if you have eg -these account directives in the journal: +Account directives also set the order in which accounts are displayed, +eg in reports, the hledger-ui accounts screen, and the hledger-web +sidebar. By default accounts are listed in alphabetical order. But if +you have these account directives in the journal: account assets account liabilities @@ -1135,7 +1207,7 @@ account revenues account expenses - you'll see those accounts listed in declaration order, not + you'll see those accounts displayed in declaration order, not alphabetically: $ hledger accounts -1 @@ -1306,7 +1378,7 @@ parent account.  -File: hledger_journal.info, Node: Periodic transactions, Next: Transaction Modifiers, Prev: Directives, Up: FILE FORMAT +File: hledger_journal.info, Node: Periodic transactions, Next: Transaction modifiers, Prev: Directives, Up: FILE FORMAT 1.15 Periodic transactions ========================== @@ -1332,32 +1404,36 @@ expression can work (useful or not). They will be relative to today's date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. - - Period expressions must be terminated by *two or more spaces* if -followed by additional fields. For example, the periodic transaction -given below includes a transaction description "paycheck", which is -separated from the period expression by a double space. If not for the -second space, hledger would attempt (and fail) to parse "paycheck" as a -part of the period expression. - -; 2 or more spaces -; || -; vv -~ every 2 weeks from 2018/6/4 to 2018/9 paycheck - assets:bank:checking $1500 - income:acme inc - * Menu: +* Two spaces after the period expression:: * Forecasting with periodic transactions:: * Budgeting with periodic transactions::  -File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Up: Periodic transactions +File: hledger_journal.info, Node: Two spaces after the period expression, Next: Forecasting with periodic transactions, Up: Periodic transactions -1.15.1 Forecasting with periodic transactions +1.15.1 Two spaces after the period expression --------------------------------------------- +If the period expression is followed by a transaction description, these +must be separated by *two or more spaces*. This helps hledger know +where the period expression ends, so that descriptions can not +accidentally alter their meaning, as in this example: + +; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020" +; || +; vv +~ every 2 months in 2020, we will review + assets:bank:checking $1500 + income:acme inc + + +File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces after the period expression, Up: Periodic transactions + +1.15.2 Forecasting with periodic transactions +--------------------------------------------- + With the '--forecast' flag, each periodic transaction rule generates future transactions recurring at the specified interval. These are not saved in the journal, but appear in all reports. They will look like @@ -1398,7 +1474,7 @@  File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -1.15.2 Budgeting with periodic transactions +1.15.3 Budgeting with periodic transactions ------------------------------------------- With the '--budget' flag, currently supported by the balance command, @@ -1412,15 +1488,16 @@ and Forecasting.  -File: hledger_journal.info, Node: Transaction Modifiers, Prev: Periodic transactions, Up: FILE FORMAT +File: hledger_journal.info, Node: Transaction modifiers, Prev: Periodic transactions, Up: FILE FORMAT -1.16 Transaction Modifiers +1.16 Transaction modifiers ========================== Transaction modifier rules describe changes that should be applied -automatically to certain transactions. Currently, this means adding -extra postings (also known as "automated postings"). Transaction -modifiers are enabled by the '--auto' flag. +automatically to certain transactions. They can be enabled by using the +'--auto' flag. Currently, just one kind of change is possible: adding +extra postings. These rule-generated postings are known as "automated +postings" or "auto postings". A transaction modifier rule looks quite like a normal transaction, except the first line is an equals sign followed by a query that matches @@ -1432,8 +1509,8 @@ ACCT [AMT] ... - The posting rules look just like normal postings, except the amount -can be: + These posting rules look like normal postings, except the amount can +be: * a normal amount with a commodity symbol, eg '$2'. This will be used as-is. @@ -1477,11 +1554,28 @@ assets:checking:gifts -$20 assets:checking $20 - Postings added by transaction modifiers participate in transaction -balancing, missing amount inference and balance assertions, like regular -postings. +* Menu: +* Auto postings and transaction balancing / inferred amounts / balance assertions:: +  +File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Transaction modifiers + +1.16.1 Auto postings and transaction balancing / inferred amounts / +------------------------------------------------------------------- + +balance assertions Currently, transaction modifiers are applied / auto +postings are added: + + * after missing amounts are inferred, and transactions are checked + for balancedness, + * but before balance assertions are checked. + + Note this means that journal entries must be balanced both before and +after auto postings are added. This changed in hledger 1.12+; see #893 +for background. + + File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top 2 EDITOR SUPPORT @@ -1539,69 +1633,81 @@ Ref: #virtual-postings15185 Node: Balance Assertions16405 Ref: #balance-assertions16580 -Node: Assertions and ordering17476 -Ref: #assertions-and-ordering17662 -Node: Assertions and included files18362 -Ref: #assertions-and-included-files18603 -Node: Assertions and multiple -f options18936 -Ref: #assertions-and-multiple--f-options19190 -Node: Assertions and commodities19322 -Ref: #assertions-and-commodities19557 -Node: Assertions and subaccounts20745 -Ref: #assertions-and-subaccounts20977 -Node: Assertions and virtual postings21498 -Ref: #assertions-and-virtual-postings21705 -Node: Balance Assignments21847 -Ref: #balance-assignments22028 -Node: Transaction prices23148 -Ref: #transaction-prices23317 -Node: Comments25585 -Ref: #comments25719 -Node: Tags26889 -Ref: #tags27007 -Node: Directives28409 -Ref: #directives28552 -Node: Comment blocks34159 -Ref: #comment-blocks34304 -Node: Including other files34480 -Ref: #including-other-files34660 -Node: Default year35068 -Ref: #default-year35237 -Node: Declaring commodities35660 -Ref: #declaring-commodities35843 -Node: Default commodity37070 -Ref: #default-commodity37246 -Node: Market prices37882 -Ref: #market-prices38047 -Node: Declaring accounts38888 -Ref: #declaring-accounts39064 -Node: Account types40021 -Ref: #account-types40170 -Node: Account comments41244 -Ref: #account-comments41429 -Node: Account display order41750 -Ref: #account-display-order41923 -Node: Rewriting accounts43045 -Ref: #rewriting-accounts43230 -Node: Basic aliases43964 -Ref: #basic-aliases44110 -Node: Regex aliases44814 -Ref: #regex-aliases44985 -Node: Multiple aliases45703 -Ref: #multiple-aliases45878 -Node: end aliases46376 -Ref: #end-aliases46523 -Node: Default parent account46624 -Ref: #default-parent-account46790 -Node: Periodic transactions47674 -Ref: #periodic-transactions47856 -Node: Forecasting with periodic transactions49559 -Ref: #forecasting-with-periodic-transactions49802 -Node: Budgeting with periodic transactions51489 -Ref: #budgeting-with-periodic-transactions51728 -Node: Transaction Modifiers52187 -Ref: #transaction-modifiers52350 -Node: EDITOR SUPPORT54331 -Ref: #editor-support54449 +Node: Assertions and ordering17531 +Ref: #assertions-and-ordering17717 +Node: Assertions and included files18417 +Ref: #assertions-and-included-files18658 +Node: Assertions and multiple -f options18991 +Ref: #assertions-and-multiple--f-options19245 +Node: Assertions and commodities19377 +Ref: #assertions-and-commodities19607 +Node: Assertions and prices20795 +Ref: #assertions-and-prices21007 +Node: Assertions and subaccounts21447 +Ref: #assertions-and-subaccounts21674 +Node: Assertions and virtual postings22195 +Ref: #assertions-and-virtual-postings22435 +Node: Assertions and precision22577 +Ref: #assertions-and-precision22768 +Node: Balance Assignments23035 +Ref: #balance-assignments23216 +Node: Balance assignments and prices24380 +Ref: #balance-assignments-and-prices24552 +Node: Transaction prices24776 +Ref: #transaction-prices24945 +Node: Comments27213 +Ref: #comments27347 +Node: Tags28517 +Ref: #tags28635 +Node: Directives30037 +Ref: #directives30180 +Node: Comment blocks35787 +Ref: #comment-blocks35932 +Node: Including other files36108 +Ref: #including-other-files36288 +Node: Default year36696 +Ref: #default-year36865 +Node: Declaring commodities37288 +Ref: #declaring-commodities37471 +Node: Default commodity38698 +Ref: #default-commodity38874 +Node: Market prices39510 +Ref: #market-prices39675 +Node: Declaring accounts40516 +Ref: #declaring-accounts40692 +Node: Account comments41617 +Ref: #account-comments41780 +Node: Account subdirectives42175 +Ref: #account-subdirectives42370 +Node: Account types42683 +Ref: #account-types42867 +Node: Account display order44511 +Ref: #account-display-order44681 +Node: Rewriting accounts45810 +Ref: #rewriting-accounts45995 +Node: Basic aliases46729 +Ref: #basic-aliases46875 +Node: Regex aliases47579 +Ref: #regex-aliases47750 +Node: Multiple aliases48468 +Ref: #multiple-aliases48643 +Node: end aliases49141 +Ref: #end-aliases49288 +Node: Default parent account49389 +Ref: #default-parent-account49555 +Node: Periodic transactions50439 +Ref: #periodic-transactions50621 +Node: Two spaces after the period expression51746 +Ref: #two-spaces-after-the-period-expression51991 +Node: Forecasting with periodic transactions52476 +Ref: #forecasting-with-periodic-transactions52766 +Node: Budgeting with periodic transactions54453 +Ref: #budgeting-with-periodic-transactions54692 +Node: Transaction modifiers55151 +Ref: #transaction-modifiers55314 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions57298 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57599 +Node: EDITOR SUPPORT57977 +Ref: #editor-support58095  End Tag Table diff --git a/embeddedfiles/hledger_journal.txt b/embeddedfiles/hledger_journal.txt --- a/embeddedfiles/hledger_journal.txt +++ b/embeddedfiles/hledger_journal.txt @@ -446,8 +446,21 @@ a:usd 0 == $1 a:euro 0 == 1 + Assertions and prices + Balance assertions ignore transaction prices, and should normally be + written without one: + + 2019/1/1 + (a) $1 @ 1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- + ments do use them (see below). + Assertions and subaccounts - Balance assertions do not count the balance from subaccounts; they + Balance assertions do not count the balance from subaccounts; they check the posted account's exclusive balance. For example: 1/1 @@ -455,7 +468,7 @@ 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 + The balance report's flat mode shows these exclusive balances more clearly: $ hledger bal checking --flat @@ -468,6 +481,12 @@ Balance assertions are checked against all postings, both real and vir- tual. They are not affected by the --real/-R flag or real: query. + Assertions and precision + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- + tions. Balance assertion failure messages show exact amounts. + 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 @@ -496,11 +515,22 @@ less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. + Balance assignments and prices + A transaction price in a balance assignment will cause the calculated + amount to have that price attached: + + 2019/1/1 + (a) = $1 @ 2 + + $ hledger print --explicit + 2019/01/01 + (a) $1 @ 2 = $1 @ 2 + 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. Note transaction prices are + 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. Note transaction prices are fixed at the time of the transaction, and do not change over time. See also market prices, which represent prevailing exchange rates on a cer- tain date. @@ -529,7 +559,7 @@ (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- PRICE}, which hledger currently ignores). - Use the -B/--cost flag to convert amounts to their transaction price's + Use the -B/--cost flag to convert amounts to their transaction price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). Eg here is how -B affects the balance report for the example above: @@ -540,8 +570,8 @@ $-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 + 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: @@ -555,14 +585,14 @@ 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 + (*) 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.) - 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. + 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: @@ -586,24 +616,24 @@ ; another comment line for posting 2 ; a file comment (because not indented) - You can also comment larger regions of a file using comment and + You can also comment larger regions of a file using comment and end comment directives. Tags - Tags are a way to add extra labels or labelled data to postings and + 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 + 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 + 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- + 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: @@ -617,78 +647,69 @@ 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, + 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 + Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. Directives - A directive is a line in the journal beginning with a special keyword, + A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). Directives' behaviour and interactions can get a little bit complex, so - here is a table summarising the directives and their effects, with + here is a table summarising the directives and their effects, with links to more detailed docs. - direc- end subdi- purpose can affect (as of + + + + direc- end subdi- purpose can affect (as of tive directive rec- 2018/06) tives ------------------------------------------------------------------------------------------------- - account any document account names, all entries in all - text declare account types & dis- files, before or + account any document account names, all entries in all + text declare account types & dis- files, before or play order after alias end aliases rewrite account names following inline/included entries until end - of current file or + of current file or end directive - apply account end apply account prepend a common parent to following + apply account end apply account prepend a common parent to following account names inline/included entries until end - of current file or + of current file or end directive comment end comment ignore part of journal following inline/included entries until end - of current file or + of current file or end directive - commodity format declare a commodity and its number notation: + commodity format declare a commodity and its number notation: number notation & display following entries style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - - - - - - - - - - - - - D declare a commodity, number commodity: all com- + D declare a commodity, number commodity: all com- notation & display style for modityless entries - commodityless amounts in all files; num- - ber notation: fol- + commodityless amounts in all files; num- + ber notation: fol- lowing commodity- - less entries and + less entries and entries in that - commodity in all + commodity in all files; display style: amounts of that commodity in @@ -699,7 +720,7 @@ commodity commodity in reports, when -V is used - Y declare a year for yearless following + Y declare a year for yearless following dates inline/included entries until end of current file @@ -709,9 +730,9 @@ subdirec- optional indented directive line immediately following a par- tive ent directive - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same + number how to interpret numbers when parsing journal entries (the + notation identity of the decimal separator character). (Currently + each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) @@ -719,37 +740,37 @@ scope are affected by a directive As you can see, directives vary in which journal entries and files they - affect, and whether they are focussed on input (parsing) or output + affect, and whether they are focussed on input (parsing) or output (reports). Some directives have multiple effects. - If you have a journal made up of multiple files, or pass multiple -f - options on the command line, note that directives which affect input - typically last only until the end of their defining file. This pro- + If you have a journal made up of multiple files, or pass multiple -f + options on the command line, note that directives which affect input + typically last only until the end of their defining file. This pro- vides more simplicity and predictability, eg reports are not changed by - writing file options in a different order. It can be surprising at + writing file options in a different order. It can be surprising at times though. Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional 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. The include file path may contain common glob patterns (e.g. + If the path does not begin with a slash, it is relative to the current + file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. 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. + 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 @@ -769,8 +790,8 @@ assets Declaring commodities - The commodity directive declares commodities which may be used in the - journal (though currently we do not enforce this). It may be written + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -780,8 +801,8 @@ ; 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 + 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 @@ -793,19 +814,19 @@ commodity INR format INR 9,99,99,999.00 - Commodity directives have a second purpose: they define the standard + Commodity directives have a second purpose: they define the standard display format for amounts in the commodity. Normally the display for- - mat is inferred from journal entries, but this can be unpredictable; - declaring it with a commodity directive overrides this and removes - ambiguity. Towards this end, amounts in commodity directives must - always be written with a decimal point (a period or comma, followed by + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Default commodity - The D directive sets a default commodity (and display format), to be + 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 + 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 @@ -820,9 +841,9 @@ a decimal point. Market prices - The P directive declares a market price, which is an exchange rate + The P directive declares a market price, which is an exchange rate between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -833,97 +854,117 @@ o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price 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 - The -V/--value flag can be used to convert reported amounts to another + The -V/--value flag can be used to convert reported amounts to another commodity using these prices. Declaring accounts - account directives can be used to pre-declare some or all accounts. - Though not required, they can provide several benefits: + account directives can be used to pre-declare accounts. Though not + required, they can provide several benefits: o They can document your intended chart of accounts, providing a refer- ence. - o They can store extra information about accounts (account numbers, + o They can store extra information about accounts (account numbers, notes, etc.) - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and incomestatement. - o They control account display order in reports, allowing non-alpha- + o They control account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They help with account name completion in the add command, + o They help with account name completion in the add command, hledger-iadd, hledger-web, ledger-mode etc. - Here is the full syntax: + The simplest form is just the word account followed by a hledger-style + account name, eg: - account ACCTNAME [ACCTTYPE] - [COMMENTS] + account assets:bank:checking - The simplest form just declares a hledger-style account name, eg: + Account comments + Comments, beginning with a semicolon, optionally including tags, can be + written after the account name, and/or on following lines. Eg: + account assets:bank:checking ; a comment + ; another comment + ; acctno:12345, a tag + + Tip: comments on the same line require hledger 1.12+. If you need your + journal to be compatible with older hledger versions, write comments on + the next line instead. + + Account subdirectives + We also allow (and ignore) Ledger-style indented subdirectives, just + for compatibility.: + account assets:bank:checking + format blah blah ; <- subdirective, ignored + Here is the full syntax of account directives: + + account ACCTNAME [ACCTTYPE] [;COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] + Account types - hledger recognises five types of account: asset, liability, equity, - revenue, expense. This is useful for certain accounting-aware reports, - in particular balancesheet, incomestatement and cashflow. + hledger recognises five types (or classes) of account: Asset, Liabil- + ity, Equity, Revenue, Expense. This is used by a few accounting-aware + reports such as balancesheet, incomestatement and cashflow. + Auto-detected account types If you name your top-level accounts with some variation of assets, lia- bilities/debts, equity, revenues/income, or expenses, their types are detected automatically. - More generally, you can declare an account's type by adding one of the - letters ALERX to its account directive, separated from the account name - by two or more spaces. Eg: + Account types declared with tags + More generally, you can declare an account's type with an account + directive, by writing a type: tag in a comment, followed by one of the + words Asset, Liability, Equity, Revenue, Expense, or one of the letters + ALERX (case insensitive): + account assets ; type:Asset + account liabilities ; type:Liability + account equity ; type:Equity + account revenues ; type:Revenue + account expenses ; type:Expenses + + Account types declared with account type codes + Or, you can write one of those letters separated from the account name + by two or more spaces, but this should probably be considered depre- + cated as of hledger 1.13: + account assets A account liabilities L account equity E account revenues R account expenses X - Note: if you ever override the types of those auto-detected english - account names mentioned above, you might need to help the reports a - bit: + Overriding auto-detected types + If you ever override the types of those auto-detected english account + names mentioned above, you might need to help the reports a bit. Eg: - ; make "liabilities" not have the liability type, who knows why - account liabilities E + ; make "liabilities" not have the liability type - who knows why + account liabilities ; type:E - ; better ensure some other account has the liability type, + ; we need to ensure some other account has the liability type, ; otherwise balancesheet would still show "liabilities" under Liabilities - account - L - - ) - - Account comments - An account directive can also have indented comments on following - lines, eg: - - account assets:bank:checking - ; acctno:12345 - ; a comment - - We also allow (and ignore) Ledger-style subdirectives, with no leading - semicolon, for compatibility. - - Tags in account comments, like acctno above, currently have no effect. + account - ; type:L Account display order - Account directives also set the order in which accounts are displayed - in reports, the hledger-ui accounts screen, the hledger-web sidebar, - etc. Normally accounts are listed in alphabetical order, but if you - have eg these account directives in the journal: + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web + sidebar. By default accounts are listed in alphabetical order. But if + you have these account directives in the journal: account assets account liabilities @@ -931,8 +972,8 @@ account revenues account expenses - you'll see those accounts listed in declaration order, not alphabeti- - cally: + you'll see those accounts displayed in declaration order, not alphabet- + ically: $ hledger accounts -1 assets @@ -943,16 +984,16 @@ Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - you - will sometimes declare parent accounts (eg account other above) that - you don't intend to post to, just to customize their display order - + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: - you + will sometimes declare parent accounts (eg account other above) that + you don't intend to post to, just to customize their display order - sibling accounts stay together (you couldn't display x:y in between a:b and a:c). @@ -971,14 +1012,14 @@ o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or + do not affect account names being entered via hledger add or hledger-web. 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 + 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 @@ -986,54 +1027,54 @@ 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 case sensitive full account names. hledger will - replace any occurrence of the old account name with the new one. Sub- + OLD and NEW are case sensitive full account names. hledger will + replace any occurrence of the old account name with the new one. Sub- accounts 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, + 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- + 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- + 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 + 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 + 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 + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and + 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 @@ -1050,7 +1091,7 @@ home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -1059,18 +1100,18 @@ apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent account. Periodic transactions - Periodic transaction rules describe transactions that recur. They + Periodic transaction rules describe transactions that recur. They allow you to generate future transactions for forecasting, without hav- - ing to write them out explicitly in the journal (with --forecast). + ing to write them out explicitly in the journal (with --forecast). Secondly, they also can be used to define budget goals (with --budget). A periodic transaction rule looks like a normal journal entry, with the @@ -1081,85 +1122,85 @@ expenses:rent $2000 assets:bank:checking - There is an additional constraint on the period expression: the start - date must fall on a natural boundary of the interval. Eg + There is an additional constraint on the period expression: the start + date must fall on a natural boundary of the interval. Eg monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not. - Partial or relative dates (M/D, D, tomorrow, last week) in the period - expression can work (useful or not). They will be relative to today's - date, unless a Y default year directive is in effect, in which case + Partial or relative dates (M/D, D, tomorrow, last week) in the period + expression can work (useful or not). They will be relative to today's + date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. - Period expressions must be terminated by two or more spaces if followed - by additional fields. For example, the periodic transaction given - below includes a transaction description "paycheck", which is separated - from the period expression by a double space. If not for the second - space, hledger would attempt (and fail) to parse "paycheck" as a part - of the period expression. + Two spaces after the period expression + If the period expression is followed by a transaction description, + these must be separated by two or more spaces. This helps hledger know + where the period expression ends, so that descriptions can not acciden- + tally alter their meaning, as in this example: - ; 2 or more spaces - ; || - ; vv - ~ every 2 weeks from 2018/6/4 to 2018/9 paycheck + ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020" + ; || + ; vv + ~ every 2 months in 2020, we will review assets:bank:checking $1500 income:acme inc Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates + With the --forecast flag, each periodic transaction rule generates future transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like - normal transactions, but with an extra tag named recur, whose value is + saved in the journal, but appear in all reports. They will look like + normal transactions, but with an extra tag named recur, whose value is the generating period expression. - Forecast transactions start on the first occurrence, and end on the - last occurrence, of their interval within the forecast period. The + Forecast transactions start on the first occurrence, and end on the + last occurrence, of their interval within the forecast period. The forecast period: o begins on the later of o the report start date if specified with -b/-p/date: - o the day after the latest normal (non-periodic) transaction in the + o the day after the latest normal (non-periodic) transaction in the journal, or today if there are no normal transactions. - o ends on the report end date if specified with -e/-p/date:, or 180 + o ends on the report end date if specified with -e/-p/date:, or 180 days from today. - where "today" means the current date at report time. The "later of" - rule ensures that forecast transactions do not overlap normal transac- + where "today" means the current date at report time. The "later of" + rule ensures that forecast transactions do not overlap normal transac- tions in time; they will begin only after normal transactions end. - Forecasting can be useful for estimating balances into the future, and - experimenting with different scenarios. Note the start date logic + Forecasting can be useful for estimating balances into the future, and + experimenting with different scenarios. Note the start date logic means that forecasted transactions are automatically replaced by normal transactions as you add those. Forecasting can also help with data entry: describe most of your trans- - actions with periodic rules, and every so often copy the output of + actions with periodic rules, and every so often copy the output of print --forecast to the journal. You can generate one-time transactions too: just write a period expres- - sion specifying a date with no report interval. (You could also write - a normal transaction with a future date, but remember this disables + sion specifying a date with no report interval. (You could also write + a normal transaction with a future date, but remember this disables forecast transactions on previous dates.) Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- pared in budget reports. - For more details, see: balance: Budget report and Cookbook: Budgeting + For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - Transaction Modifiers - Transaction modifier rules describe changes that should be applied - automatically to certain transactions. Currently, this means adding - extra postings (also known as "automated postings"). Transaction modi- - fiers are enabled by the --auto flag. + Transaction modifiers + Transaction modifier rules describe changes that should be applied + automatically to certain transactions. They can be enabled by using + the --auto flag. Currently, just one kind of change is possible: + adding extra postings. These rule-generated postings are known as + "automated postings" or "auto postings". A transaction modifier rule looks quite like a normal transaction, except the first line is an equals sign followed by a query that @@ -1171,7 +1212,7 @@ ACCT [AMT] ... - The posting rules look just like normal postings, except the amount can + These posting rules look like normal postings, except the amount can be: o a normal amount with a commodity symbol, eg $2. This will be used @@ -1219,10 +1260,20 @@ assets:checking:gifts -$20 assets:checking $20 - Postings added by transaction modifiers participate in transaction bal- - ancing, missing amount inference and balance assertions, like regular - postings. + Auto postings and transaction balancing / inferred amounts / balance + assertions + Currently, transaction modifiers are applied / auto postings are added: + + o after missing amounts are inferred, and transactions are checked for + balancedness, + + o but before balance assertions are checked. + + Note this means that journal entries must be balanced both before and + after auto postings are added. This changed in hledger 1.12+; see #893 + for background. + 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- @@ -1240,6 +1291,7 @@ Sublime Text https://github.com/ledger/ledger/wiki/Edit- ing-Ledger-files-with-Sublime-Text-or-RubyMine Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 + Text Wran- https://github.com/ledger/ledger/wiki/Edit- gler ing-Ledger-files-with-TextWrangler Visual Stu- https://marketplace.visualstudio.com/items?item- @@ -1270,4 +1322,4 @@ -hledger 1.12 December 2018 hledger_journal(5) +hledger 1.13 February 2019 hledger_journal(5) diff --git a/embeddedfiles/hledger_timeclock.5 b/embeddedfiles/hledger_timeclock.5 --- a/embeddedfiles/hledger_timeclock.5 +++ b/embeddedfiles/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "December 2018" "hledger 1.12" "hledger User Manuals" +.TH "hledger_timeclock" "5" "February 2019" "hledger 1.13" "hledger User Manuals" @@ -9,7 +9,7 @@ .SH DESCRIPTION .PP hledger can read timeclock files. -As with Ledger, these are (a subset of) timeclock.el's format, +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]. @@ -67,8 +67,8 @@ .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. +These rely on a "timeclock" executable which I think is just the ledger +2 executable renamed. .SH "REPORTING BUGS" diff --git a/embeddedfiles/hledger_timeclock.info b/embeddedfiles/hledger_timeclock.info --- a/embeddedfiles/hledger_timeclock.info +++ b/embeddedfiles/hledger_timeclock.info @@ -4,7 +4,7 @@  File: hledger_timeclock.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.12 +hledger_timeclock(5) hledger 1.13 ********************************* hledger can read timeclock files. As with Ledger, these are (a subset diff --git a/embeddedfiles/hledger_timeclock.txt b/embeddedfiles/hledger_timeclock.txt --- a/embeddedfiles/hledger_timeclock.txt +++ b/embeddedfiles/hledger_timeclock.txt @@ -77,4 +77,4 @@ -hledger 1.12 December 2018 hledger_timeclock(5) +hledger 1.13 February 2019 hledger_timeclock(5) diff --git a/embeddedfiles/hledger_timedot.5 b/embeddedfiles/hledger_timedot.5 --- a/embeddedfiles/hledger_timedot.5 +++ b/embeddedfiles/hledger_timedot.5 @@ -1,11 +1,11 @@ -.TH "hledger_timedot" "5" "December 2018" "hledger 1.12" "hledger User Manuals" +.TH "hledger_timedot" "5" "February 2019" "hledger 1.13" "hledger User Manuals" .SH NAME .PP -Timedot \- hledger's human\-friendly time logging format +Timedot \- hledger\[aq]s human\-friendly time logging format .SH DESCRIPTION .PP Timedot is a plain text format for logging dated, categorised quantities @@ -16,10 +16,10 @@ 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. +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. @@ -34,7 +34,7 @@ .IP \[bu] 2 a sequence of dots (.) representing quarter hours. Spaces may optionally be used for grouping and readability. -Eg: \&.... +Eg: .... \&.. .IP \[bu] 2 an integral or decimal number, representing hours. diff --git a/embeddedfiles/hledger_timedot.info b/embeddedfiles/hledger_timedot.info --- a/embeddedfiles/hledger_timedot.info +++ b/embeddedfiles/hledger_timedot.info @@ -4,7 +4,7 @@  File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_timedot(5) hledger 1.12 +hledger_timedot(5) hledger 1.13 ******************************* Timedot is a plain text format for logging dated, categorised quantities diff --git a/embeddedfiles/hledger_timedot.txt b/embeddedfiles/hledger_timedot.txt --- a/embeddedfiles/hledger_timedot.txt +++ b/embeddedfiles/hledger_timedot.txt @@ -124,4 +124,4 @@ -hledger 1.12 December 2018 hledger_timedot(5) +hledger 1.13 February 2019 hledger_timedot(5) diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1,3093 +1,3203 @@ .\"t -.TH "hledger" "1" "December 2018" "hledger 1.12" "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]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') -.RS -.RE -.TP -.B \f[C]\-\-alias=OLD=NEW\f[] -rename accounts named OLD to NEW -.RS -.RE -.TP -.B \f[C]\-\-anon\f[] -anonymize accounts and payees -.RS -.RE -.TP -.B \f[C]\-\-pivot\ FIELDNAME\f[] -use some other field or tag for the account name -.RS -.RE -.TP -.B \f[C]\-I\ \-\-ignore\-assertions\f[] -ignore any failing balance assertions -.RS -.RE -.PP -General reporting options: -.TP -.B \f[C]\-b\ \-\-begin=DATE\f[] -include postings/txns on or after this date -.RS -.RE -.TP -.B \f[C]\-e\ \-\-end=DATE\f[] -include postings/txns before this date -.RS -.RE -.TP -.B \f[C]\-D\ \-\-daily\f[] -multiperiod/multicolumn report by day -.RS -.RE -.TP -.B \f[C]\-W\ \-\-weekly\f[] -multiperiod/multicolumn report by week -.RS -.RE -.TP -.B \f[C]\-M\ \-\-monthly\f[] -multiperiod/multicolumn report by month -.RS -.RE -.TP -.B \f[C]\-Q\ \-\-quarterly\f[] -multiperiod/multicolumn report by quarter -.RS -.RE -.TP -.B \f[C]\-Y\ \-\-yearly\f[] -multiperiod/multicolumn report by year -.RS -.RE -.TP -.B \f[C]\-p\ \-\-period=PERIODEXP\f[] -set start date, end date, and/or reporting interval all at once using -period expressions syntax (overrides the flags above) -.RS -.RE -.TP -.B \f[C]\-\-date2\f[] -match the secondary date instead (see command help for other effects) -.RS -.RE -.TP -.B \f[C]\-U\ \-\-unmarked\f[] -include only unmarked postings/txns (can combine with \-P or \-C) -.RS -.RE -.TP -.B \f[C]\-P\ \-\-pending\f[] -include only pending postings/txns -.RS -.RE -.TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns -.RS -.RE -.TP -.B \f[C]\-R\ \-\-real\f[] -include only non\-virtual postings -.RS -.RE -.TP -.B \f[C]\-NUM\ \-\-depth=NUM\f[] -hide/aggregate accounts or postings more than NUM levels deep -.RS -.RE -.TP -.B \f[C]\-E\ \-\-empty\f[] -show items with zero amount, normally hidden (and vice\-versa in -hledger\-ui/hledger\-web) -.RS -.RE -.TP -.B \f[C]\-B\ \-\-cost\f[] -convert amounts to their cost at transaction time (using the transaction -price, if any) -.RS -.RE -.TP -.B \f[C]\-V\ \-\-value\f[] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) -.RS -.RE -.TP -.B \f[C]\-\-auto\f[] -apply automated posting rules to modify transactions. -.RS -.RE -.TP -.B \f[C]\-\-forecast\f[] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. -.RS -.RE -.PP -When a reporting option appears more than once in the command line, the -last one takes precedence. -.PP -Some reporting options can also be written as query arguments. -.SS Command options -.PP -To see options for a particular command, including command\-specific -options, run: \f[C]hledger\ COMMAND\ \-h\f[]. -.PP -Command\-specific options must be written after the command name, eg: -\f[C]hledger\ print\ \-x\f[]. -.PP -Additionally, if the command is an addon, you may need to put its -options after a double\-hyphen, eg: -\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. -Or, you can run the addon executable directly: -\f[C]hledger\-ui\ \-\-watch\f[]. -.SS Command arguments -.PP -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. -.SS Argument files -.PP -You can save a set of command line options/arguments in a file, one per -line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command -line. -To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a -\f[C]\-\-\f[] argument. -For more, see Save frequently used options. -.SS Special characters in arguments and queries -.PP -In shell command lines, option and argument values which contain -\[lq]problematic\[rq] characters, ie spaces, and also characters -significant to your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], -\f[C])\f[], \f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing -them in quotes or by writing backslashes before the characters. -Eg: -.PP -\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. -.SS More escaping -.PP -Characters significant both to the shell and in regular expressions may -need one extra level of escaping. -These include parentheses, the pipe symbol and the dollar sign. -Eg, to match the dollar symbol, bash users should do: -.PP -\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] -.PP -or: -.PP -\f[C]hledger\ balance\ cur:\\\\$\f[] -.SS Even more escaping -.PP -When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[], -hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options -and arguments once, so you might need to \f[I]triple\f[]\-escape. -Eg in bash, running the ui command and matching the dollar sign, it's: -.PP -\f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] -.PP -or: -.PP -\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] -.PP -If you asked why \f[I]four\f[] slashes above, this may help: -.PP -.TS -tab(@); -l l. -T{ -unescaped: -T}@T{ -\f[C]$\f[] -T} -T{ -escaped: -T}@T{ -\f[C]\\$\f[] -T} -T{ -double\-escaped: -T}@T{ -\f[C]\\\\$\f[] -T} -T{ -triple\-escaped: -T}@T{ -\f[C]\\\\\\\\$\f[] -T} -.TE -.PP -(The number of backslashes in fish shell is left as an exercise for the -reader.) -.PP -You can always avoid the extra escaping for addons by running the addon -directly: -.PP -\f[C]hledger\-ui\ cur:\\\\$\f[] -.SS Less escaping -.PP -Inside an argument file, or in the search field of hledger\-ui or -hledger\-web, or at a GHCI prompt, you need one less level of escaping -than at the command line. -And backslashes may work better than quotes. -Eg: -.PP -\f[C]ghci>\ :main\ balance\ cur:\\$\f[] -.SS Command line tips -.PP -If in doubt, keep things simple: -.IP \[bu] 2 -write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[]) -.IP \[bu] 2 -run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[]) -.IP \[bu] 2 -enclose problematic args in single quotes -.IP \[bu] 2 -if needed, also add a backslash to escape regexp metacharacters -.PP -To find out exactly how a command line is being parsed, add -\f[C]\-\-debug=2\f[] to troubleshoot. -.SS Unicode characters -.PP -hledger is expected to handle unicode (non\-ascii) characters, but this -requires a well\-configured environment. -.PP -To handle unicode characters in the command line or input data, a system -locale that can decode them must be configured (POSIX's default -\f[C]C\f[] locale will not work). -Eg in bash, you could do: -.IP -.nf -\f[C] -export\ LANG=en_US.UTF\-8 -\f[] -.fi -.PP -See Troubleshooting for more about this. -.PP -Unicode characters should appear correctly in hledger's output. -For the hledger and hledger\-ui tools, this requires that -.IP \[bu] 2 -your terminal supports unicode -.IP \[bu] 2 -the terminal's font includes the required unicode glyphs -.IP \[bu] 2 -the terminal is configured to display \[lq]wide\[rq] characters as -double width (otherwise report alignment will be off) -.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]2004/10/1\f[], \f[C]2004\-01\-01\f[], \f[C]2004.9.1\f[] -T}@T{ -exact date, several separators allowed. -Year is 4+ digits, month is 1\-12, day is 1\-31 -T} -T{ -\f[C]2004\f[] -T}@T{ -start of year -T} -T{ -\f[C]2004/10\f[] -T}@T{ -start of month -T} -T{ -\f[C]10/1\f[] -T}@T{ -month and day in current year -T} -T{ -\f[C]21\f[] -T}@T{ -day in current month -T} -T{ -\f[C]october,\ oct\f[] -T}@T{ -start of month in current year -T} -T{ -\f[C]yesterday,\ today,\ tomorrow\f[] -T}@T{ -\-1, 0, 1 days from today -T} -T{ -\f[C]last/this/next\ day/week/month/quarter/year\f[] -T}@T{ -\-1, 0, 1 periods from the current period -T} -T{ -\f[C]20181201\f[] -T}@T{ -8 digit YYYYMMDD with valid year month and day -T} -T{ -\f[C]201812\f[] -T}@T{ -6 digit YYYYMM with valid year and month -T} -.TE -.PP -Counterexamples \- malformed digit sequences might give surprising -results: -.PP -.TS -tab(@); -l l. -T{ -\f[C]201813\f[] -T}@T{ -6 digits with an invalid month is parsed as start of 6\-digit year -T} -T{ -\f[C]20181301\f[] -T}@T{ -8 digits with an invalid month is parsed as start of 8\-digit year -T} -T{ -\f[C]20181232\f[] -T}@T{ -8 digits with an invalid day gives an error -T} -T{ -\f[C]201801012\f[] -T}@T{ -9+ digits beginning with a valid YYYYMMDD gives an error -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. -.PD 0 -.P -.PD -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\ \-N\ euros -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros -\f[] -.fi -.PP -What are they worth at end of nov 3 ? -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V\ \-e\ 2016/11/4 -\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros -\f[] -.fi -.PP -What are they worth after 2016/12/21 ? -(no report end date specified, defaults to today) -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V -\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros -\f[] -.fi -.PP -Currently, hledger's \-V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). -.PP -Currently, \-V has a limitation in multicolumn balance reports: it uses -the market prices on the report end date for all columns. -(Instead of the prices on each column's end date.) -.SS Combining \-B and \-V -.PP -Using \-B/\[en]cost and \-V/\[en]value together is currently allowed, -but the results are probably not meaningful. -Let us know if you find a use for this. -.SS Output destination -.PP -Some commands (print, register, stats, the balance commands) can write -their output to a destination other than the console. -This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) -$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE -\f[] -.fi -.SS Output format -.PP -Some commands can write their output in other formats. -Eg print and register can output CSV, and the balance commands can -output CSV or HTML. -This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by -specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with -\f[C]\-o/\-\-output\-file\f[]. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout -$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv -\f[] -.fi -.SS Regular expressions -.PP -hledger uses regular expressions in a number of places: -.IP \[bu] 2 -query terms, on the command line and in the hledger\-web search form: -\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[], -\f[C]tag:...=REGEX\f[] -.IP \[bu] 2 -CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[] -.IP \[bu] 2 -account alias directives and options: -\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[], -\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[] -.PP -hledger's regular expressions come from the regex\-tdfa library. -In general they: -.IP \[bu] 2 -are case insensitive -.IP \[bu] 2 -are infix matching (do not need to match the entire thing being matched) -.IP \[bu] 2 -are POSIX extended regular expressions -.IP \[bu] 2 -also support GNU word boundaries (\\<, \\>, \\b, \\B) -.IP \[bu] 2 -and parenthesised capturing groups and numeric backreferences in -replacement strings -.IP \[bu] 2 -do not support mode modifiers like (?s) -.PP -Some things to note: -.IP \[bu] 2 -In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular -expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]). -Elsewhere in hledger, these are not required. -.IP \[bu] 2 -In queries, to match a regular expression metacharacter like \f[C]$\f[] -as a literal character, prepend a backslash. -Eg to search for amounts with the dollar sign in hledger\-web, write -\f[C]cur:\\$\f[]. -.IP \[bu] 2 -On the command line, some metacharacters like \f[C]$\f[] have a special -meaning to the shell and so must be escaped at least once more. -See Special characters. -.SH QUERIES -.PP -One of hledger's strengths is being able to quickly report on precise -subsets of your data. -Most commands accept an optional query expression, written as arguments -after the command name, to filter the data by date, account name or -other criteria. -The syntax is similar to a web search: one or more space\-separated -search terms, quotes to enclose whitespace, prefixes to match specific -fields, a not: prefix to negate the match. -.PP -We do not yet support arbitrary boolean combinations of search terms; -instead most commands show transactions/postings/accounts which match -(or negatively match): -.IP \[bu] 2 -any of the description terms AND -.IP \[bu] 2 -any of the account terms AND -.IP \[bu] 2 -any of the status terms AND -.IP \[bu] 2 -all the other terms. -.PP -The print command instead shows transactions which: -.IP \[bu] 2 -match any of the description terms AND -.IP \[bu] 2 -have any postings matching any of the positive account terms AND -.IP \[bu] 2 -have no postings matching any of the negative account terms AND -.IP \[bu] 2 -match all the other terms. -.PP -The following kinds of search terms can be used. -Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to -exclude a particular subaccount. -.TP -.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[] -match account names by this regular expression. -(With no prefix, \f[C]acct:\f[] is assumed.) -.RS -.RE -same as above -.RS -.RE -.TP -.B \f[B]\f[BC]amt:N,\ amt:N,\ amt:>=N\f[B]\f[] -match postings with a single\-commodity amount that is equal to, less -than, or greater than N. -(Multi\-commodity amounts are not tested, and will always match.) The -comparison has two modes: if N is preceded by a + or \- sign (or is 0), -the two signed numbers are compared. -Otherwise, the absolute magnitudes are compared, ignoring sign. -.RS -.RE -.TP -.B \f[B]\f[BC]code:REGEX\f[B]\f[] -match by transaction code (eg check number) -.RS -.RE -.TP -.B \f[B]\f[BC]cur:REGEX\f[B]\f[] -match postings or transactions including any amounts whose -currency/commodity symbol is fully matched by REGEX. -(For a partial match, use \f[C]\&.*REGEX.*\f[]). -Note, to match characters which are regex\-significant, like the dollar -sign (\f[C]$\f[]), you need to prepend \f[C]\\\f[]. -And when using the command line you need to add one more level of -quoting to hide it from the shell, so eg do: -\f[C]hledger\ print\ cur:\[aq]\\$\[aq]\f[] or -\f[C]hledger\ print\ cur:\\\\$\f[]. -.RS -.RE -.TP -.B \f[B]\f[BC]desc:REGEX\f[B]\f[] -match transaction descriptions. -.RS -.RE -.TP -.B \f[B]\f[BC]date:PERIODEXPR\f[B]\f[] -match dates within the specified period. -PERIODEXPR is a period expression (with no report interval). -Examples: \f[C]date:2016\f[], \f[C]date:thismonth\f[], -\f[C]date:2000/2/1\-2/15\f[], \f[C]date:lastweek\-\f[]. -If the \f[C]\-\-date2\f[] command line flag is present, this matches -secondary dates instead. -.RS -.RE -.TP -.B \f[B]\f[BC]date2:PERIODEXPR\f[B]\f[] -match secondary dates within the specified period. -.RS -.RE -.TP -.B \f[B]\f[BC]depth:N\f[B]\f[] -match (or display, depending on command) accounts at or above this depth -.RS -.RE -.TP -.B \f[B]\f[BC]note:REGEX\f[B]\f[] -match transaction notes (part of description right of \f[C]|\f[], or -whole description when there's no \f[C]|\f[]) -.RS -.RE -.TP -.B \f[B]\f[BC]payee:REGEX\f[B]\f[] -match transaction payee/payer names (part of description left of -\f[C]|\f[], or whole description when there's no \f[C]|\f[]) -.RS -.RE -.TP -.B \f[B]\f[BC]real:,\ real:0\f[B]\f[] -match real or virtual postings respectively -.RS -.RE -.TP -.B \f[B]\f[BC]status:,\ status:!,\ status:*\f[B]\f[] -match unmarked, pending, or cleared transactions respectively -.RS -.RE -.TP -.B \f[B]\f[BC]tag:REGEX[=REGEX]\f[B]\f[] -match by tag name, and optionally also by tag value. -Note a tag: query is considered to match a transaction if it matches any -of the postings. -Also remember that postings inherit the tags of their parent -transaction. -.RS -.RE -.PP -The following special search term is used automatically in hledger\-web, -only: -.TP -.B \f[B]\f[BC]inacct:ACCTNAME\f[B]\f[] -tells hledger\-web to show the transaction register for this account. -Can be filtered further with \f[C]acct\f[] etc. -.RS -.RE -.PP -Some of these can also be expressed as command\-line options (eg -\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]). -Generally you can mix options and query arguments, and the resulting -query will be their intersection (perhaps excluding the -\f[C]\-p/\-\-period\f[] option). -.SH COMMANDS -.PP -hledger provides a number of subcommands; \f[C]hledger\f[] with no -arguments shows a list. -.PP -If you install additional \f[C]hledger\-*\f[] packages, or if you put -programs or scripts named \f[C]hledger\-NAME\f[] in your PATH, these -will also be listed as subcommands. -.PP -Run a subcommand by writing its name as first argument (eg -\f[C]hledger\ incomestatement\f[]). -You can also write one of the standard short aliases displayed in -parentheses in the command list (\f[C]hledger\ b\f[]), or any any -unambiguous prefix of a command name (\f[C]hledger\ inc\f[]). -.PP -Here are all the builtin commands in alphabetical order. -See also \f[C]hledger\f[] for a more organised command list, and -\f[C]hledger\ CMD\ \-h\f[] for detailed command help. -.SS accounts -.PP -Show account names. -Alias: a. -.TP -.B \f[C]\-\-declared\f[] -show account names declared with account directives -.RS -.RE -.TP -.B \f[C]\-\-used\f[] -show account names posted to by transactions -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show short account names and their parents, as a tree -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show full account names, as a list (default) -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -in flat mode: omit N leading account name parts -.RS -.RE -.PP -This command lists account names, either declared with account -directives (\[en]declared), posted to (\[en]used), or both (default). -With query arguments, only matched account names and account names -referenced by matched postings are shown. -It shows a flat list by default. -With \f[C]\-\-tree\f[], it uses indentation to show the account -hierarchy. -In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few -account name components. -Account names can be depth\-clipped with \f[C]\-\-depth\ N\f[] or -depth:N. -.PP -Examples: -.IP -.nf -\f[C] -$\ hledger\ accounts\ \-\-tree -assets -\ \ bank -\ \ \ \ checking -\ \ \ \ saving -\ \ cash -expenses -\ \ food -\ \ supplies -income -\ \ gifts -\ \ salary -liabilities -\ \ debts -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ accounts\ \-\-drop\ 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts -\f[] -.fi -.SS activity -.PP -Show an ascii barchart of posting counts per interval. -.PP -The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). -With query arguments, it counts only matched transactions. -.IP -.nf -\f[C] -$\ hledger\ activity\ \-\-quarterly -2008\-01\-01\ ** -2008\-04\-01\ ******* -2008\-07\-01\ -2008\-10\-01\ ** -\f[] -.fi -.SS add -.PP -Prompt for transactions and add them to the journal. -.TP -.B \f[C]\-\-no\-new\-accounts\f[] -don't allow creating new accounts; helps prevent typos when entering -account names -.RS -.RE -.PP -Many hledger users edit their journals directly with a text editor, or -generate them from CSV. -For more interactive data entry, there is the \f[C]add\f[] command, -which prompts interactively on the console for new transactions, and -appends them to the journal file (if there are multiple -\f[C]\-f\ FILE\f[] options, the first file is used.) Existing -transactions are not changed. -This is the only hledger command that writes to the journal file. -.PP -To use it, just run \f[C]hledger\ add\f[] and follow the prompts. -You can add as many transactions as you like; when you are finished, -enter \f[C]\&.\f[] or press control\-d or control\-c to exit. -.PP -Features: -.IP \[bu] 2 -add tries to provide useful defaults, using the most similar recent -transaction (by description) as a template. -.IP \[bu] 2 -You can also set the initial defaults with command line arguments. -.IP \[bu] 2 -Readline\-style edit keys can be used during data entry. -.IP \[bu] 2 -The tab key will auto\-complete whenever possible \- accounts, -descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[], -\f[C]tomorrow\f[]). -If the input area is empty, it will insert the default value. -.IP \[bu] 2 -If the journal defines a default commodity, it will be added to any bare -numbers entered. -.IP \[bu] 2 -A parenthesised transaction code may be entered following a date. -.IP \[bu] 2 -Comments and tags may be entered following a description or amount. -.IP \[bu] 2 -If you make a mistake, enter \f[C]<\f[] at any prompt to restart the -transaction. -.IP \[bu] 2 -Input prompts are displayed in a different colour when the terminal -supports it. -.PP -Example (see the tutorial for a detailed explanation): -.IP -.nf -\f[C] -$\ hledger\ add -Adding\ transactions\ to\ journal\ file\ /src/hledger/examples/sample.journal -Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults. -Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults. -An\ optional\ (CODE)\ may\ follow\ transaction\ dates. -An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts. -If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction. -To\ end\ a\ transaction,\ enter\ .\ when\ prompted. -To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c. -Date\ [2015/05/22]:\ -Description:\ supermarket -Account\ 1:\ expenses:food -Amount\ \ 1:\ $10 -Account\ 2:\ assets:checking -Amount\ \ 2\ [$\-10.0]:\ -Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ . -2015/05/22\ supermarket -\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10 -\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0 - -Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\ -Saved. -Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit) -Date\ [2015/05/22]:\ \ $ -\f[] -.fi -.SS balance -.PP -Show accounts and their balances. -Aliases: b, bal. -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date) -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv, html. -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.TP -.B \f[C]\-\-pretty\-tables\f[] -use unicode to display prettier tables. -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name (in flat mode). -With multiple columns, sorts by the row total, or by row average if that -is displayed. -.RS -.RE -.TP -.B \f[C]\-\-invert\f[] -display all amounts with reversed sign -.RS -.RE -.TP -.B \f[C]\-\-budget\f[] -show performance compared to budget goals defined by periodic -transactions -.RS -.RE -.TP -.B \f[C]\-\-show\-unbudgeted\f[] -with \[en]budget, show unbudgeted accounts also -.RS -.RE -.PP -The balance command is hledger's most versatile command. -Note, despite the name, it is not always used for showing real\-world -account balances; the more accounting\-aware balancesheet and -incomestatement may be more convenient for that. -.PP -By default, it displays all accounts, and each account's change in -balance during the entire period of the journal. -Balance changes are calculated by adding up the postings in each -account. -You can limit the postings matched, by a query, to see fewer accounts, -changes over a different time period, changes from only cleared -transactions, etc. -.PP -If you include an account's complete history of postings in the report, -the balance change is equivalent to the account's current ending -balance. -For a real\-world account, typically you won't have all transactions in -the journal; instead you'll have all transactions after a certain date, -and an \[lq]opening balances\[rq] transaction setting the correct -starting balance on that date. -Then the balance command will show real\-world account balances. -In some cases the \-H/\[en]historical flag is used to ensure this (more -below). -.PP -The balance command can produce several styles of report: -.SS Classic balance report -.PP -This is the original balance report, as found in Ledger. -It usually looks like this: -.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 -By default, accounts are displayed hierarchically, with subaccounts -indented below their parent. -At each level of the tree, accounts are sorted by account code if any, -then by account name. -Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. -.PP -\[lq]Boring\[rq] accounts, which contain a single interesting subaccount -and no balance of their own, are elided into the following line for more -compact output. -(Eg above, the \[lq]liabilities\[rq] account.) Use -\f[C]\-\-no\-elide\f[] to prevent this. -.PP -Account balances are \[lq]inclusive\[rq] \- they include the balances of -any subaccounts. -.PP -Accounts which have zero balance (and no non\-zero subaccounts) are -omitted. -Use \f[C]\-E/\-\-empty\f[] to show them. -.PP -A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to -suppress it, eg: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies -\f[] -.fi -.SS Customising the classic balance report -.PP -You can customise the layout of classic balance reports with -\f[C]\-\-format\ FMT\f[]: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-\-format\ "%20(account)\ %12(total)" -\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ $\-1 -\ \ \ \ \ \ \ \ \ bank:saving\ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ cash\ \ \ \ \ \ \ \ \ \ $\-2 -\ \ \ \ \ \ \ \ \ \ \ \ expenses\ \ \ \ \ \ \ \ \ \ \ $2 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ food\ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ \ \ \ \ \ \ \ \ supplies\ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ income\ \ \ \ \ \ \ \ \ \ $\-2 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ gifts\ \ \ \ \ \ \ \ \ \ $\-1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ salary\ \ \ \ \ \ \ \ \ \ $\-1 -\ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ $1 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -The FMT format string (plus a newline) specifies the formatting applied -to each account/balance pair. -It may contain any suitable text, with data fields interpolated like so: -.PP -\f[C]%[MIN][.MAX](FIELDNAME)\f[] -.IP \[bu] 2 -MIN pads with spaces to at least this width (optional) -.IP \[bu] 2 -MAX truncates at this width (optional) -.IP \[bu] 2 -FIELDNAME must be enclosed in parentheses, and can be one of: -.RS 2 -.IP \[bu] 2 -\f[C]depth_spacer\f[] \- a number of spaces equal to the account's -depth, or if MIN is specified, MIN * depth spaces. -.IP \[bu] 2 -\f[C]account\f[] \- the account's name -.IP \[bu] 2 -\f[C]total\f[] \- the account's balance/posted total, right justified -.RE -.PP -Also, FMT can begin with an optional prefix to control how -multi\-commodity amounts are rendered: -.IP \[bu] 2 -\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default) -.IP \[bu] 2 -\f[C]%^\f[] \- render on multiple lines, top\-aligned -.IP \[bu] 2 -\f[C]%,\f[] \- render on one line, comma\-separated -.PP -There are some quirks. -Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead -\f[C]%(account)\f[] has indentation built in. - Experimentation may be needed to get pleasing results. -.PP -Some example formats: -.IP \[bu] 2 -\f[C]%(total)\f[] \- the account's total -.IP \[bu] 2 -\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded -to 20 characters and clipped at 20 characters -.IP \[bu] 2 -\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50 -characters, total padded to 20 characters, with multiple commodities -rendered on one line -.IP \[bu] 2 -\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default -format for the single\-column balance report -.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 Flat mode -.PP -To see a flat list instead of the default hierarchical display, use -\f[C]\-\-flat\f[]. -In this mode, accounts (unless depth\-clipped) show their full names and -\[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[] or \f[C]depth:N\f[] or just \f[C]\-N\f[], -balance reports show accounts only to the specified numeric depth. -This is very useful to summarise a complex set of accounts and get an -overview. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-N\ \-1 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities -\f[] -.fi -.PP -Flat\-mode balance reports, which normally show exclusive balances, show -inclusive balances at the depth limit. -.SS Multicolumn balance report -.PP -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. -They share many of the above features, but they show the report as a -table, with columns representing time periods. -This mode is activated by providing a reporting interval. -.PP -There are three types of multicolumn 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 -Multicolumn 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 -.PP -Limitations: -.PP -In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market -price on the report end date, for all columns (not the price on each -column's end date). -.PP -Eliding of boring parent accounts in tree mode, as in the classic -balance report, is not yet supported in multicolumn reports. -.SS Budget report -.PP -With \f[C]\-\-budget\f[], extra columns are displayed showing budget -goals for each account and period, if any. -Budget goals are defined by periodic transactions. -This is very useful for comparing planned and actual income, expenses, -time usage, etc. -\[en]budget is most often combined with a report interval. -.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 report: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ -======================++================================================= -\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $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 -By default, only accounts with budget goals during the report period are -shown. -\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well. -Top\-level accounts with no budget goals anywhere below them are grouped -under \f[C]\f[]. -.PP -You can roll over unspent budgets to next period with -\f[C]\-\-cumulative\f[]: -.IP -.nf -\f[C] -$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative -Budget\ performance\ in\ 2017/11/01\-2017/12/31: - -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ -======================++================================================= -\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $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 -Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported -with \f[C]\-\-budget\f[]. -.PP -For more examples, see Budgeting and Forecasting. -.SS Output format -.PP -The balance command supports output destination and output format -selection. -.SS balancesheet -.PP -This command displays a simple balance sheet, showing historical ending -balances of asset and liability accounts (ignoring any report begin -date). -It assumes that these accounts are under a top\-level \f[C]asset\f[] or -\f[C]liability\f[] account (case insensitive, plural forms also -allowed). -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). -(bs) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period, instead of historical ending -balances -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of historical ending balances -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date) (default) -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE -.PP -Example: -.IP -.nf -\f[C] -$\ hledger\ balancesheet -Balance\ Sheet - -Assets: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -Liabilities: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -With a reporting interval, multiple columns will be shown, one for each -report period. -As with multicolumn balance reports, you can alter the report mode with -\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. -Normally balancesheet shows historical ending balances, which is what -you need for a balance sheet; note this means it ignores report begin -dates. -.PP -This command also supports output destination and output format -selection. -.SS balancesheetequity -.PP -Just like balancesheet, but also reports Equity (which it assumes is -under a top\-level \f[C]equity\f[] account). -.PP -Example: -.IP -.nf -\f[C] -$\ hledger\ balancesheetequity -Balance\ Sheet\ With\ Equity - -Assets: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-3\ \ \ \ cash -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 - -Liabilities: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 - -Equity: -\ \ \ \ \ \ \ \ \ \ $1\ \ equity:owner -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ $1 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.SS cashflow -.PP -This command displays a simple cashflow statement, showing changes in -\[lq]cash\[rq] accounts. -It assumes that these accounts are under a top\-level \f[C]asset\f[] -account (case insensitive, plural forms also allowed) and do not contain -\f[C]receivable\f[] or \f[C]A/R\f[] in their name. -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). -(cf) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of changes during periods -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date), instead of changes during each period -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row (in simple reports) -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE -.PP -Example: -.IP -.nf -\f[C] -$\ hledger\ cashflow -Cashflow\ Statement - -Cash\ flows: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 -\f[] -.fi -.PP -With a reporting interval, multiple columns will be shown, one for each -report period. -Normally cashflow shows changes in assets per period, though as with -multicolumn balance reports you can alter the report mode with -\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. -.PP -This command also supports output destination and output format -selection. -.SS check\-dates -.PP -Check that transactions are sorted by increasing date. -With a query, only matched transactions' dates are checked. -.SS check\-dupes -.PP -Report account names having the same leaf but different prefixes. -An example: http://stefanorodighiero.net/software/hledger\-dupes.html -.SS close -.PP -Print closing/opening transactions that bring some or all account -balances to zero and back. -Can be useful for bringing asset/liability balances across file -boundaries, or for closing out income/expenses for a period. -This was formerly called \[lq]equity\[rq], as in Ledger, and that alias -is also accepted. -See close \[en]help for more. -.SS files -.PP -List all files included in the journal. -With a REGEX argument, only file names matching the regular expression -(case sensitive) are shown. -.SS help -.PP -Show any of the hledger manuals. -.PP -The \f[C]help\f[] command displays any of the main hledger manuals, in -one of several ways. -Run it with no argument to list the manuals, or provide a full or -partial manual name to select one. -.PP -hledger manuals are available in several formats. -hledger help will use the first of these display methods that it finds: -info, man, $PAGER, less, stdout (or when non\-interactive, just stdout). -You can force a particular viewer with the \f[C]\-\-info\f[], -\f[C]\-\-man\f[], \f[C]\-\-pager\f[], \f[C]\-\-cat\f[] flags. -.IP -.nf -\f[C] -$\ hledger\ help -Please\ choose\ a\ manual\ by\ typing\ "hledger\ help\ MANUAL"\ (a\ substring\ is\ ok). -Manuals:\ hledger\ hledger\-ui\ hledger\-web\ hledger\-api\ journal\ csv\ timeclock\ timedot -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ help\ h\ \-\-man - -hledger(1)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger\ User\ Manuals\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger(1) - -NAME -\ \ \ \ \ \ \ hledger\ \-\ a\ command\-line\ accounting\ tool - -SYNOPSIS -\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS] -\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS] -\ \ \ \ \ \ \ hledger - -DESCRIPTION -\ \ \ \ \ \ \ hledger\ \ is\ \ a\ \ cross\-platform\ \ program\ \ for\ tracking\ money,\ time,\ or\ any -\&... -\f[] -.fi -.SS import -.PP -Read new transactions added to each FILE since last run, and add them to -the main journal file. -.TP -.B \f[C]\-\-dry\-run\f[] -just show the transactions to be imported -.RS -.RE -.PP -The input files are specified as arguments \- no need to write \-f -before each one. -So eg to add new transactions from all CSV files to the main journal, -it's just: \f[C]hledger\ import\ *.csv\f[] -.PP -New transactions are detected in the same way as print \[en]new: by -assuming transactions are always added to the input files in increasing -date order, and by saving \f[C]\&.latest.FILE\f[] state files. -.PP -The \[en]dry\-run output is in journal format, so you can filter it, eg -to see only uncategorised transactions: -.IP -.nf -\f[C] -$\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\-assertions -\f[] -.fi -.SS incomestatement -.PP -This command displays a simple income statement, showing revenues and -expenses during a period. -It assumes that these accounts are under a top\-level \f[C]revenue\f[] -or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural -forms also allowed). -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). -(is) -.TP -.B \f[C]\-\-change\f[] -show balance change in each period (default) -.RS -.RE -.TP -.B \f[C]\-\-cumulative\f[] -show balance change accumulated across periods (in multicolumn reports), -instead of changes during periods -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical ending balance in each period (includes postings before -report start date), instead of changes during each period -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show accounts as a tree; amounts include subaccounts (default in simple -reports) -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show accounts as a list; amounts exclude subaccounts except when account -is depth\-clipped (default in multicolumn reports) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show a row average column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-T\ \-\-row\-total\f[] -show a row total column (in multicolumn mode) -.RS -.RE -.TP -.B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -omit N leading account name parts (in flat mode) -.RS -.RE -.TP -.B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) -.RS -.RE -.TP -.B \f[C]\-\-format=LINEFORMAT\f[] -in single\-column balance reports: use this custom line format -.RS -.RE -.TP -.B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account code/name -.RS -.RE -.PP -This command displays a simple income statement. -It currently assumes that you have top\-level accounts named -\f[C]income\f[] (or \f[C]revenue\f[]) and \f[C]expense\f[] (plural forms -also allowed.) -.IP -.nf -\f[C] -$\ hledger\ incomestatement -Income\ Statement - -Revenues: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 - -Expenses: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2 - -Total: -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -With a reporting interval, multiple columns will be shown, one for each -report period. -Normally incomestatement shows revenues/expenses per period, though as -with multicolumn balance reports you can alter the report mode with -\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. -.PP -This command also supports output destination and output format -selection. -.SS prices -.PP -Print market price directives from the journal. -With \[en]costs, also print synthetic market prices based on transaction -prices. -With \[en]inverted\-costs, also print inverse prices based on -transaction prices. -Prices (and postings providing prices) can be filtered by a query. -.SS print -.PP -Show transactions from the journal. -Aliases: p, txns. -.TP -.B \f[C]\-m\ STR\ \-\-match=STR\f[] -show the transaction whose description is most similar to STR, and is -most recent -.RS -.RE -.TP -.B \f[C]\-\-new\f[] -show only newer\-dated transactions added in each file since last run -.RS -.RE -.TP -.B \f[C]\-x\ \ \ \ \ \-\-explicit\f[] -show all amounts explicitly -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv. -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.IP -.nf -\f[C] -$\ hledger\ print -2008/01/01\ income -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -2008/06/01\ gift -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 - -2008/06/02\ save -\ \ \ \ assets:bank:saving\ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1 - -2008/06/03\ *\ eat\ &\ shop -\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ expenses:supplies\ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 - -2008/12/31\ *\ pay\ off -\ \ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1 -\f[] -.fi -.PP -The print command displays full journal entries (transactions) from the -journal file in date order, tidily formatted. -print's output is always a valid hledger journal. -It preserves all transaction information, but it does not preserve -directives or inter\-transaction comments -.PP -Normally, the journal entry's explicit or implicit amount style is -preserved. -Ie when an amount is omitted in the journal, it will be omitted in the -output. -You can use the \f[C]\-x\f[]/\f[C]\-\-explicit\f[] flag to make all -amounts explicit, which can be useful for troubleshooting or for making -your journal more readable and robust against data entry errors. -Note, \f[C]\-x\f[] will cause postings with a multi\-commodity amount -(these can arise when a multi\-commodity transaction has an implicit -amount) will be split into multiple single\-commodity postings, for -valid journal output. -.PP -With \f[C]\-B\f[]/\f[C]\-\-cost\f[], amounts with transaction prices are -converted to cost using that price. -This can be used for troubleshooting. -.PP -With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show -at most one transaction: the one one whose description is most similar -to STR, and is most recent. -STR should contain at least two characters. -If there is no similar\-enough match, no transaction will be shown. -.PP -With \f[C]\-\-new\f[], for each FILE being read, hledger reads (and -writes) a special state file (\f[C]\&.latest.FILE\f[] in the same -directory), containing the latest transaction date(s) that were seen -last time FILE was read. -When this file is found, only transactions with newer dates (and new -transactions on the latest date) are printed. -This is useful for ignoring already\-seen entries in import data, such -as downloaded CSV files. -Eg: -.IP -.nf -\f[C] -$\ hledger\ \-f\ bank1.csv\ print\ \-\-new -#\ shows\ transactions\ added\ since\ last\ print\ \-\-new\ on\ this\ file -\f[] -.fi -.PP -This assumes that transactions added to FILE always have same or -increasing dates, and that transactions on the same day do not get -reordered. -See also the import command. -.PP -This command also supports output destination and output format -selection. -Here's an example of print's CSV output: -.IP -.nf -\f[C] -$\ hledger\ print\ \-Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting\-status","posting\-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","\-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","\-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","\-1","$","1","","","" -"4","2008/06/03","","*","","eat\ &\ shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat\ &\ shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat\ &\ shop","","assets:cash","\-2","$","2","","","" -"5","2008/12/31","","*","","pay\ off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay\ off","","assets:bank:checking","\-1","$","1","","","" -\f[] -.fi -.IP \[bu] 2 -There is one CSV record per posting, with the parent transaction's -fields repeated. -.IP \[bu] 2 -The \[lq]txnidx\[rq] (transaction index) field shows which postings -belong to the same transaction. -(This number might change if transactions are reordered within the file, -files are parsed/included in a different order, etc.) -.IP \[bu] 2 -The amount is separated into \[lq]commodity\[rq] (the symbol) and -\[lq]amount\[rq] (numeric quantity) fields. -.IP \[bu] 2 -The numeric amount is repeated in either the \[lq]credit\[rq] or -\[lq]debit\[rq] column, for convenience. -(Those names are not accurate in the accounting sense; it just puts -negative amounts under credit and zero or greater amounts under debit.) -.SS print\-unique -.PP -Print transactions which do not reuse an already\-seen description. -.SS register -.PP -Show postings and their running total. -Aliases: r, reg. -.TP -.B \f[C]\-\-cumulative\f[] -show running total from report start date (default) -.RS -.RE -.TP -.B \f[C]\-H\ \-\-historical\f[] -show historical running total/balance (includes postings before report -start date) -.RS -.RE -.TP -.B \f[C]\-A\ \-\-average\f[] -show running average of posting amounts instead of total (implies -\[en]empty) -.RS -.RE -.TP -.B \f[C]\-r\ \-\-related\f[] -show postings' siblings instead -.RS -.RE -.TP -.B \f[C]\-w\ N\ \-\-width=N\f[] -set output width (default: terminal width or COLUMNS. -\-wN,M sets description width as well) -.RS -.RE -.TP -.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] -select the output format. -Supported formats: txt, csv. -.RS -.RE -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.PP -The register command displays postings, one per line, and their running -total. -This is typically used with a query selecting a particular account, to -see that account's activity: -.IP -.nf -\f[C] -$\ hledger\ register\ checking -2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2 -2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -The \f[C]\-\-historical\f[]/\f[C]\-H\f[] flag adds the balance from any -undisplayed prior postings to the running total. -This is useful when you want to see only recent activity, with a -historically accurate running balance: -.IP -.nf -\f[C] -$\ hledger\ register\ checking\ \-b\ 2008/6\ \-\-historical -2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2 -2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 -\f[] -.fi -.PP -The \f[C]\-\-depth\f[] option limits the amount of sub\-account detail -displayed. -.PP -The \f[C]\-\-average\f[]/\f[C]\-A\f[] flag shows the running average -posting amount instead of the running total (so, the final number -displayed is the average for the whole report period). -This flag implies \f[C]\-\-empty\f[] (see below). -It is affected by \f[C]\-\-historical\f[]. -It works best when showing just one account and one commodity. -.PP -The \f[C]\-\-related\f[]/\f[C]\-r\f[] flag shows the \f[I]other\f[] -postings in the transactions of the postings which would normally be -shown. -.PP -With a reporting interval, register shows summary postings, one per -interval, aggregating the postings to each account: -.IP -.nf -\f[C] -$\ hledger\ register\ \-\-monthly\ income -2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2 -\f[] -.fi -.PP -Periods with no activity, and summary postings with a zero amount, are -not shown by default; use the \f[C]\-\-empty\f[]/\f[C]\-E\f[] flag to -see them: -.IP -.nf -\f[C] -$\ hledger\ register\ \-\-monthly\ income\ \-E -2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/02\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/03\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/04\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/05\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 -2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/07\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/08\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/09\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/10\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 -\f[] -.fi -.PP -Often, you'll want to see just one line per interval. -The \f[C]\-\-depth\f[] option helps with this, causing subaccounts to be -aggregated: -.IP -.nf -\f[C] -$\ hledger\ register\ \-\-monthly\ assets\ \-\-depth\ 1h -2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1 -2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 -2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 -\f[] -.fi -.PP -Note when using report intervals, if you specify start/end dates these -will be adjusted outward if necessary to contain a whole number of -intervals. -This ensures that the first and last intervals are full length and -comparable to the others in the report. -.SS Custom register output -.PP -register uses the full terminal width by default, except on windows. -You can override this by setting the \f[C]COLUMNS\f[] environment -variable (not a bash shell variable) or by using the -\f[C]\-\-width\f[]/\f[C]\-w\f[] option. -.PP -The description and account columns normally share the space equally -(about half of (width \- 40) each). -You can adjust this by adding a description width as part of -\[en]width's argument, comma\-separated: \f[C]\-\-width\ W,D\f[] . -Here's a diagram: -.IP -.nf -\f[C] -<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ width\ (W)\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-> -date\ (10)\ \ description\ (D)\ \ \ \ \ \ \ account\ (W\-41\-D)\ \ \ \ \ amount\ (12)\ \ \ balance\ (12) -DDDDDDDDDD\ dddddddddddddddddddd\ \ aaaaaaaaaaaaaaaaaaa\ \ AAAAAAAAAAAA\ \ AAAAAAAAAAAA -\f[] -.fi -.PP -and some examples: -.IP -.nf -\f[C] -$\ hledger\ reg\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ terminal\ width\ (or\ 80\ on\ windows) -$\ hledger\ reg\ \-w\ 100\ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ width\ 100 -$\ COLUMNS=100\ hledger\ reg\ \ \ \ \ \ \ \ \ #\ set\ with\ one\-time\ environment\ variable -$\ export\ COLUMNS=100;\ hledger\ reg\ #\ set\ till\ session\ end\ (or\ window\ resize) -$\ hledger\ reg\ \-w\ 100,40\ \ \ \ \ \ \ \ \ \ \ #\ set\ overall\ width\ 100,\ description\ width\ 40 -$\ hledger\ reg\ \-w\ $COLUMNS,40\ \ \ \ \ \ #\ use\ terminal\ width,\ and\ set\ description\ width -\f[] -.fi -.PP -This command also supports output destination and output format -selection. -.SS register\-match -.PP -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. -Helps ledger\-autosync detect already\-seen transactions when importing. -.SS rewrite -.PP -Print all transactions, adding custom postings to the matched ones. -.SS roi -.PP -Shows time\-weighted (TWR) and money\-weighted (IRR) rate of return on -your investments. -See \f[C]roi\ \-\-help\f[] for more. -.SS stats -.PP -Show some journal statistics. -.TP -.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] -write output to FILE. -A file extension matching one of the above formats selects that format. -.RS -.RE -.IP -.nf -\f[C] -$\ hledger\ stats -Main\ journal\ file\ \ \ \ \ \ \ \ :\ /src/hledger/examples/sample.journal -Included\ journal\ files\ \ \ :\ -Transactions\ span\ \ \ \ \ \ \ \ :\ 2008\-01\-01\ to\ 2009\-01\-01\ (366\ days) -Last\ transaction\ \ \ \ \ \ \ \ \ :\ 2008\-12\-31\ (2333\ days\ ago) -Transactions\ \ \ \ \ \ \ \ \ \ \ \ \ :\ 5\ (0.0\ per\ day) -Transactions\ last\ 30\ days:\ 0\ (0.0\ per\ day) -Transactions\ last\ 7\ days\ :\ 0\ (0.0\ per\ day) -Payees/descriptions\ \ \ \ \ \ :\ 5 -Accounts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 8\ (depth\ 3) -Commodities\ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 1\ ($) -\f[] -.fi -.PP -The stats command displays summary information for the whole journal, or -a matched part of it. -With a reporting interval, it shows a report for each report period. -.PP -This command also supports output destination and output format -selection. -.SS tags -.PP -List all the tag names used in the journal. -With a TAGREGEX argument, only tag names matching the regular expression -(case insensitive) are shown. -With additional QUERY arguments, only transactions matching the query -are considered. -.SS test -.PP -Run built\-in unit tests. -.PP -Prints test names and their results on stdout. -If any test fails or gives an error, the exit code will be non\-zero. -.PP -Test names include a group prefix. -If a (exact, case sensitive) group prefix, or a full test name is -provided as the first argument, only that group or test is run. -.PP -If a numeric second argument is provided, it will set the randomness -seed, for repeatable results from tests using randomness (currently none -of them). -.PP -This is mainly used by developers, but it's nice to be able to -sanity\-check your installed hledger executable at any time. -All tests are expected to pass \- if you ever see otherwise, something -has gone wrong, please report a bug! -.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, but it's superseded now by the built\-in roi command. -.SS Experimental add\-ons -.PP -These are available in source form in the hledger repo's bin/ directory; -installing them is pretty easy. -They may be less mature and documented than built\-in commands. -Reading and tweaking these is a good way to start making your own! -.SS autosync -.PP -hledger\-autosync is a symbolic link for easily running -ledger\-autosync, if installed. -ledger\-autosync does deduplicating conversion of OFX data and some CSV -formats, and can also download the data if your bank offers OFX Direct -Connect. -.SS chart -.PP -hledger\-chart.hs is an old pie chart generator, in need of some love. -.SS check -.PP -hledger\-check.hs checks more powerful account balance assertions. -.SH ENVIRONMENT -.PP -\f[B]COLUMNS\f[] The screen width used by the register command. -Default: the full terminal width. -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede addon command options with \f[C]\-\-\f[] when -invoked from hledger is awkward. -.PP -When input data contains non\-ascii characters, a suitable system locale -must be configured (or there will be an unhelpful error). -Eg on POSIX, set LANG to something other than C. -.PP -In a Microsoft Windows CMD window, non\-ascii characters and colours are -not supported. -.PP -In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger -add. -.PP -Not all of Ledger's journal file syntax is supported. -See file format differences. -.PP -On large data files, hledger is slower and uses more memory than Ledger. -.SH TROUBLESHOOTING -.PP -Here are some issues you might encounter when you run hledger (and -remember you can also seek help from the IRC channel, mail list or bug -tracker): -.PP -\f[B]Successfully installed, but \[lq]No command `hledger' -found\[rq]\f[] -.PD 0 -.P -.PD -stack and cabal install binaries into a special directory, which should -be added to your PATH environment variable. -Eg on unix\-like systems, that is ~/.local/bin and ~/.cabal/bin -respectively. -.PP -\f[B]I set a custom LEDGER_FILE, but hledger is still using the default -file\f[] -.PD 0 -.P -.PD -\f[C]LEDGER_FILE\f[] should be a real environment variable, not just a -shell variable. -The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it. -You may need to use \f[C]export\f[]. -Here's an explanation. -.PP -\f[B]\[lq]Illegal byte sequence\[rq] or \[lq]Invalid or incomplete -multibyte or wide character\[rq] errors\f[] -.PD 0 -.P -.PD -In order to handle non\-ascii letters and symbols (like £), hledger -needs an appropriate locale. -This is usually configured system\-wide; you can also configure it -temporarily. -The locale may need to be one that supports UTF\-8, if you built hledger -with GHC < 7.2 (or possibly always, I'm not sure yet). -.PP -Here's an example of setting the locale temporarily, on ubuntu -gnu/linux: -.IP -.nf -\f[C] -$\ file\ my.journal -my.journal:\ UTF\-8\ Unicode\ text\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ the\ file\ is\ UTF8\-encoded -$\ locale\ \-a -C -en_US.utf8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ a\ UTF8\-aware\ locale\ is\ available -POSIX -$\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ this\ command -\f[] -.fi -.PP -Here's one way to set it permanently, there are probably better ways: +.TH "hledger" "1" "February 2019" "hledger 1.13" "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]\-\-separator=CHAR\f[] +Field separator to expect when reading CSV (default: \[aq],\[aq]) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +rename accounts named OLD to NEW +.RS +.RE +.TP +.B \f[C]\-\-anon\f[] +anonymize accounts and payees +.RS +.RE +.TP +.B \f[C]\-\-pivot\ FIELDNAME\f[] +use some other field or tag for the account name +.RS +.RE +.TP +.B \f[C]\-I\ \-\-ignore\-assertions\f[] +ignore any failing balance assertions +.RS +.RE +.PP +General reporting options: +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once using +period expressions syntax (overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\f[] +match the secondary date instead (see command help for other effects) +.RS +.RE +.TP +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) +.RS +.RE +.TP +.B \f[C]\-P\ \-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-NUM\ \-\-depth=NUM\f[] +hide/aggregate accounts or postings more than NUM levels deep +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show items with zero amount, normally hidden (and vice\-versa in +hledger\-ui/hledger\-web) +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +convert amounts to their cost at transaction time (using the transaction +price, if any) +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +convert amounts to their market value on the report end date (using the +most recent applicable market price, if any) +.RS +.RE +.TP +.B \f[C]\-\-auto\f[] +apply automated posting rules to modify transactions. +.RS +.RE +.TP +.B \f[C]\-\-forecast\f[] +apply periodic transaction rules to generate future transactions, to 6 +months from now or report end date. +.RS +.RE +.PP +When a reporting option appears more than once in the command line, the +last one takes precedence. +.PP +Some reporting options can also be written as query arguments. +.SS Command options +.PP +To see options for a particular command, including command\-specific +options, run: \f[C]hledger\ COMMAND\ \-h\f[]. +.PP +Command\-specific options must be written after the command name, eg: +\f[C]hledger\ print\ \-x\f[]. +.PP +Additionally, if the command is an addon, you may need to put its +options after a double\-hyphen, eg: +\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. +Or, you can run the addon executable directly: +\f[C]hledger\-ui\ \-\-watch\f[]. +.SS Command arguments +.PP +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. +.SS Argument files +.PP +You can save a set of command line options/arguments in a file, one per +line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command +line. +To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a +\f[C]\-\-\f[] argument. +For more, see Save frequently used options. +.SS Special characters in arguments and queries +.PP +In shell command lines, option and argument values which contain +"problematic" characters, ie spaces, and also characters significant to +your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], \f[C])\f[], +\f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing them in quotes +or by writing backslashes before the characters. +Eg: +.PP +\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. +.SS More escaping +.PP +Characters significant both to the shell and in regular expressions may +need one extra level of escaping. +These include parentheses, the pipe symbol and the dollar sign. +Eg, to match the dollar symbol, bash users should do: +.PP +\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] +.PP +or: +.PP +\f[C]hledger\ balance\ cur:\\\\$\f[] +.SS Even more escaping +.PP +When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[], +hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options +and arguments once, so you might need to \f[I]triple\f[]\-escape. +Eg in bash, running the ui command and matching the dollar sign, +it\[aq]s: +.PP +\f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] +.PP +or: +.PP +\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] +.PP +If you asked why \f[I]four\f[] slashes above, this may help: +.PP +.TS +tab(@); +l l. +T{ +unescaped: +T}@T{ +\f[C]$\f[] +T} +T{ +escaped: +T}@T{ +\f[C]\\$\f[] +T} +T{ +double\-escaped: +T}@T{ +\f[C]\\\\$\f[] +T} +T{ +triple\-escaped: +T}@T{ +\f[C]\\\\\\\\$\f[] +T} +.TE +.PP +(The number of backslashes in fish shell is left as an exercise for the +reader.) +.PP +You can always avoid the extra escaping for addons by running the addon +directly: +.PP +\f[C]hledger\-ui\ cur:\\\\$\f[] +.SS Less escaping +.PP +Inside an argument file, or in the search field of hledger\-ui or +hledger\-web, or at a GHCI prompt, you need one less level of escaping +than at the command line. +And backslashes may work better than quotes. +Eg: +.PP +\f[C]ghci>\ :main\ balance\ cur:\\$\f[] +.SS Command line tips +.PP +If in doubt, keep things simple: +.IP \[bu] 2 +write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[]) +.IP \[bu] 2 +run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[]) +.IP \[bu] 2 +enclose problematic args in single quotes +.IP \[bu] 2 +if needed, also add a backslash to escape regexp metacharacters +.PP +To find out exactly how a command line is being parsed, add +\f[C]\-\-debug=2\f[] to troubleshoot. +.SS Unicode characters +.PP +hledger is expected to handle unicode (non\-ascii) characters, but this +requires a well\-configured environment. +.PP +To handle unicode characters in the command line or input data, a system +locale that can decode them must be configured (POSIX\[aq]s default +\f[C]C\f[] locale will not work). +Eg in bash, you could do: +.IP +.nf +\f[C] +export\ LANG=en_US.UTF\-8 +\f[] +.fi +.PP +See Troubleshooting for more about this. +.PP +Unicode characters should appear correctly in hledger\[aq]s output. +For the hledger and hledger\-ui tools, this requires that +.IP \[bu] 2 +your terminal supports unicode +.IP \[bu] 2 +the terminal\[aq]s font includes the required unicode glyphs +.IP \[bu] 2 +the terminal is configured to display "wide" characters as double width +(otherwise report alignment will be off) +.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.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\[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]2004/10/1\f[], \f[C]2004\-01\-01\f[], \f[C]2004.9.1\f[] +T}@T{ +exact date, several separators allowed. +Year is 4+ digits, month is 1\-12, day is 1\-31 +T} +T{ +\f[C]2004\f[] +T}@T{ +start of year +T} +T{ +\f[C]2004/10\f[] +T}@T{ +start of month +T} +T{ +\f[C]10/1\f[] +T}@T{ +month and day in current year +T} +T{ +\f[C]21\f[] +T}@T{ +day in current month +T} +T{ +\f[C]october,\ oct\f[] +T}@T{ +start of month in current year +T} +T{ +\f[C]yesterday,\ today,\ tomorrow\f[] +T}@T{ +\-1, 0, 1 days from today +T} +T{ +\f[C]last/this/next\ day/week/month/quarter/year\f[] +T}@T{ +\-1, 0, 1 periods from the current period +T} +T{ +\f[C]20181201\f[] +T}@T{ +8 digit YYYYMMDD with valid year month and day +T} +T{ +\f[C]201812\f[] +T}@T{ +6 digit YYYYMM with valid year and month +T} +.TE +.PP +Counterexamples \- malformed digit sequences might give surprising +results: +.PP +.TS +tab(@); +l l. +T{ +\f[C]201813\f[] +T}@T{ +6 digits with an invalid month is parsed as start of 6\-digit year +T} +T{ +\f[C]20181301\f[] +T}@T{ +8 digits with an invalid month is parsed as start of 8\-digit year +T} +T{ +\f[C]20181232\f[] +T}@T{ +8 digits with an invalid day gives an error +T} +T{ +\f[C]201801012\f[] +T}@T{ +9+ digits beginning with a valid YYYYMMDD gives an error +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 +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[] \-\- starts on +2008/12/29, closest preceeding Monday +T} +T{ +\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \-\- 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[] \-\- periods will have boundaries +on 2008/01/01, 2008/03/01, ... +T} +T{ +\f[C]\-p\ "every\ 2\ weeks"\f[] \-\- starts on closest preceeding Monday +T} +T{ +\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \-\- 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[] \-\- periods will go from Tue +to Tue +T} +T{ +\f[C]\-p\ "every\ Tue"\f[] \-\- same +T} +T{ +\f[C]\-p\ "every\ 15th\ day"\f[] \-\- period boundaries will be on 15th +of each month +T} +T{ +\f[C]\-p\ "every\ 2nd\ Monday"\f[] \-\- period boundaries will be on +second Monday of each month +T} +T{ +\f[C]\-p\ "every\ 11/05"\f[] \-\- yearly periods with boundaries on 5th +of Nov +T} +T{ +\f[C]\-p\ "every\ 5th\ Nov"\f[] \-\- same +T} +T{ +\f[C]\-p\ "every\ Nov\ 5th"\f[] \-\- 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\[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 reported amounts to their +current market value. +.PD 0 +.P +.PD +Specifically, when there is a market price (P directive) for the +amount\[aq]s commodity, dated on or before today\[aq]s date (or the +report end date if specified), the amount will be converted to the +price\[aq]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\ \-N\ euros +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi +.PP +What are they worth at end of nov 3 ? +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V\ \-e\ 2016/11/4 +\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros +\f[] +.fi +.PP +What are they worth after 2016/12/21 ? +(no report end date specified, defaults to today) +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V +\ \ \ \ \ \ \ \ \ \ \ \ \ $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 +Currently, \-V has a limitation in multicolumn balance reports: it uses +the market prices on the report end date for all columns. +(Instead of the prices on each column\[aq]s end date.) +.SS Combining \-B and \-V +.PP +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. +.SS Output destination +.PP +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. +This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) +$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE +\f[] +.fi +.SS Output format +.PP +Some commands can write their output in other formats. +Eg print and register can output CSV, and the balance commands can +output CSV or HTML. +This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by +specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with +\f[C]\-o/\-\-output\-file\f[]. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout +$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv +\f[] +.fi +.SS Regular expressions +.PP +hledger uses regular expressions in a number of places: +.IP \[bu] 2 +query terms, on the command line and in the hledger\-web search form: +\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[], +\f[C]tag:...=REGEX\f[] +.IP \[bu] 2 +CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[] +.IP \[bu] 2 +account alias directives and options: +\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[], +\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[] +.PP +hledger\[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[BC]not:\f[B]\f[], eg to +exclude a particular subaccount. +.TP +.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[] +match account names by this regular expression. +(With no prefix, \f[C]acct:\f[] is assumed.) +.RS +.RE +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\[aq]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\[aq]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 +accounts, a +.PD 0 +.P +.PD +Show account names. +.PP +This command lists account names, either declared with account +directives (\-\-declared), posted to (\-\-used), or both (the default). +With query arguments, only matched account names and account names +referenced by matched postings are shown. +It shows a flat list by default. +With \f[C]\-\-tree\f[], it uses indentation to show the account +hierarchy. +In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few +account name components. +Account names can be depth\-clipped with \f[C]depth:N\f[] or +\f[C]\-\-depth\ N\f[] or \f[C]\-N\f[]. +.PP +Examples: +.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 +activity +.PD 0 +.P +.PD +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. +.PP +Examples: +.IP +.nf +\f[C] +$\ hledger\ activity\ \-\-quarterly +2008\-01\-01\ ** +2008\-04\-01\ ******* +2008\-07\-01\ +2008\-10\-01\ ** +\f[] +.fi +.SS add +.PP +add +.PD 0 +.P +.PD +Prompt for transactions and add them to the journal. +.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 (by +description) recent transaction (filtered by the query, if any) 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 +balance, bal, b +.PD 0 +.P +.PD +Show accounts and their balances. +.PP +The balance command is hledger\[aq]s most versatile command. +Note, despite the name, it is not always used for showing real\-world +account balances; the more accounting\-aware balancesheet and +incomestatement may be more convenient for that. +.PP +By default, it displays all accounts, and each account\[aq]s change in +balance during the entire period of the journal. +Balance changes are calculated by adding up the postings in each +account. +You can limit the postings matched, by a query, to see fewer accounts, +changes over a different time period, changes from only cleared +transactions, etc. +.PP +If you include an account\[aq]s complete history of postings in the +report, the balance change is equivalent to the account\[aq]s current +ending balance. +For a real\-world account, typically you won\[aq]t have all transactions +in the journal; instead you\[aq]ll have all transactions after a certain +date, and an "opening balances" transaction setting the correct starting +balance on that date. +Then the balance command will show real\-world account balances. +In some cases the \-H/\-\-historical flag is used to ensure this (more +below). +.PP +The balance command can produce several styles of report: +.SS Classic balance report +.PP +This is the original balance report, as found in Ledger. +It usually looks like this: +.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 +By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. +At each level of the tree, accounts are sorted by account code if any, +then by account name. +Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. +.PP +"Boring" accounts, which contain a single interesting subaccount and no +balance of their own, are elided into the following line for more +compact output. +(Eg above, the "liabilities" account.) Use \f[C]\-\-no\-elide\f[] to +prevent this. +.PP +Account balances are "inclusive" \- they include the balances of any +subaccounts. +.PP +Accounts which have zero balance (and no non\-zero subaccounts) are +omitted. +Use \f[C]\-E/\-\-empty\f[] to show them. +.PP +A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to +suppress it, eg: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\f[] +.fi +.SS Customising the classic balance report +.PP +You can customise the layout of classic balance reports with +\f[C]\-\-format\ FMT\f[]: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-format\ "%20(account)\ %12(total)" +\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ \ \ \ \ \ \ bank:saving\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ cash\ \ \ \ \ \ \ \ \ \ $\-2 +\ \ \ \ \ \ \ \ \ \ \ \ expenses\ \ \ \ \ \ \ \ \ \ \ $2 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ food\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ supplies\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ income\ \ \ \ \ \ \ \ \ \ $\-2 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ gifts\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ salary\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ $1 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. +It may contain any suitable text, with data fields interpolated like so: +.PP +\f[C]%[MIN][.MAX](FIELDNAME)\f[] +.IP \[bu] 2 +MIN pads with spaces to at least this width (optional) +.IP \[bu] 2 +MAX truncates at this width (optional) +.IP \[bu] 2 +FIELDNAME must be enclosed in parentheses, and can be one of: +.RS 2 +.IP \[bu] 2 +\f[C]depth_spacer\f[] \- a number of spaces equal to the account\[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 Flat mode +.PP +To see a flat list instead of the default hierarchical display, use +\f[C]\-\-flat\f[]. +In this mode, accounts (unless depth\-clipped) show their full names and +"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[] or \f[C]depth:N\f[] or just \f[C]\-N\f[], +balance reports show accounts only to the specified numeric depth. +This is very useful to summarise a complex set of accounts and get an +overview. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-N\ \-1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities +\f[] +.fi +.PP +Flat\-mode balance reports, which normally show exclusive balances, show +inclusive balances at the depth limit. +.SS Multicolumn balance report +.PP +Multicolumn or tabular balance reports are a very useful hledger +feature, and usually the preferred style. +They share many of the above features, but they show the report as a +table, with columns representing time periods. +This mode is activated by providing a reporting interval. +.PP +There are three types of multicolumn 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 +Multicolumn 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). +With \f[C]\-\-budget\f[], \f[C]\-\-empty\f[] also shows unbudgeted +accounts. +.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 +.PP +Limitations: +.PP +In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market +price on the report end date, for all columns (not the price on each +column\[aq]s end date). +.PP +Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. +.SS Budget report +.PP +With \f[C]\-\-budget\f[], extra columns are displayed showing budget +goals for each account and period, if any. +Budget goals are defined by periodic transactions. +This is very useful for comparing planned and actual income, expenses, +time usage, etc. +\-\-budget is most often combined with a report interval. +.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 report: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ \ $53\ [\ 106%\ of\ \ \ \ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $412\ [\ 103%\ of\ \ \ $400]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ \ \ 0\ [\ \ \ 0%\ of\ \ \ \ $30]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $2100\ [\ 105%\ of\ \ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +By default, only accounts with budget goals during the report period are +shown. +In the example above, transactions in \f[C]expenses:gifts\f[] and +\f[C]expenses:supplies\f[] are counted towards \f[C]expenses\f[] budget, +but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are +not shown, as they don\[aq]t have any budgets. +.PP +You can use \f[C]\-\-empty\f[] shows unbudgeted accounts as well: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget\ \-\-empty +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ \ $53\ [\ 106%\ of\ \ \ \ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $412\ [\ 103%\ of\ \ \ $400]\ +\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ \ \ 0\ [\ \ \ 0%\ of\ \ \ \ $30]\ +\ expenses:supplies\ \ \ \ ||\ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $2100\ [\ 105%\ of\ \ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\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 +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ $1060\ [\ 110%\ of\ \ \ $960]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ $102\ [\ 102%\ of\ \ \ $100]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $808\ [\ 101%\ of\ \ \ $800]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ $30\ [\ \ 50%\ of\ \ \ \ $60]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $4050\ [\ 101%\ of\ \ $4000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported +with \f[C]\-\-budget\f[]. +.PP +For more examples, see Budgeting and Forecasting. +.SS Nested budgets +.PP +You can add budgets to any account in your account hierarchy. +If you have budgets on both parent account and some of its children, +then budget(s) of the child account(s) would be added to the budget of +their parent, much like account balances behave. +.PP +In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. +.PP +To illustrate this, consider the following budget: +.IP +.nf +\f[C] +~\ monthly\ from\ 2019/01 +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 +\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 +\ \ \ \ liabilities +\f[] +.fi +.PP +With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both \f[C]expenses:personal\f[] and +\f[C]expenses\f[] is $1100. +.PP +Transactions in \f[C]expenses:personal:electronics\f[] will be counted +both towards its $100 budget and $1100 of \f[C]expenses:personal\f[] , +and transactions in any other subaccount of \f[C]expenses:personal\f[] +would be counted towards only towards the budget of +\f[C]expenses:personal\f[]. +.PP +For example, let\[aq]s consider these transactions: +.IP +.nf +\f[C] +~\ monthly\ from\ 2019/01 +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 +\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 +\ \ \ \ liabilities + +2019/01/01\ Google\ home\ hub +\ \ \ \ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ $90.00 +\ \ \ \ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-90.00 + +2019/01/02\ Phone\ screen\ protector +\ \ \ \ expenses:personal:electronics:upgrades\ \ \ \ \ \ \ \ \ \ $10.00 +\ \ \ \ liabilities + +2019/01/02\ Weekly\ train\ ticket +\ \ \ \ expenses:personal:train\ tickets\ \ \ \ \ \ \ $153.00 +\ \ \ \ liabilities + +2019/01/03\ Flowers +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ $30.00 +\ \ \ \ liabilities +\f[] +.fi +.PP +As you can see, we have transactions in +\f[C]expenses:personal:electronics:upgrades\f[] and +\f[C]expenses:personal:train\ tickets\f[], and since both of these +accounts are without explicitly defined budget, these transactions would +be counted towards budgets of \f[C]expenses:personal:electronics\f[] and +\f[C]expenses:personal\f[] accordingly: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-M +Budget\ performance\ in\ 2019/01: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ +===============================++=============================== +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal:electronics\ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ +\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +And with \f[C]\-\-empty\f[], we can get a better picture of budget +allocation and consumption: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-M\ \-\-empty +Budget\ performance\ in\ 2019/01: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ +========================================++=============================== +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ +\ expenses:personal:electronics:upgrades\ ||\ \ \ $10.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ expenses:personal:train\ tickets\ \ \ \ \ \ \ \ ||\ \ $153.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.SS Output format +.PP +The balance command supports output destination and output format +selection. +.SS balancesheet +.PP +balancesheet, bs +.PD 0 +.P +.PD +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). +It assumes that these accounts are under a top\-level \f[C]asset\f[] or +\f[C]liability\f[] account (case insensitive, plural forms also +allowed). +.PP +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ balancesheet +Balance\ Sheet + +Assets: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +Liabilities: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +As with multicolumn balance reports, you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +Normally balancesheet shows historical ending balances, which is what +you need for a balance sheet; note this means it ignores report begin +dates. +.PP +This command also supports output destination and output format +selection. +.SS balancesheetequity +.PP +balancesheetequity, bse +.PD 0 +.P +.PD +Just like balancesheet, but also reports Equity (which it assumes is +under a top\-level \f[C]equity\f[] account). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ balancesheetequity +Balance\ Sheet\ With\ Equity + +Assets: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-3\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +Liabilities: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 + +Equity: +\ \ \ \ \ \ \ \ \ \ $1\ \ equity:owner +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ $1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.SS cashflow +.PP +cashflow, cf +.PD 0 +.P +.PD +This command displays a simple cashflow statement, showing changes in +"cash" accounts. +It assumes that these accounts are under a top\-level \f[C]asset\f[] +account (case insensitive, plural forms also allowed) and do not contain +\f[C]receivable\f[] or \f[C]A/R\f[] in their name. +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ cashflow +Cashflow\ Statement + +Cash\ flows: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +Normally cashflow shows changes in assets per period, though as with +multicolumn balance reports you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. +.SS check\-dates +.PP +check\-dates +.PD 0 +.P +.PD +Check that transactions are sorted by increasing date. +With \-\-date2, checks secondary dates instead. +With \-\-strict, dates must also be unique. +With a query, only matched transactions\[aq] dates are checked. +Reads the default journal file, or another specified with \-f. +.SS check\-dupes +.PP +check\-dupes +.PD 0 +.P +.PD +Reports account names having the same leaf but different prefixes. +In other words, two or more leaves that are categorized differently. +Reads the default journal file, or another specified as an argument. +.PP +An example: http://stefanorodighiero.net/software/hledger\-dupes.html +.SS close +.PP +close, equity +.PD 0 +.P +.PD +Prints a "closing balances" transaction and an "opening balances" +transaction that bring account balances to and from zero, respectively. +Useful for bringing asset/liability balances forward into a new journal +file, or for closing out revenues/expenses to retained earnings at the +end of a period. +.PP +The closing transaction transfers balances to "equity:closing balances". +The opening transaction transfers balances from "equity:opening +balances". +You can chose to print just one of the transactions by using the +\f[C]\-\-opening\f[] or \f[C]\-\-closing\f[] flag. +.PP +If you split your journal files by time (eg yearly), you will typically +run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. +This makes the files self contained, so that correct balances are +reported no matter which of them are loaded. +Ie, if you load just one file, the balances are initialised correctly; +or if you load several files, the redundant closing/opening transactions +cancel each other out. +(They will show up in print or register reports; you can exclude them +with a query like +\f[C]not:desc:\[aq](opening|closing)\ balances\[aq]\f[].) +.PP +If you\[aq]re running a business, you might also use this command to +"close the books" at the end of an accounting period, transferring +income statement account balances to retained earnings. +(You may want to change the equity account name to something like +"equity:retained earnings".) +.PP +By default, the closing transaction is dated yesterday, the balances are +calculated as of end of yesterday, and the opening transaction is dated +today. +To close on some other date, use: +\f[C]hledger\ close\ \-e\ OPENINGDATE\f[]. +Eg, to close/open on the 2018/2019 boundary, use \f[C]\-e\ 2019\f[]. +You can also use \-p or \f[C]date:PERIOD\f[] (any starting date is +ignored). +.PP +Both transactions will include balance assertions for the +closed/reopened accounts. +You probably shouldn\[aq]t use status or realness filters (like \-C or +\-R or \f[C]status:\f[]) with this command, or the generated balance +assertions will depend on these flags. +Likewise, if you run this command with \-\-auto, the balance assertions +will probably always require \-\-auto. +.PP +Examples: +.PP +Carrying asset/liability balances into a new file for 2019, all from +command line: +.PP +\f[I]Warning: we use \f[CI]>>\f[I] here to append; be careful not to +type a single \f[CI]>\f[I] which would wipe your journal!\f[] +.IP +.nf +\f[C] +$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-opening\ >>2019.journal +$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-closing\ >>2018.journal +\f[] +.fi +.PP +Now: +.IP +.nf +\f[C] +$\ hledger\ bs\ \-f\ 2019.journal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ one\ file\ \-\ balances\ are\ correct +$\ hledger\ bs\ \-f\ 2018.journal\ \-f\ 2019.journal\ \ \ #\ two\ files\ \-\ balances\ still\ correct +$\ hledger\ bs\ \-f\ 2018.journal\ not:desc:closing\ \ #\ to\ see\ year\-end\ balances,\ must\ exclude\ closing\ txn +\f[] +.fi +.PP +Transactions spanning the closing date can complicate matters, breaking +balance assertions: +.IP +.nf +\f[C] +2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5 +\ \ \ \ assets:bank:checking\ \ \-5\ \ ;\ [2019/1/2] +\f[] +.fi +.PP +Here\[aq]s one way to resolve that: +.IP +.nf +\f[C] +;\ in\ 2018.journal: +2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5 +\ \ \ \ liabilities:pending + +;\ in\ 2019.journal: +2019/1/2\ clearance\ of\ last\ year\[aq]s\ pending\ transactions +\ \ \ \ liabilities:pending\ \ \ \ 5\ =\ 0 +\ \ \ \ assets:checking +\f[] +.fi +.SS files +.PP +files +.PD 0 +.P +.PD +List all files included in the journal. +With a REGEX argument, only file names matching the regular expression +(case sensitive) are shown. +.SS help +.PP +help +.PD 0 +.P +.PD +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. +.PP +Examples: +.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 +import +.PD 0 +.P +.PD +Read new transactions added to each FILE since last run, and add them to +the main journal file. +Or with \-\-dry\-run, just print the transactions that would be added. +.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\[aq]s just: \f[C]hledger\ import\ *.csv\f[] +.PP +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 \f[C]\&.latest.FILE\f[] state files. +.PP +The \-\-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 +incomestatement, is +.PD 0 +.P +.PD +This command displays a simple income statement, showing revenues and +expenses during a period. +It assumes that these accounts are under a top\-level \f[C]revenue\f[] +or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural +forms also allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +.PP +This command displays a simple income statement. +It currently assumes that you have top\-level accounts named +\f[C]income\f[] (or \f[C]revenue\f[]) and \f[C]expense\f[] (plural forms +also allowed.) +.IP +.nf +\f[C] +$\ hledger\ incomestatement +Income\ Statement + +Revenues: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +Expenses: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +Normally incomestatement shows revenues/expenses per period, though as +with multicolumn balance reports you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. +.SS prices +.PP +prices +.PD 0 +.P +.PD +Print market price directives from the journal. +With \-\-costs, also print synthetic market prices based on transaction +prices. +With \-\-inverted\-costs, also print inverse prices based on transaction +prices. +Prices (and postings providing prices) can be filtered by a query. +.SS print +.PP +print, txns, p +.PD 0 +.P +.PD +Show transaction journal entries, sorted by date. +.PP +The print command displays full journal entries (transactions) from the +journal file in date order, tidily formatted. +With \-\-date2, transactions are sorted by secondary date instead. +.PP +print\[aq]s output is always a valid hledger journal. +.PD 0 +.P +.PD +It preserves all transaction information, but it does not preserve +directives or inter\-transaction comments +.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 +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. +This can be used for troubleshooting. +.PP +With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show +at most one transaction: the one one whose description is most similar +to STR, and is most recent. +STR should contain at least two characters. +If there is no similar\-enough match, no transaction will be shown. +.PP +With \f[C]\-\-new\f[], for each FILE being read, hledger reads (and +writes) a special state file (\f[C]\&.latest.FILE\f[] in the same +directory), containing the latest transaction date(s) that were seen +last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. +This is useful for ignoring already\-seen entries in import data, such +as downloaded CSV files. +Eg: +.IP +.nf +\f[C] +$\ hledger\ \-f\ bank1.csv\ print\ \-\-new +#\ shows\ transactions\ added\ since\ last\ print\ \-\-new\ on\ this\ file +\f[] +.fi +.PP +This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. +See also the import command. +.PP +This command also supports output destination and output format +selection. +Here\[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\-unique +.PD 0 +.P +.PD +Print transactions which do not reuse an already\-seen description. +.PP +Example: +.IP +.nf +\f[C] +$\ cat\ unique.journal +1/1\ test +\ (acct:one)\ \ 1 +2/2\ test +\ (acct:two)\ \ 2 +$\ LEDGER_FILE=unique.journal\ hledger\ print\-unique +(\-f\ option\ not\ supported) +2015/01/01\ test +\ \ \ \ (acct:one)\ \ \ \ \ \ \ \ \ \ \ \ \ 1 +\f[] +.fi +.SS register +.PP +register, reg, r +.PD 0 +.P +.PD +Show postings and their running total. +.PP +The register command displays postings in date order, 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 +With \-\-date2, it shows and sorts by secondary date instead. +.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 (won\[aq]t display correctly in \-\-help): +.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,\ &\ description\ width\ 40 +\f[] +.fi +.PP +This command also supports output destination and output format +selection. +.SS register\-match +.PP +register\-match +.PD 0 +.P +.PD +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. +If there are multiple equally good matches, it shows the most recent. +Query options (options, not arguments) can be used to restrict the +search space. +Helps ledger\-autosync detect already\-seen transactions when importing. +.SS rewrite +.PP +rewrite +.PD 0 +.P +.PD +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +\-\-auto. +.PP +This is a start at a generic rewriter of transaction entries. +It reads the default journal and prints the transactions, like print, +but adds one or more specified postings to any transactions matching +QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction\[aq]s first posting amount. +.PP +Examples: +.IP +.nf +\f[C] +hledger\-rewrite.hs\ ^income\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\ \ ;\ income\ tax\[aq]\ \-\-add\-posting\ \[aq](reserve:gifts)\ \ $100\[aq] +hledger\-rewrite.hs\ expenses:gifts\ \-\-add\-posting\ \[aq](reserve:gifts)\ \ *\-1"\[aq] +hledger\-rewrite.hs\ \-f\ rewrites.hledger +\f[] +.fi +.PP +rewrites.hledger may consist of entries like: +.IP +.nf +\f[C] +=\ ^income\ amt:<0\ date:2017 +\ \ (liabilities:tax)\ \ *0.33\ \ ;\ tax\ on\ income +\ \ (reserve:grocery)\ \ *0.25\ \ ;\ reserve\ 25%\ for\ grocery +\ \ (reserve:)\ \ *0.25\ \ ;\ reserve\ 25%\ for\ grocery +\f[] +.fi +.PP +Note the single quotes to protect the dollar sign from bash, and the two +spaces between account and amount. +.PP +More: +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ [QUERY]\ \ \ \ \ \ \ \ \-\-add\-posting\ "ACCT\ \ AMTEXPR"\ ... +$\ hledger\ rewrite\ \-\-\ ^income\ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq] +$\ hledger\ rewrite\ \-\-\ expenses:gifts\ \-\-add\-posting\ \[aq](budget:gifts)\ \ *\-1"\[aq] +$\ hledger\ rewrite\ \-\-\ ^income\ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq](budget:foreign\ currency)\ \ *0.25\ JPY;\ diversify\[aq] +\f[] +.fi +.PP +Argument for \f[C]\-\-add\-posting\f[] option is a usual posting of +transaction with an exception for amount specification. +More precisely, you can use \f[C]\[aq]*\[aq]\f[] (star symbol) before +the amount to indicate that that this is a factor for an amount of +original matched posting. +If the amount includes a commodity name, the new posting amount will be +in the new commodity; otherwise, it will be in the matched posting +amount\[aq]s commodity. +.SS Re\-write rules in a file +.PP +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. +I.e instead of specifying this operations in command line you can put +them in a journal file. +.IP +.nf +\f[C] +$\ rewrite\-rules.journal +\f[] +.fi +.PP +Make contents look like this: +.IP +.nf +\f[C] +=\ ^income +\ \ \ \ (liabilities:tax)\ \ *.33 + +=\ expenses:gifts +\ \ \ \ budget:gifts\ \ *\-1 +\ \ \ \ assets:budget\ \ *1 +\f[] +.fi +.PP +Note that \f[C]\[aq]=\[aq]\f[] (equality symbol) that is used instead of +date in transactions you usually write. +It indicates the query by which you want to match the posting to add new +ones. +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-f\ input.journal\ \-f\ rewrite\-rules.journal\ >\ rewritten\-tidy\-output.journal +\f[] +.fi +.PP +This is something similar to the commands pipeline: +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-f\ input.journal\ \[aq]^income\[aq]\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq]\ \\ +\ \ |\ hledger\ rewrite\ \-\-\ \-f\ \-\ expenses:gifts\ \ \ \ \ \ \-\-add\-posting\ \[aq]budget:gifts\ \ *\-1\[aq]\ \ \ \ \ \ \ \\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\-add\-posting\ \[aq]assets:budget\ \ *1\[aq]\ \ \ \ \ \ \ \\ +\ \ >\ rewritten\-tidy\-output.journal +\f[] +.fi +.PP +It is important to understand that relative order of such entries in +journal is important. +You can re\-use result of previously added postings. +.SS Diff output format +.PP +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. +.IP +.nf +\f[C] +$\ hledger\ rewrite\ \-\-\ \-\-diff\ \-f\ examples/sample.journal\ \[aq]^income\[aq]\ \-\-add\-posting\ \[aq](liabilities:tax)\ \ *.33\[aq] +\f[] +.fi +.PP +Output might look like: +.IP +.nf +\f[C] +\-\-\-\ /tmp/examples/sample.journal ++++\ /tmp/examples/sample.journal +\@\@\ \-18,3\ +18,4\ \@\@ +\ 2008/01/01\ income +\-\ \ \ \ assets:bank:checking\ \ $1 ++\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ income:salary ++\ \ \ \ (liabilities:tax)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\@\@\ \-22,3\ +23,4\ \@\@ +\ 2008/06/01\ gift +\-\ \ \ \ assets:bank:checking\ \ $1 ++\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ income:gifts ++\ \ \ \ (liabilities:tax)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +If you\[aq]ll pass this through \f[C]patch\f[] tool you\[aq]ll get +transactions containing the posting that matches your query be updated. +Note that multiple files might be update according to list of input +files specified via \f[C]\-\-file\f[] options and \f[C]include\f[] +directives inside of these files. +.PP +Be careful. +Whole transaction being re\-formatted in a style of output from +\f[C]hledger\ print\f[]. +.PP +See also: +.PP +https://github.com/simonmichael/hledger/issues/99 +.SS rewrite vs. print \-\-auto +.PP +This command predates print \-\-auto, and currently does much the same +thing, but with these differences: +.IP \[bu] 2 +with multiple files, rewrite lets rules in any file affect all other +files. +print \-\-auto uses standard directive scoping; rules affect only child +files. +.IP \[bu] 2 +rewrite\[aq]s query limits which transactions can be rewritten; all are +printed. +print \-\-auto\[aq]s query limits which transactions are printed. +.IP \[bu] 2 +rewrite applies rules specified on command line or in the journal. +print \-\-auto applies rules specified in the journal. +.SS roi +.PP +roi +.PD 0 +.P +.PD +Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return +on your investments. +.PP +This command assumes that you have account(s) that hold nothing but your +investments and whenever you record current appraisal/valuation of these +investments you offset unrealized profit and loss into account(s) that, +again, hold nothing but unrealized profit and loss. +.PP +Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. +.PP +At a minimum, you need to supply a query (which could be just an account +name) to select your investments with \f[C]\-\-inv\f[], and another +query to identify your profit and loss transactions with +\f[C]\-\-pnl\f[]. +.PP +It will compute and display the internalized rate of return (IRR) and +time\-weighted rate of return (TWR) for your investments for the time +period requested. +Both rates of return are annualized before display, regardless of the +length of reporting interval. +.SS stats +.PP +stats +.PD 0 +.P +.PD +Show some journal statistics. +.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 +Example: +.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 +This command also supports output destination and output format +selection. +.SS tags +.PP +tags +.PD 0 +.P +.PD +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. +.SS test +.PP +test +.PD 0 +.P +.PD +Run built\-in unit tests. +.PP +This command runs the unit tests built in to hledger\-lib and hledger, +printing test names and results on stdout. +If any test fails, the exit code will be non\-zero. +.PP +Test names include a group prefix. +If a (exact, case sensitive) group prefix, or a full test name is +provided as the first argument, only that group or test is run. +.PP +If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). +.PP +This is mainly used by developers, but it\[aq]s nice to be able to +sanity\-check your installed hledger executable at any time. +All tests are expected to pass \- if you ever see otherwise, something +has gone wrong, please report a bug! +.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, but it\[aq]s superseded now by the built\-in roi command. +.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 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] diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -1,13 +1,13 @@ cabal-version: 1.12 --- This file has been generated from package.yaml by hpack version 0.31.0. +-- This file has been generated from package.yaml by hpack version 0.31.1. -- -- see: https://github.com/sol/hpack -- --- hash: 269994bfba5ad36962478f05df1bf958a94778ec5b36db499d768b64aa3e411a +-- hash: 0f31726cb805b74d59400bb1d7502bb6c6c7f01eb41ac0272c4da6a8d94144b2 name: hledger -version: 1.12.1 +version: 1.13 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 @@ -30,7 +30,7 @@ tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.3 build-type: Simple extra-source-files: - CHANGES + CHANGES.md README.md test/test.hs bench/10000x1000x10.journal @@ -61,6 +61,30 @@ embeddedfiles/hledger_timedot.5 embeddedfiles/hledger_timedot.txt embeddedfiles/hledger_timedot.info + Hledger/Cli/Commands/Accounts.txt + Hledger/Cli/Commands/Activity.txt + Hledger/Cli/Commands/Add.txt + Hledger/Cli/Commands/Balance.txt + Hledger/Cli/Commands/Balancesheet.txt + Hledger/Cli/Commands/Balancesheetequity.txt + Hledger/Cli/Commands/Cashflow.txt + Hledger/Cli/Commands/Checkdates.txt + Hledger/Cli/Commands/Checkdupes.txt + Hledger/Cli/Commands/Close.txt + Hledger/Cli/Commands/Files.txt + Hledger/Cli/Commands/Help.txt + Hledger/Cli/Commands/Import.txt + Hledger/Cli/Commands/Incomestatement.txt + Hledger/Cli/Commands/Prices.txt + Hledger/Cli/Commands/Print.txt + Hledger/Cli/Commands/Printunique.txt + Hledger/Cli/Commands/Register.txt + Hledger/Cli/Commands/Registermatch.txt + Hledger/Cli/Commands/Rewrite.txt + Hledger/Cli/Commands/Roi.txt + Hledger/Cli/Commands/Stats.txt + Hledger/Cli/Commands/Tags.txt + Hledger/Cli/Commands/Test.txt source-repository head type: git @@ -112,7 +136,7 @@ other-modules: Paths_hledger ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.12.1" + cpp-options: -DVERSION="1.13" build-depends: Decimal , Diff @@ -125,12 +149,11 @@ , data-default >=0.5 , directory , easytest - , file-embed >=0.0.10 , filepath , hashable >=1.2.4 , haskeline >=0.6 , here - , hledger-lib >=1.12 && <1.13 + , hledger-lib >=1.13 && <1.14 , lucid , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 @@ -165,7 +188,7 @@ 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 -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.12.1" + cpp-options: -DVERSION="1.13" build-depends: Decimal , ansi-terminal >=0.6.2.3 @@ -177,12 +200,11 @@ , data-default >=0.5 , directory , easytest - , file-embed >=0.0.10 , filepath , haskeline >=0.6 , here , hledger - , hledger-lib >=1.12 && <1.13 + , hledger-lib >=1.13 && <1.14 , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 , mtl @@ -219,7 +241,7 @@ 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 -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.12.1" + cpp-options: -DVERSION="1.13" build-depends: Decimal , ansi-terminal >=0.6.2.3 @@ -231,12 +253,11 @@ , data-default >=0.5 , directory , easytest - , file-embed >=0.0.10 , filepath , haskeline >=0.6 , here , hledger - , hledger-lib >=1.12 && <1.13 + , hledger-lib >=1.13 && <1.14 , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 , mtl @@ -285,12 +306,11 @@ , data-default >=0.5 , directory , easytest - , file-embed >=0.0.10 , filepath , haskeline >=0.6 , here , hledger - , hledger-lib >=1.12 && <1.13 + , hledger-lib >=1.13 && <1.14 , html , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -3,2703 +3,2835 @@  File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.12 -*********************** - -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 in arguments and queries:: -* Command line tips:: -* Unicode characters:: -* Input files:: -* Smart dates:: -* Report start & end date:: -* Report intervals:: -* Period expressions:: -* Depth limiting:: -* Pivoting:: -* Cost:: -* Market value:: -* Combining -B and -V:: -* Output destination:: -* Output format:: -* Regular expressions:: - - -File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS - -2.1 General options -=================== - -To see general usage help, including general options which are supported -by most hledger commands, run 'hledger -h'. - - General help options: - -'-h --help' - - show general usage (or after COMMAND, command usage) -'--version' - - show version -'--debug[=N]' - - show debug output (levels 1-9, default: 1) - - General input options: - -'-f FILE --file=FILE' - - use a different input file. For stdin, use - (default: - '$LEDGER_FILE' or '$HOME/.hledger.journal') -'--rules-file=RULESFILE' - - Conversion rules file to use when reading CSV (default: FILE.rules) -'--separator=CHAR' - - Field separator to expect when reading CSV (default: ',') -'--alias=OLD=NEW' - - rename accounts named OLD to NEW -'--anon' - - anonymize accounts and payees -'--pivot FIELDNAME' - - use some other field or tag for the account name -'-I --ignore-assertions' - - ignore any failing balance assertions - - General reporting options: - -'-b --begin=DATE' - - include postings/txns on or after this date -'-e --end=DATE' - - include postings/txns before this date -'-D --daily' - - multiperiod/multicolumn report by day -'-W --weekly' - - multiperiod/multicolumn report by week -'-M --monthly' - - multiperiod/multicolumn report by month -'-Q --quarterly' - - multiperiod/multicolumn report by quarter -'-Y --yearly' - - multiperiod/multicolumn report by year -'-p --period=PERIODEXP' - - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) -'--date2' - - match the secondary date instead (see command help for other - effects) -'-U --unmarked' - - include only unmarked postings/txns (can combine with -P or -C) -'-P --pending' - - include only pending postings/txns -'-C --cleared' - - include only cleared postings/txns -'-R --real' - - include only non-virtual postings -'-NUM --depth=NUM' - - hide/aggregate accounts or postings more than NUM levels deep -'-E --empty' - - show items with zero amount, normally hidden (and vice-versa in - hledger-ui/hledger-web) -'-B --cost' - - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' - - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) -'--auto' - - apply automated posting rules to modify transactions. -'--forecast' - - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, -the last one takes precedence. - - Some reporting options can also be written as query arguments. - - -File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS - -2.2 Command options -=================== - -To see options for a particular command, including command-specific -options, run: 'hledger COMMAND -h'. - - Command-specific options must be written after the command name, eg: -'hledger print -x'. - - Additionally, if the command is an addon, you may need to put its -options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can -run the addon executable directly: 'hledger-ui --watch'. - - -File: hledger.info, Node: Command arguments, Next: Argument files, Prev: Command options, Up: OPTIONS - -2.3 Command arguments -===================== - -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. - - -File: hledger.info, Node: Argument files, Next: Special characters in arguments and queries, 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 in arguments and queries, Next: Command line tips, Prev: Argument files, Up: OPTIONS - -2.5 Special characters in arguments and queries -=============================================== - -In shell command lines, option and argument values which contain -"problematic" characters, ie spaces, and also characters significant to -your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by -enclosing them in quotes or by writing backslashes before the -characters. Eg: - - 'hledger register -p 'last year' "accounts receivable -(receivable|payable)" amt:\>100'. -* Menu: - -* More escaping:: -* Even more escaping:: -* Less escaping:: - - -File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries - -2.5.1 More escaping -------------------- - -Characters significant both to the shell and in regular expressions may -need one extra level of escaping. 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:\\$' - - -File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries - -2.5.2 Even more escaping ------------------------- - -When hledger runs an addon executable (eg you type 'hledger ui', hledger -runs 'hledger-ui'), it de-escapes command-line options and arguments -once, so you might need to _triple_-escape. Eg in bash, running the ui -command and matching the dollar sign, it's: - - 'hledger ui cur:'\\$'' - - or: - - 'hledger ui cur:\\\\$' - - If you asked why _four_ slashes above, this may help: - -unescaped: '$' -escaped: '\$' -double-escaped: '\\$' -triple-escaped: '\\\\$' - - (The number of backslashes in fish shell is left as an exercise for -the reader.) - - You can always avoid the extra escaping for addons by running the -addon directly: - - 'hledger-ui cur:\\$' - - -File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries - -2.5.3 Less escaping -------------------- - -Inside an argument file, or in the search field of hledger-ui or -hledger-web, or at a GHCI prompt, you need one less level of escaping -than at the command line. And backslashes may work better than quotes. -Eg: - - 'ghci> :main balance cur:\$' - - -File: hledger.info, Node: Command line tips, Next: Unicode characters, Prev: Special characters in arguments and queries, Up: OPTIONS - -2.6 Command line tips -===================== - -If in doubt, keep things simple: - - * write options after the command ('hledger CMD -OPTIONS ARGS') - * run add-on executables directly ('hledger-ui -OPTIONS ARGS') - * enclose problematic args in single quotes - * if needed, also add a backslash to escape regexp metacharacters - - To find out exactly how a command line is being parsed, add -'--debug=2' to troubleshoot. - - -File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Command line tips, Up: OPTIONS - -2.7 Unicode characters -====================== - -hledger is expected to handle unicode (non-ascii) characters, but this -requires a well-configured environment. - - To handle unicode characters in the command line or input data, a -system locale that can decode them must be configured (POSIX's default -'C' locale will not work). Eg in bash, you could do: - -export LANG=en_US.UTF-8 - - See Troubleshooting for more about this. - - Unicode characters should appear correctly in hledger's output. For -the hledger and hledger-ui tools, this requires that - - * your terminal supports unicode - * the terminal's font includes the required unicode glyphs - * the terminal is configured to display "wide" characters as double - width (otherwise report alignment will be off) - - -File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS - -2.8 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.9 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: - -'2004/10/1', '2004-01-01', '2004.9.1' exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 -'2004' start of year -'2004/10' start of month -'10/1' month and day in current year -'21' day in current month -'october, oct' start of month in current year -'yesterday, today, tomorrow' -1, 0, 1 days from today -'last/this/next -1, 0, 1 periods from the current period -day/week/month/quarter/year' -'20181201' 8 digit YYYYMMDD with valid year month and day -'201812' 6 digit YYYYMM with valid year and month - - Counterexamples - malformed digit sequences might give surprising -results: - -'201813' 6 digits with an invalid month is parsed as start of 6-digit year -'20181301' 8 digits with an invalid month is parsed as start of 8-digit year -'20181232' 8 digits with an invalid day gives an error -'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error - - -File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS - -2.10 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.11 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.12 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.13 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.14 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.15 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.16 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 -N euros - €100 assets:euros - - What are they worth at end of nov 3 ? - -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date -specified, defaults to today) - -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - Currently, hledger's -V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). - - Currently, -V has a limitation in multicolumn balance reports: it -uses the market prices on the report end date for all columns. (Instead -of the prices on each column's end date.) - - -File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS - -2.17 Combining -B and -V -======================== - -Using -B/-cost and -V/-value together is currently allowed, but the -results are probably not meaningful. Let us know if you find a use for -this. - - -File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS - -2.18 Output destination -======================= - -Some commands (print, register, stats, the balance commands) can write -their output to a destination other than the console. This is -controlled by the '-o/--output-file' option. - -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE - - -File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS - -2.19 Output format -================== - -Some commands can write their output in other formats. Eg print and -register can output CSV, and the balance commands can output CSV or -HTML. This is controlled by the '-O/--output-format' option, or by -specifying a '.csv' or '.html' file extension with '-o/--output-file'. - -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv - - -File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS - -2.20 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', 'acct:REGEX'* - - match account names by this regular expression. (With no prefix, - 'acct:' is assumed.) same as above - -*'amt:N, amt:N, amt:>=N'* - - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not - tested, and will always match.) The comparison has two modes: if N - is preceded by a + or - sign (or is 0), the two signed numbers are - compared. Otherwise, the absolute magnitudes are compared, - ignoring sign. -*'code:REGEX'* - - match by transaction code (eg check number) -*'cur:REGEX'* - - match postings or transactions including any amounts whose - currency/commodity symbol is fully matched by REGEX. (For a partial - match, use '.*REGEX.*'). Note, to match characters which are - regex-significant, like the dollar sign ('$'), you need to prepend - '\'. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: 'hledger - print cur:'\$'' or 'hledger print cur:\\$'. -*'desc:REGEX'* - - match transaction descriptions. -*'date:PERIODEXPR'* - - match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: 'date:2016', - 'date:thismonth', 'date:2000/2/1-2/15', 'date:lastweek-'. If the - '--date2' command line flag is present, this matches secondary - dates instead. -*'date2:PERIODEXPR'* - - match secondary dates within the specified period. -*'depth:N'* - - match (or display, depending on command) accounts at or above this - depth -*'note:REGEX'* - - match transaction notes (part of description right of '|', or whole - description when there's no '|') -*'payee:REGEX'* - - match transaction payee/payer names (part of description left of - '|', or whole description when there's no '|') -*'real:, real:0'* - - match real or virtual postings respectively -*'status:, status:!, status:*'* - - match unmarked, pending, or cleared transactions respectively -*'tag:REGEX[=REGEX]'* - - match by tag name, and optionally also by tag value. Note a tag: - query is considered to match a transaction if it matches any of the - postings. Also remember that postings inherit the tags of their - parent transaction. - - The following special search term is used automatically in -hledger-web, only: - -*'inacct:ACCTNAME'* - - tells hledger-web to show the transaction register for this - account. Can be filtered further with 'acct' etc. - - Some of these can also be expressed as command-line options (eg -'depth:2' is equivalent to '--depth 2'). Generally you can mix options -and query arguments, and the resulting query will be their intersection -(perhaps excluding the '-p/--period' option). - - -File: hledger.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top - -4 COMMANDS -********** - -hledger provides a number of subcommands; 'hledger' with no arguments -shows a list. - - If you install additional 'hledger-*' packages, or if you put -programs or scripts named 'hledger-NAME' in your PATH, these will also -be listed as subcommands. - - Run a subcommand by writing its name as first argument (eg 'hledger -incomestatement'). You can also write one of the standard short aliases -displayed in parentheses in the command list ('hledger b'), or any any -unambiguous prefix of a command name ('hledger inc'). - - Here are all the builtin commands in alphabetical order. See also -'hledger' for a more organised command list, and 'hledger CMD -h' for -detailed command help. -* Menu: - -* accounts:: -* activity:: -* add:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check-dates:: -* check-dupes:: -* close:: -* files:: -* help:: -* import:: -* incomestatement:: -* prices:: -* print:: -* print-unique:: -* register:: -* register-match:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: - - -File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS - -4.1 accounts -============ - -Show account names. Alias: a. - -'--declared' - - show account names declared with account directives -'--used' - - show account names posted to by transactions -'--tree' - - show short account names and their parents, as a tree -'--flat' - - show full account names, as a list (default) -'--drop=N' - - in flat mode: omit N leading account name parts - - This command lists account names, either declared with account -directives (-declared), posted to (-used), or both (default). With -query arguments, only matched account names and account names referenced -by matched postings are shown. It shows a flat list by default. With -'--tree', it uses indentation to show the account hierarchy. In flat -mode you can add '--drop N' to omit the first few account name -components. Account names can be depth-clipped with '--depth N' or -depth:N. - - Examples: - -$ hledger accounts --tree -assets - bank - checking - saving - cash -expenses - food - supplies -income - gifts - salary -liabilities - debts - -$ hledger accounts --drop 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS - -4.2 activity -============ - -Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS - -4.3 add -======= - -Prompt for transactions and add them to the journal. - -'--no-new-accounts' - - don't allow creating new accounts; helps prevent typos when - entering account names - - Many hledger users edit their journals directly with a text editor, -or generate them from CSV. For more interactive data entry, there is the -'add' command, which prompts interactively on the console for new -transactions, and appends them to the journal file (if there are -multiple '-f FILE' options, the first file is used.) Existing -transactions are not changed. This is the only hledger command that -writes to the journal file. - - To use it, just run 'hledger add' and follow the prompts. You can -add as many transactions as you like; when you are finished, enter '.' -or press control-d or control-c to exit. - - Features: - - * add tries to provide useful defaults, using the most similar recent - transaction (by description) as a template. - * You can also set the initial defaults with command line arguments. - * Readline-style edit keys can be used during data entry. - * The tab key will auto-complete whenever possible - accounts, - descriptions, dates ('yesterday', 'today', 'tomorrow'). If the - input area is empty, it will insert the default value. - * If the journal defines a default commodity, it will be added to any - bare numbers entered. - * A parenthesised transaction code may be entered following a date. - * Comments and tags may be entered following a description or amount. - * If you make a mistake, enter '<' at any prompt to restart the - transaction. - * Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see the tutorial for a detailed explanation): - -$ hledger add -Adding transactions to journal file /src/hledger/examples/sample.journal -Any command line arguments will be used as defaults. -Use tab key to complete, readline keys to edit, enter to accept defaults. -An optional (CODE) may follow transaction dates. -An optional ; COMMENT may follow descriptions or amounts. -If you make a mistake, enter < at any prompt to restart the transaction. -To end a transaction, enter . when prompted. -To quit, enter . at a date prompt or press control-d or control-c. -Date [2015/05/22]: -Description: supermarket -Account 1: expenses:food -Amount 1: $10 -Account 2: assets:checking -Amount 2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): . -2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - -Save this transaction to the journal ? [y]: -Saved. -Starting the next transaction (. or ctrl-D/ctrl-C to quit) -Date [2015/05/22]: $ - - -File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS - -4.4 balance -=========== - -Show accounts and their balances. Aliases: b, bal. - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports) -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date) -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'-O FMT --output-format=FMT' - - select the output format. Supported formats: txt, csv, html. -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. -'--pretty-tables' - - use unicode to display prettier tables. -'--sort-amount' - - sort by amount instead of account code/name (in flat mode). With - multiple columns, sorts by the row total, or by row average if that - is displayed. -'--invert' - - display all amounts with reversed sign -'--budget' - - show performance compared to budget goals defined by periodic - transactions -'--show-unbudgeted' - - with -budget, show unbudgeted accounts also - - The balance command is hledger's most versatile command. Note, -despite the name, it is not always used for showing real-world account -balances; the more accounting-aware balancesheet and incomestatement may -be more convenient for that. - - By default, it displays all accounts, and each account's change in -balance during the entire period of the journal. Balance changes are -calculated by adding up the postings in each account. You can limit the -postings matched, by a query, to see fewer accounts, changes over a -different time period, changes from only cleared transactions, etc. - - If you include an account's complete history of postings in the -report, the balance change is equivalent to the account's current ending -balance. For a real-world account, typically you won't have all -transactions in the journal; instead you'll have all transactions after -a certain date, and an "opening balances" transaction setting the -correct starting balance on that date. Then the balance command will -show real-world account balances. In some cases the -H/-historical flag -is used to ensure this (more below). - - The balance command can produce several styles of report: -* Menu: - -* Classic balance report:: -* Customising the classic balance report:: -* Colour support:: -* Flat mode:: -* Depth limited balance reports:: -* Multicolumn balance report:: -* Budget report:: -* Output format:: - - -File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance - -4.4.1 Classic balance report ----------------------------- - -This is the original balance report, as found in Ledger. It usually -looks like this: - -$ 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 - - By default, accounts are displayed hierarchically, with subaccounts -indented below their parent. At each level of the tree, accounts are -sorted by account code if any, then by account name. Or with -'-S/--sort-amount', by their balance amount. - - "Boring" accounts, which contain a single interesting subaccount and -no balance of their own, are elided into the following line for more -compact output. (Eg above, the "liabilities" account.) Use -'--no-elide' to prevent this. - - Account balances are "inclusive" - they include the balances of any -subaccounts. - - Accounts which have zero balance (and no non-zero subaccounts) are -omitted. Use '-E/--empty' to show them. - - A final total is displayed by default; use '-N/--no-total' to -suppress it, eg: - -$ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies - - -File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance - -4.4.2 Customising the classic balance report --------------------------------------------- - -You can customise the layout of classic balance reports with '--format -FMT': - -$ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 - - The FMT format string (plus a newline) specifies the formatting -applied to each account/balance pair. It may contain any suitable text, -with data fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - * MAX truncates at this width (optional) - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance - -4.4.3 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: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance - -4.4.4 Flat mode ---------------- - -To see a flat list instead of the default hierarchical display, use -'--flat'. In this mode, accounts (unless depth-clipped) show their full -names and "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 report, Prev: Flat mode, Up: balance - -4.4.5 Depth limited balance reports ------------------------------------ - -With '--depth N' or 'depth:N' or just '-N', balance reports show -accounts only to the specified numeric depth. This is very useful to -summarise a complex set of accounts and get an overview. - -$ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Flat-mode balance reports, which normally show exclusive balances, -show inclusive balances at the depth limit. - - -File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance - -4.4.6 Multicolumn balance report --------------------------------- - -Multicolumn or tabular balance reports are a very useful hledger -feature, and usually the preferred style. They share many of the above -features, but they show the report as a table, with columns representing -time periods. This mode is activated by providing a reporting interval. - - There are three types of multicolumn 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 - - Multicolumn 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 - - Limitations: - - In multicolumn reports the '-V/--value' flag uses the market price on -the report end date, for all columns (not the price on each column's end -date). - - Eliding of boring parent accounts in tree mode, as in the classic -balance report, is not yet supported in multicolumn reports. - - -File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance - -4.4.7 Budget report -------------------- - -With '--budget', extra columns are displayed showing budget goals for -each account and period, if any. Budget goals are defined by periodic -transactions. This is very useful for comparing planned and actual -income, expenses, time usage, etc. -budget is most often combined with -a report interval. - - 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 report: - -$ hledger balance -M --budget -Budget performance in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 -======================++================================================= - || $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 - - By default, only accounts with budget goals during the report period -are shown. '--show-unbudgeted' shows unbudgeted accounts as well. -Top-level accounts with no budget goals anywhere below them are grouped -under ''. - - You can roll over unspent budgets to next period with '--cumulative': - -$ hledger balance -M --budget --cumulative -Budget performance in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 -======================++================================================= - || $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 - - Note, the '-S/--sort-amount' flag is not yet fully supported with -'--budget'. - - For more examples, see Budgeting and Forecasting. - -4.4.8 Output format -------------------- - -The balance command supports output destination and output format -selection. - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS - -4.5 balancesheet -================ - -This command displays a simple balance sheet, showing historical ending -balances of asset and liability accounts (ignoring any report begin -date). It assumes that these accounts are under a top-level 'asset' or -'liability' account (case insensitive, plural forms also allowed). Note -this report shows all account balances with normal positive sign (like -conventional financial statements, unlike balance/print/register) -(experimental). (bs) - -'--change' - - show balance change in each period, instead of historical ending - balances -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of historical ending balances -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date) (default) -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'--sort-amount' - - sort by amount instead of account code/name - - Example: - -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for -each report period. As with multicolumn balance reports, you can alter -the report mode with '--change'/'--cumulative'/'--historical'. Normally -balancesheet shows historical ending balances, which is what you need -for a balance sheet; note this means it ignores report begin dates. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS - -4.6 balancesheetequity -====================== - -Just like balancesheet, but also reports Equity (which it assumes is -under a top-level 'equity' account). - - Example: - -$ hledger balancesheetequity -Balance Sheet With Equity - -Assets: - $-2 assets - $1 bank:saving - $-3 cash --------------------- - $-2 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Equity: - $1 equity:owner --------------------- - $1 - -Total: --------------------- - 0 - - -File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS - -4.7 cashflow -============ - -This command displays a simple cashflow statement, showing changes in -"cash" accounts. It assumes that these accounts are under a top-level -'asset' account (case insensitive, plural forms also allowed) and do not -contain 'receivable' or 'A/R' in their name. Note this report shows all -account balances with normal positive sign (like conventional financial -statements, unlike balance/print/register) (experimental). (cf) - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row (in simple reports) -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'--sort-amount' - - sort by amount instead of account code/name - - Example: - -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 - - With a reporting interval, multiple columns will be shown, one for -each report period. Normally cashflow shows changes in assets per -period, though as with multicolumn balance reports you can alter the -report mode with '--change'/'--cumulative'/'--historical'. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS - -4.8 check-dates -=============== - -Check that transactions are sorted by increasing date. With a query, -only matched transactions' dates are checked. - - -File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS - -4.9 check-dupes -=============== - -Report account names having the same leaf but different prefixes. An -example: http://stefanorodighiero.net/software/hledger-dupes.html - - -File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS - -4.10 close -========== - -Print closing/opening transactions that bring some or all account -balances to zero and back. Can be useful for bringing asset/liability -balances across file boundaries, or for closing out income/expenses for -a period. This was formerly called "equity", as in Ledger, and that -alias is also accepted. See close -help for more. - - -File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS - -4.11 files -========== - -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - - -File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS - -4.12 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.13 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.14 incomestatement -==================== - -This command displays a simple income statement, showing revenues and -expenses during a period. It assumes that these accounts are under a -top-level 'revenue' or 'income' or 'expense' account (case insensitive, -plural forms also allowed). Note this report shows all account balances -with normal positive sign (like conventional financial statements, -unlike balance/print/register) (experimental). (is) - -'--change' - - show balance change in each period (default) -'--cumulative' - - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods -'-H --historical' - - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period -'--tree' - - show accounts as a tree; amounts include subaccounts (default in - simple reports) -'--flat' - - show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) -'-A --average' - - show a row average column (in multicolumn mode) -'-T --row-total' - - show a row total column (in multicolumn mode) -'-N --no-total' - - don't show the final total row -'--drop=N' - - omit N leading account name parts (in flat mode) -'--no-elide' - - don't squash boring parent accounts (in tree mode) -'--format=LINEFORMAT' - - in single-column balance reports: use this custom line format -'--sort-amount' - - sort by amount instead of account code/name - - This command displays a simple income statement. It currently -assumes that you have top-level accounts named 'income' (or 'revenue') -and 'expense' (plural forms also allowed.) - -$ hledger incomestatement -Income Statement - -Revenues: - $-2 income - $-1 gifts - $-1 salary --------------------- - $-2 - -Expenses: - $2 expenses - $1 food - $1 supplies --------------------- - $2 - -Total: --------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for -each report period. Normally incomestatement shows revenues/expenses -per period, though as with multicolumn balance reports you can alter the -report mode with '--change'/'--cumulative'/'--historical'. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS - -4.15 prices -=========== - -Print market price directives from the journal. With -costs, also print -synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction prices. -Prices (and postings providing prices) can be filtered by a query. - - -File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS - -4.16 print -========== - -Show transactions from the journal. Aliases: p, txns. - -'-m STR --match=STR' - - show the transaction whose description is most similar to STR, and - is most recent -'--new' - - show only newer-dated transactions added in each file since last - run -'-x --explicit' - - show all amounts explicitly -'-O FMT --output-format=FMT' - - select the output format. Supported formats: txt, csv. -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. - -$ hledger print -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - -2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - -2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - -2008/12/31 * pay off - liabilities:debts $1 - assets:bank:checking $-1 - - The print command displays full journal entries (transactions) from -the journal file in date order, tidily formatted. print's output is -always a valid hledger journal. It preserves all transaction -information, but it does not preserve directives or inter-transaction -comments - - Normally, the journal entry's explicit or implicit amount style is -preserved. Ie when an amount is omitted in the journal, it will be -omitted in the output. You can use the '-x'/'--explicit' flag to make -all amounts explicit, which can be useful for troubleshooting or for -making your journal more readable and robust against data entry errors. -Note, '-x' will cause postings with a multi-commodity amount (these can -arise when a multi-commodity transaction has an implicit amount) will be -split into multiple single-commodity postings, for valid journal output. - - With '-B'/'--cost', amounts with transaction prices are converted to -cost using that price. This can be used for troubleshooting. - - With '-m'/'--match' and a STR argument, print will show at most one -transaction: the one one whose description is most similar to STR, and -is most recent. STR should contain at least two characters. If there -is no similar-enough match, no transaction will be shown. - - With '--new', for each FILE being read, hledger reads (and writes) a -special state file ('.latest.FILE' in the same directory), containing -the latest transaction date(s) that were seen last time FILE was read. -When this file is found, only transactions with newer dates (and new -transactions on the latest date) are printed. This is useful for -ignoring already-seen entries in import data, such as downloaded CSV -files. Eg: - -$ hledger -f bank1.csv print --new -# shows transactions added since last print --new on this file - - This assumes that transactions added to FILE always have same or -increasing dates, and that transactions on the same day do not get -reordered. See also the import command. - - This command also supports output destination and output format -selection. Here's an example of print's CSV output: - -$ hledger print -Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" -"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" -"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - * There is one CSV record per posting, with the parent transaction's - fields repeated. - * The "txnidx" (transaction index) field shows which postings belong - to the same transaction. (This number might change if transactions - are reordered within the file, files are parsed/included in a - different order, etc.) - * The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - * The numeric amount is repeated in either the "credit" or "debit" - column, for convenience. (Those names are not accurate in the - accounting sense; it just puts negative amounts under credit and - zero or greater amounts under debit.) - - -File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS - -4.17 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.18 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.18.1 Custom register output ------------------------------ - -register uses the full terminal width by default, except on windows. -You can override this by setting the 'COLUMNS' environment variable (not -a bash shell variable) or by using the '--width'/'-w' option. - - The description and account columns normally share the space equally -(about half of (width - 40) each). You can adjust this by adding a -description width as part of -width's argument, comma-separated: -'--width W,D' . Here's a diagram: - -<--------------------------------- width (W) ----------------------------------> -date (10) description (D) account (W-41-D) amount (12) balance (12) -DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - and some examples: - -$ hledger reg # use terminal width (or 80 on windows) -$ hledger reg -w 100 # use width 100 -$ COLUMNS=100 hledger reg # set with one-time environment variable -$ export COLUMNS=100; hledger reg # set till session end (or window resize) -$ hledger reg -w 100,40 # set overall width 100, description width 40 -$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS - -4.19 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: roi, Prev: register-match, Up: COMMANDS - -4.20 rewrite -============ - -Print all transactions, adding custom postings to the matched ones. - - -File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS - -4.21 roi -======== - -Shows time-weighted (TWR) and money-weighted (IRR) rate of return on -your investments. See 'roi --help' for more. - - -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS - -4.22 stats -========== - -Show some journal statistics. - -'-o FILE --output-file=FILE' - - write output to FILE. A file extension matching one of the above - formats selects that format. - -$ hledger stats -Main journal file : /src/hledger/examples/sample.journal -Included journal files : -Transactions span : 2008-01-01 to 2009-01-01 (366 days) -Last transaction : 2008-12-31 (2333 days ago) -Transactions : 5 (0.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 5 -Accounts : 8 (depth 3) -Commodities : 1 ($) - - The stats command displays summary information for the whole journal, -or a matched part of it. With a reporting interval, it shows a report -for each report period. - - This command also supports output destination and output format -selection. - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS - -4.23 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.24 test -========= - -Run built-in unit tests. - - Prints test names and their results on stdout. If any test fails or -gives an error, the exit code will be non-zero. - - Test names include a group prefix. If a (exact, case sensitive) -group prefix, or a full test name is provided as the first argument, -only that group or test is run. - - If a numeric second argument is provided, it will set the randomness -seed, for repeatable results from tests using randomness (currently none -of them). - - This is mainly used by developers, but it's nice to be able to -sanity-check your installed hledger executable at any time. All tests -are expected to pass - if you ever see otherwise, something has gone -wrong, please report a bug! - - -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, but it's superseded now by the built-in roi command. - - -File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS - -5.3 Experimental add-ons -======================== - -These are available in source form in the hledger repo's bin/ directory; -installing them is pretty easy. They may be less mature and documented -than built-in commands. Reading and tweaking these is a good way to -start making your own! -* Menu: - -* autosync:: -* chart:: -* check:: - - -File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons - -5.3.1 autosync --------------- - -hledger-autosync is a symbolic link for easily running ledger-autosync, -if installed. ledger-autosync does deduplicating conversion of OFX data -and some CSV formats, and can also download the data if your bank offers -OFX Direct Connect. - - -File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons - -5.3.2 chart ------------ - -hledger-chart.hs is an old pie chart generator, in need of some love. - - -File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons - -5.3.3 check ------------ - -hledger-check.hs checks more powerful account balance assertions. - - -Tag Table: -Node: Top68 -Node: EXAMPLES1884 -Ref: #examples1984 -Node: OPTIONS3630 -Ref: #options3732 -Node: General options4167 -Ref: #general-options4292 -Node: Command options6974 -Ref: #command-options7125 -Node: Command arguments7523 -Ref: #command-arguments7677 -Node: Argument files7798 -Ref: #argument-files7974 -Node: Special characters in arguments and queries8240 -Ref: #special-characters-in-arguments-and-queries8474 -Node: More escaping8924 -Ref: #more-escaping9086 -Node: Even more escaping9382 -Ref: #even-more-escaping9576 -Node: Less escaping10247 -Ref: #less-escaping10409 -Node: Command line tips10654 -Ref: #command-line-tips10840 -Node: Unicode characters11217 -Ref: #unicode-characters11373 -Node: Input files12098 -Ref: #input-files12234 -Node: Smart dates14204 -Ref: #smart-dates14345 -Node: Report start & end date15751 -Ref: #report-start-end-date15923 -Node: Report intervals16988 -Ref: #report-intervals17153 -Node: Period expressions17554 -Ref: #period-expressions17714 -Node: Depth limiting21671 -Ref: #depth-limiting21815 -Node: Pivoting22157 -Ref: #pivoting22275 -Node: Cost23951 -Ref: #cost24059 -Node: Market value24177 -Ref: #market-value24312 -Node: Combining -B and -V25678 -Ref: #combining--b-and--v25841 -Node: Output destination25988 -Ref: #output-destination26150 -Node: Output format26433 -Ref: #output-format26585 -Node: Regular expressions26970 -Ref: #regular-expressions27107 -Node: QUERIES28468 -Ref: #queries28570 -Node: COMMANDS32532 -Ref: #commands32644 -Node: accounts33644 -Ref: #accounts33742 -Node: activity34988 -Ref: #activity35098 -Node: add35458 -Ref: #add35557 -Node: balance38218 -Ref: #balance38329 -Node: Classic balance report41412 -Ref: #classic-balance-report41585 -Node: Customising the classic balance report42954 -Ref: #customising-the-classic-balance-report43182 -Node: Colour support45256 -Ref: #colour-support45423 -Node: Flat mode45596 -Ref: #flat-mode45744 -Node: Depth limited balance reports46157 -Ref: #depth-limited-balance-reports46357 -Node: Multicolumn balance report46813 -Ref: #multicolumn-balance-report47011 -Node: Budget report52191 -Ref: #budget-report52334 -Ref: #output-format-155368 -Node: balancesheet55446 -Ref: #balancesheet55582 -Node: balancesheetequity57893 -Ref: #balancesheetequity58042 -Node: cashflow58579 -Ref: #cashflow58707 -Node: check-dates60830 -Ref: #check-dates60957 -Node: check-dupes61074 -Ref: #check-dupes61198 -Node: close61335 -Ref: #close61443 -Node: files61773 -Ref: #files61874 -Node: help62015 -Ref: #help62115 -Node: import63189 -Ref: #import63303 -Node: incomestatement64033 -Ref: #incomestatement64167 -Node: prices66571 -Ref: #prices66686 -Node: print66958 -Ref: #print67068 -Node: print-unique71962 -Ref: #print-unique72088 -Node: register72156 -Ref: #register72283 -Node: Custom register output76784 -Ref: #custom-register-output76913 -Node: register-match78143 -Ref: #register-match78277 -Node: rewrite78460 -Ref: #rewrite78575 -Node: roi78644 -Ref: #roi78742 -Node: stats78858 -Ref: #stats78957 -Node: tags79827 -Ref: #tags79925 -Node: test80161 -Ref: #test80245 -Node: ADD-ON COMMANDS80953 -Ref: #add-on-commands81063 -Node: Official add-ons82350 -Ref: #official-add-ons82490 -Node: api82577 -Ref: #api82666 -Node: ui82718 -Ref: #ui82817 -Node: web82875 -Ref: #web82964 -Node: Third party add-ons83010 -Ref: #third-party-add-ons83185 -Node: diff83320 -Ref: #diff83417 -Node: iadd83516 -Ref: #iadd83630 -Node: interest83713 -Ref: #interest83834 -Node: irr83929 -Ref: #irr84027 -Node: Experimental add-ons84158 -Ref: #experimental-add-ons84310 -Node: autosync84590 -Ref: #autosync84701 -Node: chart84940 -Ref: #chart85059 -Node: check85130 -Ref: #check85232 +hledger(1) hledger 1.13 +*********************** + +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 in arguments and queries:: +* Command line tips:: +* Unicode characters:: +* Input files:: +* Smart dates:: +* Report start & end date:: +* Report intervals:: +* Period expressions:: +* Depth limiting:: +* Pivoting:: +* Cost:: +* Market value:: +* Combining -B and -V:: +* Output destination:: +* Output format:: +* Regular expressions:: + + +File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS + +2.1 General options +=================== + +To see general usage help, including general options which are supported +by most hledger commands, run 'hledger -h'. + + General help options: + +'-h --help' + + show general usage (or after COMMAND, command usage) +'--version' + + show version +'--debug[=N]' + + show debug output (levels 1-9, default: 1) + + General input options: + +'-f FILE --file=FILE' + + use a different input file. For stdin, use - (default: + '$LEDGER_FILE' or '$HOME/.hledger.journal') +'--rules-file=RULESFILE' + + Conversion rules file to use when reading CSV (default: FILE.rules) +'--separator=CHAR' + + Field separator to expect when reading CSV (default: ',') +'--alias=OLD=NEW' + + rename accounts named OLD to NEW +'--anon' + + anonymize accounts and payees +'--pivot FIELDNAME' + + use some other field or tag for the account name +'-I --ignore-assertions' + + ignore any failing balance assertions + + General reporting options: + +'-b --begin=DATE' + + include postings/txns on or after this date +'-e --end=DATE' + + include postings/txns before this date +'-D --daily' + + multiperiod/multicolumn report by day +'-W --weekly' + + multiperiod/multicolumn report by week +'-M --monthly' + + multiperiod/multicolumn report by month +'-Q --quarterly' + + multiperiod/multicolumn report by quarter +'-Y --yearly' + + multiperiod/multicolumn report by year +'-p --period=PERIODEXP' + + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) +'--date2' + + match the secondary date instead (see command help for other + effects) +'-U --unmarked' + + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' + + include only pending postings/txns +'-C --cleared' + + include only cleared postings/txns +'-R --real' + + include only non-virtual postings +'-NUM --depth=NUM' + + hide/aggregate accounts or postings more than NUM levels deep +'-E --empty' + + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) +'-B --cost' + + convert amounts to their cost at transaction time (using the + transaction price, if any) +'-V --value' + + convert amounts to their market value on the report end date (using + the most recent applicable market price, if any) +'--auto' + + apply automated posting rules to modify transactions. +'--forecast' + + apply periodic transaction rules to generate future transactions, + to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, +the last one takes precedence. + + Some reporting options can also be written as query arguments. + + +File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS + +2.2 Command options +=================== + +To see options for a particular command, including command-specific +options, run: 'hledger COMMAND -h'. + + Command-specific options must be written after the command name, eg: +'hledger print -x'. + + Additionally, if the command is an addon, you may need to put its +options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can +run the addon executable directly: 'hledger-ui --watch'. + + +File: hledger.info, Node: Command arguments, Next: Argument files, Prev: Command options, Up: OPTIONS + +2.3 Command arguments +===================== + +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. + + +File: hledger.info, Node: Argument files, Next: Special characters in arguments and queries, 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 in arguments and queries, Next: Command line tips, Prev: Argument files, Up: OPTIONS + +2.5 Special characters in arguments and queries +=============================================== + +In shell command lines, option and argument values which contain +"problematic" characters, ie spaces, and also characters significant to +your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by +enclosing them in quotes or by writing backslashes before the +characters. Eg: + + 'hledger register -p 'last year' "accounts receivable +(receivable|payable)" amt:\>100'. +* Menu: + +* More escaping:: +* Even more escaping:: +* Less escaping:: + + +File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries + +2.5.1 More escaping +------------------- + +Characters significant both to the shell and in regular expressions may +need one extra level of escaping. 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:\\$' + + +File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries + +2.5.2 Even more escaping +------------------------ + +When hledger runs an addon executable (eg you type 'hledger ui', hledger +runs 'hledger-ui'), it de-escapes command-line options and arguments +once, so you might need to _triple_-escape. Eg in bash, running the ui +command and matching the dollar sign, it's: + + 'hledger ui cur:'\\$'' + + or: + + 'hledger ui cur:\\\\$' + + If you asked why _four_ slashes above, this may help: + +unescaped: '$' +escaped: '\$' +double-escaped: '\\$' +triple-escaped: '\\\\$' + + (The number of backslashes in fish shell is left as an exercise for +the reader.) + + You can always avoid the extra escaping for addons by running the +addon directly: + + 'hledger-ui cur:\\$' + + +File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries + +2.5.3 Less escaping +------------------- + +Inside an argument file, or in the search field of hledger-ui or +hledger-web, or at a GHCI prompt, you need one less level of escaping +than at the command line. And backslashes may work better than quotes. +Eg: + + 'ghci> :main balance cur:\$' + + +File: hledger.info, Node: Command line tips, Next: Unicode characters, Prev: Special characters in arguments and queries, Up: OPTIONS + +2.6 Command line tips +===================== + +If in doubt, keep things simple: + + * write options after the command ('hledger CMD -OPTIONS ARGS') + * run add-on executables directly ('hledger-ui -OPTIONS ARGS') + * enclose problematic args in single quotes + * if needed, also add a backslash to escape regexp metacharacters + + To find out exactly how a command line is being parsed, add +'--debug=2' to troubleshoot. + + +File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Command line tips, Up: OPTIONS + +2.7 Unicode characters +====================== + +hledger is expected to handle unicode (non-ascii) characters, but this +requires a well-configured environment. + + To handle unicode characters in the command line or input data, a +system locale that can decode them must be configured (POSIX's default +'C' locale will not work). Eg in bash, you could do: + +export LANG=en_US.UTF-8 + + See Troubleshooting for more about this. + + Unicode characters should appear correctly in hledger's output. For +the hledger and hledger-ui tools, this requires that + + * your terminal supports unicode + * the terminal's font includes the required unicode glyphs + * the terminal is configured to display "wide" characters as double + width (otherwise report alignment will be off) + + +File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS + +2.8 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.9 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: + +'2004/10/1', '2004-01-01', '2004.9.1' exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 +'2004' start of year +'2004/10' start of month +'10/1' month and day in current year +'21' day in current month +'october, oct' start of month in current year +'yesterday, today, tomorrow' -1, 0, 1 days from today +'last/this/next -1, 0, 1 periods from the current period +day/week/month/quarter/year' +'20181201' 8 digit YYYYMMDD with valid year month and day +'201812' 6 digit YYYYMM with valid year and month + + Counterexamples - malformed digit sequences might give surprising +results: + +'201813' 6 digits with an invalid month is parsed as start of 6-digit year +'20181301' 8 digits with an invalid month is parsed as start of 8-digit year +'20181232' 8 digits with an invalid day gives an error +'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error + + +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS + +2.10 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.11 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.12 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.13 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.14 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.15 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.16 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 -N euros + €100 assets:euros + + What are they worth at end of nov 3 ? + +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date +specified, defaults to today) + +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P +directives, not transaction prices (unlike Ledger). + + Currently, -V has a limitation in multicolumn balance reports: it +uses the market prices on the report end date for all columns. (Instead +of the prices on each column's end date.) + + +File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS + +2.17 Combining -B and -V +======================== + +Using -B/-cost and -V/-value together is currently allowed, but the +results are probably not meaningful. Let us know if you find a use for +this. + + +File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS + +2.18 Output destination +======================= + +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. This is +controlled by the '-o/--output-file' option. + +$ hledger balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE + + +File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS + +2.19 Output format +================== + +Some commands can write their output in other formats. Eg print and +register can output CSV, and the balance commands can output CSV or +HTML. This is controlled by the '-O/--output-format' option, or by +specifying a '.csv' or '.html' file extension with '-o/--output-file'. + +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv + + +File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS + +2.20 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', 'acct:REGEX'* + + match account names by this regular expression. (With no prefix, + 'acct:' is assumed.) same as above + +*'amt:N, amt:N, amt:>=N'* + + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not + tested, and will always match.) The comparison has two modes: if N + is preceded by a + or - sign (or is 0), the two signed numbers are + compared. Otherwise, the absolute magnitudes are compared, + ignoring sign. +*'code:REGEX'* + + match by transaction code (eg check number) +*'cur:REGEX'* + + match postings or transactions including any amounts whose + currency/commodity symbol is fully matched by REGEX. (For a partial + match, use '.*REGEX.*'). Note, to match characters which are + regex-significant, like the dollar sign ('$'), you need to prepend + '\'. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: 'hledger + print cur:'\$'' or 'hledger print cur:\\$'. +*'desc:REGEX'* + + match transaction descriptions. +*'date:PERIODEXPR'* + + match dates within the specified period. PERIODEXPR is a period + expression (with no report interval). Examples: 'date:2016', + 'date:thismonth', 'date:2000/2/1-2/15', 'date:lastweek-'. If the + '--date2' command line flag is present, this matches secondary + dates instead. +*'date2:PERIODEXPR'* + + match secondary dates within the specified period. +*'depth:N'* + + match (or display, depending on command) accounts at or above this + depth +*'note:REGEX'* + + match transaction notes (part of description right of '|', or whole + description when there's no '|') +*'payee:REGEX'* + + match transaction payee/payer names (part of description left of + '|', or whole description when there's no '|') +*'real:, real:0'* + + match real or virtual postings respectively +*'status:, status:!, status:*'* + + match unmarked, pending, or cleared transactions respectively +*'tag:REGEX[=REGEX]'* + + match by tag name, and optionally also by tag value. Note a tag: + query is considered to match a transaction if it matches any of the + postings. Also remember that postings inherit the tags of their + parent transaction. + + The following special search term is used automatically in +hledger-web, only: + +*'inacct:ACCTNAME'* + + tells hledger-web to show the transaction register for this + account. Can be filtered further with 'acct' etc. + + Some of these can also be expressed as command-line options (eg +'depth:2' is equivalent to '--depth 2'). Generally you can mix options +and query arguments, and the resulting query will be their intersection +(perhaps excluding the '-p/--period' option). + + +File: hledger.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top + +4 COMMANDS +********** + +hledger provides a number of subcommands; 'hledger' with no arguments +shows a list. + + If you install additional 'hledger-*' packages, or if you put +programs or scripts named 'hledger-NAME' in your PATH, these will also +be listed as subcommands. + + Run a subcommand by writing its name as first argument (eg 'hledger +incomestatement'). You can also write one of the standard short aliases +displayed in parentheses in the command list ('hledger b'), or any any +unambiguous prefix of a command name ('hledger inc'). + + Here are all the builtin commands in alphabetical order. See also +'hledger' for a more organised command list, and 'hledger CMD -h' for +detailed command help. +* Menu: + +* accounts:: +* activity:: +* add:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check-dates:: +* check-dupes:: +* close:: +* files:: +* help:: +* import:: +* incomestatement:: +* prices:: +* print:: +* print-unique:: +* register:: +* register-match:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS + +4.1 accounts +============ + +accounts, a +Show account names. + + This command lists account names, either declared with account +directives (-declared), posted to (-used), or both (the default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +'--tree', it uses indentation to show the account hierarchy. In flat +mode you can add '--drop N' to omit the first few account name +components. Account names can be depth-clipped with 'depth:N' or +'--depth N' or '-N'. + + Examples: + +$ 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 +============ + +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. + + Examples: + +$ 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 +======= + +add +Prompt for transactions and add them to the journal. + + 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 (by + description) recent transaction (filtered by the query, if any) 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 +=========== + +balance, bal, b +Show accounts and their balances. + + The balance command is hledger's most versatile command. Note, +despite the name, it is not always used for showing real-world account +balances; the more accounting-aware balancesheet and incomestatement may +be more convenient for that. + + By default, it displays all accounts, and each account's change in +balance during the entire period of the journal. Balance changes are +calculated by adding up the postings in each account. You can limit the +postings matched, by a query, to see fewer accounts, changes over a +different time period, changes from only cleared transactions, etc. + + If you include an account's complete history of postings in the +report, the balance change is equivalent to the account's current ending +balance. For a real-world account, typically you won't have all +transactions in the journal; instead you'll have all transactions after +a certain date, and an "opening balances" transaction setting the +correct starting balance on that date. Then the balance command will +show real-world account balances. In some cases the -H/-historical flag +is used to ensure this (more below). + + The balance command can produce several styles of report: +* Menu: + +* Classic balance report:: +* Customising the classic balance report:: +* Colour support:: +* Flat mode:: +* Depth limited balance reports:: +* Multicolumn balance report:: +* Budget report:: +* Output format:: + + +File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance + +4.4.1 Classic balance report +---------------------------- + +This is the original balance report, as found in Ledger. It usually +looks like this: + +$ 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 + + By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. At each level of the tree, accounts are +sorted by account code if any, then by account name. Or with +'-S/--sort-amount', by their balance amount. + + "Boring" accounts, which contain a single interesting subaccount and +no balance of their own, are elided into the following line for more +compact output. (Eg above, the "liabilities" account.) Use +'--no-elide' to prevent this. + + Account balances are "inclusive" - they include the balances of any +subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are +omitted. Use '-E/--empty' to show them. + + A final total is displayed by default; use '-N/--no-total' to +suppress it, eg: + +$ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + + +File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance + +4.4.2 Customising the classic balance report +-------------------------------------------- + +You can customise the layout of classic balance reports with '--format +FMT': + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + * MAX truncates at this width (optional) + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance + +4.4.3 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: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance + +4.4.4 Flat mode +--------------- + +To see a flat list instead of the default hierarchical display, use +'--flat'. In this mode, accounts (unless depth-clipped) show their full +names and "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 report, Prev: Flat mode, Up: balance + +4.4.5 Depth limited balance reports +----------------------------------- + +With '--depth N' or 'depth:N' or just '-N', balance reports show +accounts only to the specified numeric depth. This is very useful to +summarise a complex set of accounts and get an overview. + +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Flat-mode balance reports, which normally show exclusive balances, +show inclusive balances at the depth limit. + + +File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance + +4.4.6 Multicolumn balance report +-------------------------------- + +Multicolumn or tabular balance reports are a very useful hledger +feature, and usually the preferred style. They share many of the above +features, but they show the report as a table, with columns representing +time periods. This mode is activated by providing a reporting interval. + + There are three types of multicolumn 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 + + Multicolumn 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). With '--budget', '--empty' also shows unbudgeted +accounts. + + 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 + + Limitations: + + In multicolumn reports the '-V/--value' flag uses the market price on +the report end date, for all columns (not the price on each column's end +date). + + Eliding of boring parent accounts in tree mode, as in the classic +balance report, is not yet supported in multicolumn reports. + + +File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance + +4.4.7 Budget report +------------------- + +With '--budget', extra columns are displayed showing budget goals for +each account and period, if any. Budget goals are defined by periodic +transactions. This is very useful for comparing planned and actual +income, expenses, time usage, etc. -budget is most often combined with +a report interval. + + 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 report: + +$ hledger balance -M --budget +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + By default, only accounts with budget goals during the report period +are shown. In the example above, transactions in 'expenses:gifts' and +'expenses:supplies' are counted towards 'expenses' budget, but accounts +'expenses:gifts' and 'expenses:supplies' are not shown, as they don't +have any budgets. + + You can use '--empty' shows unbudgeted accounts as well: + +$ hledger balance -M --budget --empty +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with '--cumulative': + +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + Note, the '-S/--sort-amount' flag is not yet fully supported with +'--budget'. + + For more examples, see Budgeting and Forecasting. +* Menu: + +* Nested budgets:: + + +File: hledger.info, Node: Nested budgets, Up: Budget report + +4.4.7.1 Nested budgets +...................... + +You can add budgets to any account in your account hierarchy. If you +have budgets on both parent account and some of its children, then +budget(s) of the child account(s) would be added to the budget of their +parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both 'expenses:personal' and 'expenses' is $1100. + + Transactions in 'expenses:personal:electronics' will be counted both +towards its $100 budget and $1100 of 'expenses:personal' , and +transactions in any other subaccount of 'expenses:personal' would be +counted towards only towards the budget of 'expenses:personal'. + + For example, let's consider these transactions: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + +2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + +2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + +2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in +'expenses:personal:electronics:upgrades' and 'expenses:personal:train +tickets', and since both of these accounts are without explicitly +defined budget, these transactions would be counted towards budgets of +'expenses:personal:electronics' and 'expenses:personal' accordingly: + +$ hledger balance --budget -M +Budget performance in 2019/01: + + || Jan +===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++------------------------------- + || 0 [ 0] + + And with '--empty', we can get a better picture of budget allocation +and consumption: + +$ hledger balance --budget -M --empty +Budget performance in 2019/01: + + || Jan +========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++------------------------------- + || 0 [ 0] + +4.4.8 Output format +------------------- + +The balance command supports output destination and output format +selection. + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS + +4.5 balancesheet +================ + +balancesheet, bs +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). It assumes that these accounts are under a top-level 'asset' or +'liability' account (case insensitive, plural forms also allowed). + + Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for +each report period. As with multicolumn balance reports, you can alter +the report mode with '--change'/'--cumulative'/'--historical'. Normally +balancesheet shows historical ending balances, which is what you need +for a balance sheet; note this means it ignores report begin dates. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS + +4.6 balancesheetequity +====================== + +balancesheetequity, bse +Just like balancesheet, but also reports Equity (which it assumes is +under a top-level 'equity' account). + + Example: + +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 + + +File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS + +4.7 cashflow +============ + +cashflow, cf +This command displays a simple cashflow statement, showing changes in +"cash" accounts. It assumes that these accounts are under a top-level +'asset' account (case insensitive, plural forms also allowed) and do not +contain 'receivable' or 'A/R' in their name. Note this report shows all +account balances with normal positive sign (like conventional financial +statements, unlike balance/print/register) (experimental). + + Example: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + With a reporting interval, multiple columns will be shown, one for +each report period. Normally cashflow shows changes in assets per +period, though as with multicolumn balance reports you can alter the +report mode with '--change'/'--cumulative'/'--historical'. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS + +4.8 check-dates +=============== + +check-dates +Check that transactions are sorted by increasing date. With -date2, +checks secondary dates instead. With -strict, dates must also be +unique. With a query, only matched transactions' dates are checked. +Reads the default journal file, or another specified with -f. + + +File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS + +4.9 check-dupes +=============== + +check-dupes +Reports account names having the same leaf but different prefixes. In +other words, two or more leaves that are categorized differently. Reads +the default journal file, or another specified as an argument. + + An example: http://stefanorodighiero.net/software/hledger-dupes.html + + +File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS + +4.10 close +========== + +close, equity +Prints a "closing balances" transaction and an "opening balances" +transaction that bring account balances to and from zero, respectively. +Useful for bringing asset/liability balances forward into a new journal +file, or for closing out revenues/expenses to retained earnings at the +end of a period. + + The closing transaction transfers balances to "equity:closing +balances". The opening transaction transfers balances from +"equity:opening balances". You can chose to print just one of the +transactions by using the '--opening' or '--closing' flag. + + If you split your journal files by time (eg yearly), you will +typically run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. This makes the files self +contained, so that correct balances are reported no matter which of them +are loaded. Ie, if you load just one file, the balances are initialised +correctly; or if you load several files, the redundant closing/opening +transactions cancel each other out. (They will show up in print or +register reports; you can exclude them with a query like +'not:desc:'(opening|closing) balances''.) + + If you're running a business, you might also use this command to +"close the books" at the end of an accounting period, transferring +income statement account balances to retained earnings. (You may want +to change the equity account name to something like "equity:retained +earnings".) + + By default, the closing transaction is dated yesterday, the balances +are calculated as of end of yesterday, and the opening transaction is +dated today. To close on some other date, use: 'hledger close -e +OPENINGDATE'. Eg, to close/open on the 2018/2019 boundary, use '-e +2019'. You can also use -p or 'date:PERIOD' (any starting date is +ignored). + + Both transactions will include balance assertions for the +closed/reopened accounts. You probably shouldn't use status or realness +filters (like -C or -R or 'status:') with this command, or the generated +balance assertions will depend on these flags. Likewise, if you run +this command with -auto, the balance assertions will probably always +require -auto. + + Examples: + + Carrying asset/liability balances into a new file for 2019, all from +command line: + + _Warning: we use '>>' here to append; be careful not to type a single +'>' which would wipe your journal!_ + +$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + + Now: + +$ hledger bs -f 2019.journal # one file - balances are correct +$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct +$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + + Transactions spanning the closing date can complicate matters, +breaking balance assertions: + +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + + Here's one way to resolve that: + +; in 2018.journal: +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + +; in 2019.journal: +2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking + + +File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS + +4.11 files +========== + +files +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + + +File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS + +4.12 help +========= + +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. + + Examples: + +$ 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.13 import +=========== + +import +Read new transactions added to each FILE since last run, and add them to +the main journal file. Or with -dry-run, just print the transactions +that would be added. + + 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.14 incomestatement +==================== + +incomestatement, is +This command displays a simple income statement, showing revenues and +expenses during a period. It assumes that these accounts are under a +top-level 'revenue' or 'income' or 'expense' account (case insensitive, +plural forms also allowed). Note this report shows all account balances +with normal positive sign (like conventional financial statements, +unlike balance/print/register) (experimental). + + This command displays a simple income statement. It currently +assumes that you have top-level accounts named 'income' (or 'revenue') +and 'expense' (plural forms also allowed.) + +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for +each report period. Normally incomestatement shows revenues/expenses +per period, though as with multicolumn balance reports you can alter the +report mode with '--change'/'--cumulative'/'--historical'. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS + +4.15 prices +=========== + +prices +Print market price directives from the journal. With -costs, also print +synthetic market prices based on transaction prices. With +-inverted-costs, also print inverse prices based on transaction prices. +Prices (and postings providing prices) can be filtered by a query. + + +File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS + +4.16 print +========== + +print, txns, p +Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from +the journal file in date order, tidily formatted. With -date2, +transactions are sorted by secondary date instead. + + print's output is always a valid hledger journal. +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments + +$ 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 + + Normally, the journal entry's explicit or implicit amount style is +preserved. Ie when an amount is omitted in the journal, it will be +omitted in the output. You can use the '-x'/'--explicit' flag to make +all amounts explicit, which can be useful for troubleshooting or for +making your journal more readable and robust against data entry errors. +Note, '-x' will cause postings with a multi-commodity amount (these can +arise when a multi-commodity transaction has an implicit amount) will be +split into multiple single-commodity postings, for valid journal output. + + With '-B'/'--cost', amounts with transaction prices are converted to +cost using that price. This can be used for troubleshooting. + + With '-m'/'--match' and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there +is no similar-enough match, no transaction will be shown. + + With '--new', for each FILE being read, hledger reads (and writes) a +special state file ('.latest.FILE' in the same directory), containing +the latest transaction date(s) that were seen last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. This is useful for +ignoring already-seen entries in import data, such as downloaded CSV +files. Eg: + +$ hledger -f bank1.csv print --new +# shows transactions added since last print --new on this file + + This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. See also the import command. + + This command also supports output destination and output format +selection. Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS + +4.17 print-unique +================= + +print-unique +Print transactions which do not reuse an already-seen description. + + Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 + + +File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS + +4.18 register +============= + +register, reg, r +Show postings and their running total. + + The register command displays postings in date order, 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 + + With -date2, it shows and sorts by secondary date instead. + + 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.18.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 (won't display correctly in -help): + +<--------------------------------- 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, & description width 40 + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS + +4.19 register-match +=================== + +register-match +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. If there are multiple equally +good matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS + +4.20 rewrite +============ + +rewrite +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: + + +File: hledger.info, Node: Re-write rules in a file, Up: rewrite + +4.20.1 Re-write rules in a file +------------------------------- + +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. I.e instead of specifying this +operations in command line you can put them in a journal file. + +$ rewrite-rules.journal + + Make contents look like this: + += ^income + (liabilities:tax) *.33 + += expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that ''='' (equality symbol) that is used instead of date in +transactions you usually write. It indicates the query by which you +want to match the posting to add new ones. + +$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + +$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in +journal is important. You can re-use result of previously added +postings. + +* Menu: + +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file + +4.20.1.1 Diff output format +........................... + +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. + +$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + +--- /tmp/examples/sample.journal ++++ /tmp/examples/sample.journal +@@ -18,3 +18,4 @@ + 2008/01/01 income +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:salary ++ (liabilities:tax) 0 +@@ -22,3 +23,4 @@ + 2008/06/01 gift +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:gifts ++ (liabilities:tax) 0 + + If you'll pass this through 'patch' tool you'll get transactions +containing the posting that matches your query be updated. Note that +multiple files might be update according to list of input files +specified via '--file' options and 'include' directives inside of these +files. + + Be careful. Whole transaction being re-formatted in a style of +output from 'hledger print'. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + +File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file + +4.20.1.2 rewrite vs. print -auto +................................ + +This command predates print -auto, and currently does much the same +thing, but with these differences: + + * with multiple files, rewrite lets rules in any file affect all + other files. print -auto uses standard directive scoping; rules + affect only child files. + + * rewrite's query limits which transactions can be rewritten; all are + printed. print -auto's query limits which transactions are + printed. + + * rewrite applies rules specified on command line or in the journal. + print -auto applies rules specified in the journal. + + +File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS + +4.21 roi +======== + +roi +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + + This command assumes that you have account(s) that hold nothing but +your investments and whenever you record current appraisal/valuation of +these investments you offset unrealized profit and loss into account(s) +that, again, hold nothing but unrealized profit and loss. + + Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to be +your investments or withdrawals. + + At a minimum, you need to supply a query (which could be just an +account name) to select your investments with '--inv', and another query +to identify your profit and loss transactions with '--pnl'. + + It will compute and display the internalized rate of return (IRR) and +time-weighted rate of return (TWR) for your investments for the time +period requested. Both rates of return are annualized before display, +regardless of the length of reporting interval. + + +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS + +4.22 stats +========== + +stats +Show some journal statistics. + + 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. + + Example: + +$ 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 ($) + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS + +4.23 tags +========= + +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 QUERY arguments, only transactions matching the query are +considered. + + +File: hledger.info, Node: test, Prev: tags, Up: COMMANDS + +4.24 test +========= + +test +Run built-in unit tests. + + This command runs the unit tests built in to hledger-lib and hledger, +printing test names and results on stdout. If any test fails, the exit +code will be non-zero. + + Test names include a group prefix. If a (exact, case sensitive) +group prefix, or a full test name is provided as the first argument, +only that group or test is run. + + If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). + + This is mainly used by developers, but it's nice to be able to +sanity-check your installed hledger executable at any time. All tests +are expected to pass - if you ever see otherwise, something has gone +wrong, please report a bug! + + +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, but it's superseded now by the built-in roi command. + + +File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS + +5.3 Experimental add-ons +======================== + +These are available in source form in the hledger repo's bin/ directory; +installing them is pretty easy. They may be less mature and documented +than built-in commands. Reading and tweaking these is a good way to +start making your own! +* Menu: + +* autosync:: +* chart:: +* check:: + + +File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons + +5.3.1 autosync +-------------- + +hledger-autosync is a symbolic link for easily running ledger-autosync, +if installed. ledger-autosync does deduplicating conversion of OFX data +and some CSV formats, and can also download the data if your bank offers +OFX Direct Connect. + + +File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons + +5.3.2 chart +----------- + +hledger-chart.hs is an old pie chart generator, in need of some love. + + +File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons + +5.3.3 check +----------- + +hledger-check.hs checks more powerful account balance assertions. + + +Tag Table: +Node: Top68 +Node: EXAMPLES1884 +Ref: #examples1984 +Node: OPTIONS3630 +Ref: #options3732 +Node: General options4167 +Ref: #general-options4292 +Node: Command options6974 +Ref: #command-options7125 +Node: Command arguments7523 +Ref: #command-arguments7677 +Node: Argument files7798 +Ref: #argument-files7974 +Node: Special characters in arguments and queries8240 +Ref: #special-characters-in-arguments-and-queries8474 +Node: More escaping8924 +Ref: #more-escaping9086 +Node: Even more escaping9382 +Ref: #even-more-escaping9576 +Node: Less escaping10247 +Ref: #less-escaping10409 +Node: Command line tips10654 +Ref: #command-line-tips10840 +Node: Unicode characters11217 +Ref: #unicode-characters11373 +Node: Input files12098 +Ref: #input-files12234 +Node: Smart dates14204 +Ref: #smart-dates14345 +Node: Report start & end date15751 +Ref: #report-start-end-date15923 +Node: Report intervals16989 +Ref: #report-intervals17154 +Node: Period expressions17555 +Ref: #period-expressions17715 +Node: Depth limiting21672 +Ref: #depth-limiting21816 +Node: Pivoting22158 +Ref: #pivoting22276 +Node: Cost23952 +Ref: #cost24060 +Node: Market value24178 +Ref: #market-value24313 +Node: Combining -B and -V25679 +Ref: #combining--b-and--v25842 +Node: Output destination25989 +Ref: #output-destination26151 +Node: Output format26434 +Ref: #output-format26586 +Node: Regular expressions26971 +Ref: #regular-expressions27108 +Node: QUERIES28469 +Ref: #queries28571 +Node: COMMANDS32533 +Ref: #commands32645 +Node: accounts33645 +Ref: #accounts33743 +Node: activity34442 +Ref: #activity34552 +Node: add34935 +Ref: #add35034 +Node: balance37621 +Ref: #balance37732 +Node: Classic balance report39173 +Ref: #classic-balance-report39346 +Node: Customising the classic balance report40715 +Ref: #customising-the-classic-balance-report40943 +Node: Colour support43017 +Ref: #colour-support43184 +Node: Flat mode43357 +Ref: #flat-mode43505 +Node: Depth limited balance reports43918 +Ref: #depth-limited-balance-reports44118 +Node: Multicolumn balance report44574 +Ref: #multicolumn-balance-report44772 +Node: Budget report50012 +Ref: #budget-report50155 +Node: Nested budgets54839 +Ref: #nested-budgets54951 +Ref: #output-format-158431 +Node: balancesheet58509 +Ref: #balancesheet58645 +Node: balancesheetequity59879 +Ref: #balancesheetequity60028 +Node: cashflow60589 +Ref: #cashflow60717 +Node: check-dates61745 +Ref: #check-dates61872 +Node: check-dupes62151 +Ref: #check-dupes62275 +Node: close62568 +Ref: #close62676 +Node: files66089 +Ref: #files66190 +Node: help66337 +Ref: #help66437 +Node: import67530 +Ref: #import67644 +Node: incomestatement68388 +Ref: #incomestatement68522 +Node: prices69858 +Ref: #prices69973 +Node: print70252 +Ref: #print70362 +Node: print-unique74855 +Ref: #print-unique74981 +Node: register75266 +Ref: #register75393 +Node: Custom register output79262 +Ref: #custom-register-output79391 +Node: register-match80653 +Ref: #register-match80787 +Node: rewrite81138 +Ref: #rewrite81253 +Node: Re-write rules in a file83102 +Ref: #re-write-rules-in-a-file83236 +Node: Diff output format84446 +Ref: #diff-output-format84615 +Node: rewrite vs print --auto85707 +Ref: #rewrite-vs.-print---auto85886 +Node: roi86442 +Ref: #roi86540 +Node: stats87552 +Ref: #stats87651 +Node: tags88405 +Ref: #tags88503 +Node: test88733 +Ref: #test88817 +Node: ADD-ON COMMANDS89578 +Ref: #add-on-commands89688 +Node: Official add-ons90975 +Ref: #official-add-ons91115 +Node: api91202 +Ref: #api91291 +Node: ui91343 +Ref: #ui91442 +Node: web91500 +Ref: #web91589 +Node: Third party add-ons91635 +Ref: #third-party-add-ons91810 +Node: diff91945 +Ref: #diff92042 +Node: iadd92141 +Ref: #iadd92255 +Node: interest92338 +Ref: #interest92459 +Node: irr92554 +Ref: #irr92652 +Node: Experimental add-ons92783 +Ref: #experimental-add-ons92935 +Node: autosync93215 +Ref: #autosync93326 +Node: chart93565 +Ref: #chart93684 +Node: check93755 +Ref: #check93857  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -135,2155 +135,2269 @@ FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') - - --alias=OLD=NEW - rename accounts named OLD to NEW - - --anon anonymize accounts and payees - - --pivot FIELDNAME - use some other field or tag for the account name - - -I --ignore-assertions - ignore any failing balance assertions - - General reporting options: - - -b --begin=DATE - include postings/txns on or after this date - - -e --end=DATE - include postings/txns before this date - - -D --daily - multiperiod/multicolumn report by day - - -W --weekly - multiperiod/multicolumn report by week - - -M --monthly - multiperiod/multicolumn report by month - - -Q --quarterly - multiperiod/multicolumn report by quarter - - -Y --yearly - multiperiod/multicolumn report by year - - -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) - - --date2 - match the secondary date instead (see command help for other - effects) - - -U --unmarked - include only unmarked postings/txns (can combine with -P or -C) - - -P --pending - include only pending postings/txns - - -C --cleared - include only cleared postings/txns - - -R --real - include only non-virtual postings - - -NUM --depth=NUM - hide/aggregate accounts or postings more than NUM levels deep - - -E --empty - show items with zero amount, normally hidden (and vice-versa in - hledger-ui/hledger-web) - - -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) - - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) - - --auto apply automated posting rules to modify transactions. - - --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, the - last one takes precedence. - - Some reporting options can also be written as query arguments. - - Command options - To see options for a particular command, including command-specific - options, run: hledger COMMAND -h. - - Command-specific options must be written after the command name, eg: - hledger print -x. - - Additionally, if the command is an addon, you may need to put its - options after a double-hyphen, eg: hledger ui -- --watch. Or, you can - run the addon executable directly: hledger-ui --watch. - - Command arguments - Most hledger commands accept arguments after the command name, which - are often a query, filtering the data in some way. - - Argument files - You can save a set of command line options/arguments in a file, one per - line, and then reuse them by writing @FILENAME in a command line. To - prevent this expansion of @-arguments, precede them with a -- argument. - For more, see Save frequently used options. - - Special characters in arguments and queries - In shell command lines, option and argument values which contain "prob- - lematic" characters, ie spaces, and also characters significant to your - shell such as <, >, (, ), | and $, should be escaped by enclosing them - in quotes or by writing backslashes before the characters. Eg: - - hledger register -p 'last year' "accounts receivable (receiv- - able|payable)" amt:\>100. - - More escaping - Characters significant both to the shell and in regular expressions may - need one extra level of escaping. 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:\\$ - - Even more escaping - When hledger runs an addon executable (eg you type hledger ui, hledger - runs hledger-ui), it de-escapes command-line options and arguments - once, so you might need to triple-escape. Eg in bash, running the ui - command and matching the dollar sign, it's: - - hledger ui cur:'\\$' - - or: - - hledger ui cur:\\\\$ - - If you asked why four slashes above, this may help: - - - unescaped: $ - escaped: \$ - double-escaped: \\$ - triple-escaped: \\\\$ - - (The number of backslashes in fish shell is left as an exercise for the - reader.) - - You can always avoid the extra escaping for addons by running the addon - directly: - - hledger-ui cur:\\$ - - Less escaping - Inside an argument file, or in the search field of hledger-ui or - hledger-web, or at a GHCI prompt, you need one less level of escaping - than at the command line. And backslashes may work better than quotes. - Eg: - - ghci> :main balance cur:\$ - - Command line tips - If in doubt, keep things simple: - - o write options after the command (hledger CMD -OPTIONS ARGS) - - o run add-on executables directly (hledger-ui -OPTIONS ARGS) - - o enclose problematic args in single quotes - - o if needed, also add a backslash to escape regexp metacharacters - - To find out exactly how a command line is being parsed, add --debug=2 - to troubleshoot. - - Unicode characters - hledger is expected to handle unicode (non-ascii) characters, but this - requires a well-configured environment. - - To handle unicode characters in the command line or input data, a sys- - tem locale that can decode them must be configured (POSIX's default C - locale will not work). Eg in bash, you could do: - - export LANG=en_US.UTF-8 - - See Troubleshooting for more about this. - - Unicode characters should appear correctly in hledger's output. For - the hledger and hledger-ui tools, this requires that - - o your terminal supports unicode - - o the terminal's font includes the required unicode glyphs - - o the terminal is configured to display "wide" characters as double - width (otherwise report alignment will be off) - - 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: - - - 2004/10/1, 2004-01-01, exact date, several sepa- - 2004.9.1 rators allowed. Year is - 4+ digits, month is 1-12, - day is 1-31 - 2004 start of year - - 2004/10 start of month - 10/1 month and day in current - year - 21 day in current month - october, oct start of month in current - year - yesterday, today, tomorrow -1, 0, 1 days from today - last/this/next day/week/month/quar- -1, 0, 1 periods from the - ter/year current period - 20181201 8 digit YYYYMMDD with - valid year month and day - 201812 6 digit YYYYMM with valid - year and month - - Counterexamples - malformed digit sequences might give surprising - results: - - - 201813 6 digits with an invalid - month is parsed as start - of 6-digit year - 20181301 8 digits with an invalid - month is parsed as start - of 8-digit year - 20181232 8 digits with an invalid - day gives an error - 201801012 9+ digits beginning with a - valid YYYYMMDD gives an - error - - 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 commod- - ity. - - 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 -N euros - 100 assets:euros - - What are they worth at end of nov 3 ? - - $ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date specified, - defaults to today) - - $ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - Currently, hledger's -V only uses market prices recorded with P direc- - tives, not transaction prices (unlike Ledger). - - Currently, -V has a limitation in multicolumn balance reports: it uses - the market prices on the report end date for all columns. (Instead of - the prices on each column's end date.) - - Combining -B and -V - Using -B/-cost and -V/-value together is currently allowed, but the - results are probably not meaningful. Let us know if you find a use for - this. - - Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- - trolled by the -o/--output-file option. - - $ hledger balance -o - # write to stdout (the default) - $ hledger balance -o FILE # write to FILE - - Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or - HTML. This is controlled by the -O/--output-format option, or by spec- - ifying a .csv or .html file extension with -o/--output-file. - - $ hledger balance -O csv # write CSV to stdout - $ hledger balance -o FILE.csv # write CSV to FILE.csv - - Regular expressions - hledger uses regular expressions in a number of places: - - o query terms, on the command line and in the hledger-web search form: - REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX - - o CSV rules conditional blocks: if REGEX ... - - o account alias directives and options: alias /REGEX/ = REPLACEMENT, - --alias /REGEX/=REPLACEMENT - - hledger's regular expressions come from the regex-tdfa library. In - general they: - - o are case insensitive - - o are infix matching (do not need to match the entire thing being - matched) - - o are POSIX extended regular expressions - - o also support GNU word boundaries (\<, \>, \b, \B) - - o and parenthesised capturing groups and numeric backreferences in - replacement strings - - o do not support mode modifiers like (?s) - - Some things to note: - - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, - these are not required. - - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts - with the dollar sign in hledger-web, write cur:\$. - - o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped at least once more. See Spe- - cial characters. - -QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a - web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate - the match. - - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match - (or negatively match): - - o any of the description terms AND - - o any of the account terms AND - - o any of the status terms AND - - o all the other terms. - - The print command instead shows transactions which: - - o match any of the description terms AND - - o have any postings matching any of the positive account terms AND - - o have no postings matching any of the negative account terms AND - - o match all the other terms. - - The following kinds of search terms can be used. Remember these can - also be prefixed with not:, eg to exclude a particular subaccount. - - REGEX, acct:REGEX - match account names by this regular expression. (With no pre- - fix, acct: is assumed.) - same as above - - amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not - tested, and will always match.) The comparison has two modes: if - N is preceded by a + or - sign (or is 0), the two signed numbers - are compared. Otherwise, the absolute magnitudes are compared, - ignoring sign. - - code:REGEX - match by transaction code (eg check number) - - cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- - tial match, use .*REGEX.*). Note, to match characters which are - regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: - hledger print cur:'\$' or hledger print cur:\\$. - - desc:REGEX - match transaction descriptions. - - date:PERIODEXPR - match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary - dates instead. - - date2:PERIODEXPR - match secondary dates within the specified period. - - depth:N - match (or display, depending on command) accounts at or above - this depth - - note:REGEX - match transaction notes (part of description right of |, or - whole description when there's no |) - - payee:REGEX - match transaction payee/payer names (part of description left of - |, or whole description when there's no |) - - real:, real:0 - match real or virtual postings respectively - - status:, status:!, status:* - match unmarked, pending, or cleared transactions respectively - - tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the - tags of their parent transaction. - - The following special search term is used automatically in hledger-web, - only: - - inacct:ACCTNAME - tells hledger-web to show the transaction register for this - account. Can be filtered further with acct etc. - - Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps - excluding the -p/--period option). - -COMMANDS - hledger provides a number of subcommands; hledger with no arguments - shows a list. - - If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as - subcommands. - - Run a subcommand by writing its name as first argument (eg - hledger incomestatement). You can also write one of the standard short - aliases displayed in parentheses in the command list (hledger b), or - any any unambiguous prefix of a command name (hledger inc). - - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for - detailed command help. - - accounts - Show account names. Alias: a. - - --declared - show account names declared with account directives - - --used show account names posted to by transactions - - --tree show short account names and their parents, as a tree - - --flat show full account names, as a list (default) - - --drop=N - in flat mode: omit N leading account name parts - - This command lists account names, either declared with account direc- - tives (-declared), posted to (-used), or both (default). With query - arguments, only matched account names and account names referenced by - matched postings are shown. It shows a flat list by default. With - --tree, it uses indentation to show the account hierarchy. In flat - mode you can add --drop N to omit the first few account name compo- - nents. Account names can be depth-clipped with --depth N or depth:N. - - Examples: - - $ hledger accounts --tree - assets - bank - checking - saving - cash - expenses - food - supplies - income - gifts - salary - liabilities - debts - - $ hledger accounts --drop 1 - bank:checking - bank:saving - cash - food - supplies - gifts - salary - debts - - $ hledger accounts - assets:bank:checking - assets:bank:saving - assets:cash - expenses:food - expenses:supplies - income:gifts - income:salary - liabilities:debts - - activity - Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the - default). With query arguments, it counts only matched transactions. - - $ hledger activity --quarterly - 2008-01-01 ** - 2008-04-01 ******* - 2008-07-01 - 2008-10-01 ** - - add - Prompt for transactions and add them to the journal. - - --no-new-accounts - don't allow creating new accounts; helps prevent typos when - entering account names - - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the journal file (if there are multiple - -f FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal - file. - - To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press - control-d or control-c to exit. - - Features: - - o add tries to provide useful defaults, using the most similar recent - transaction (by description) as a template. - - o You can also set the initial defaults with command line arguments. - - o Readline-style edit keys can be used during data entry. - - o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is - empty, it will insert the default value. - - o If the journal defines a default commodity, it will be added to any - bare numbers entered. - - o A parenthesised transaction code may be entered following a date. - - o Comments and tags may be entered following a description or amount. - - o If you make a mistake, enter < at any prompt to restart the transac- - tion. - - o Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see the tutorial for a detailed explanation): - - $ hledger add - Adding transactions to journal file /src/hledger/examples/sample.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to restart the transaction. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2015/05/22]: - Description: supermarket - Account 1: expenses:food - Amount 1: $10 - Account 2: assets:checking - Amount 2 [$-10.0]: - Account 3 (or . or enter to finish this transaction): . - 2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2015/05/22]: $ - - balance - Show accounts and their balances. Aliases: b, bal. - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports) - - -H --historical - show historical ending balance in each period (includes postings - before report start date) - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv, html. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - --pretty-tables - use unicode to display prettier tables. - - --sort-amount - sort by amount instead of account code/name (in flat mode). - With multiple columns, sorts by the row total, or by row average - if that is displayed. - - --invert - display all amounts with reversed sign - - --budget - show performance compared to budget goals defined by periodic - transactions - - --show-unbudgeted - with -budget, show unbudgeted accounts also - - The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may - be more convenient for that. - - By default, it displays all accounts, and each account's change in bal- - ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a - different time period, changes from only cleared transactions, etc. - - If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- - tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show - real-world account balances. In some cases the -H/-historical flag is - used to ensure this (more below). - - The balance command can produce several styles of report: - - Classic balance report - This is the original balance report, as found in Ledger. It usually - looks like this: - - $ 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 - - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with - -S/--sort-amount, by their balance amount. - - "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to - prevent this. - - Account balances are "inclusive" - they include the balances of any - subaccounts. - - Accounts which have zero balance (and no non-zero subaccounts) are - omitted. Use -E/--empty to show them. - - A final total is displayed by default; use -N/--no-total to suppress - it, eg: - - $ hledger balance -p 2008/6 expenses --no-total - $2 expenses - $1 food - $1 supplies - - Customising the classic balance report - You can customise the layout of classic balance reports with --for- - mat 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 - - Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "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 or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise - a complex set of accounts and get an overview. - - $ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - - Flat-mode balance reports, which normally show exclusive balances, show - inclusive balances at the depth limit. - - Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting - interval. - - There are three types of multicolumn 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 - - Multicolumn 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 - - Limitations: - - In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end - date). - - Eliding of boring parent accounts in tree mode, as in the classic bal- - ance report, is not yet supported in multicolumn reports. - - Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. -budget is most often combined with - a report interval. - - 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 report: - - $ hledger balance -M --budget - Budget performance in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 - ======================++================================================= - || $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 - - By default, only accounts with budget goals during the report period - are shown. --show-unbudgeted shows unbudgeted accounts as well. - Top-level accounts with no budget goals anywhere below them are grouped - under . - - You can roll over unspent budgets to next period with --cumulative: - - $ hledger balance -M --budget --cumulative - Budget performance in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 - ======================++================================================= - || $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 - - Note, the -S/--sort-amount flag is not yet fully supported with --bud- - get. - - For more examples, see Budgeting and Forecasting. - - Output format - The balance command supports output destination and output format - selection. - - balancesheet - This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or - liability account (case insensitive, plural forms also allowed). Note - this report shows all account balances with normal positive sign (like - conventional financial statements, unlike balance/print/register) - (experimental). (bs) - - --change - show balance change in each period, instead of historical ending - balances - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of historical ending balances - - -H --historical - show historical ending balance in each period (includes postings - before report start date) (default) - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - --sort-amount - sort by amount instead of account code/name - - Example: - - $ hledger balancesheet - Balance Sheet - - Assets: - $-1 assets - $1 bank:saving - $-2 cash - -------------------- - $-1 - - Liabilities: - $1 liabilities:debts - -------------------- - $1 - - Total: - -------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for - a balance sheet; note this means it ignores report begin dates. - - This command also supports output destination and output format selec- - tion. - - balancesheetequity - Just like balancesheet, but also reports Equity (which it assumes is - under a top-level equity account). - - Example: - - $ hledger balancesheetequity - Balance Sheet With Equity - - Assets: - $-2 assets - $1 bank:saving - $-3 cash - -------------------- - $-2 - - Liabilities: - $1 liabilities:debts - -------------------- - $1 - - Equity: - $1 equity:owner - -------------------- - $1 - - Total: - -------------------- - 0 - - cashflow - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all - account balances with normal positive sign (like conventional financial - statements, unlike balance/print/register) (experimental). (cf) - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods - - -H --historical - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row (in simple reports) - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - --sort-amount - sort by amount instead of account code/name - - Example: - - $ hledger cashflow - Cashflow Statement - - Cash flows: - $-1 assets - $1 bank:saving - $-2 cash - -------------------- - $-1 - - Total: - -------------------- - $-1 - - With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report - mode with --change/--cumulative/--historical. - - This command also supports output destination and output format selec- - tion. - - check-dates - Check that transactions are sorted by increasing date. With a query, - only matched transactions' dates are checked. - - check-dupes - Report account names having the same leaf but different prefixes. An - example: http://stefanorodighiero.net/software/hledger-dupes.html - - close - Print closing/opening transactions that bring some or all account bal- - ances to zero and back. Can be useful for bringing asset/liability - balances across file boundaries, or for closing out income/expenses for - a period. This was formerly called "equity", as in Ledger, and that - alias is also accepted. See close -help for more. - - files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - help - Show any of the hledger manuals. - - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide - a full or partial manual name to select one. - - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can - force a particular viewer with the --info, --man, --pager, --cat flags. - - $ hledger help - Please choose a manual by typing "hledger help MANUAL" (a substring is ok). - Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot - - $ hledger help h --man - - hledger(1) hledger User Manuals hledger(1) - - NAME - hledger - a command-line accounting tool - - SYNOPSIS - hledger [-f FILE] COMMAND [OPTIONS] [ARGS] - hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] - hledger - - DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any - ... - - import - Read new transactions added to each FILE since last run, and add them - to the main journal file. - - --dry-run - just show the transactions to be imported - - The input files are specified as arguments - no need to write -f before - each one. So eg to add new transactions from all CSV files to the main - journal, it's just: hledger import *.csv - - New transactions are detected in the same way as print -new: by assum- - ing transactions are always added to the input files in increasing date - order, and by saving .latest.FILE state files. - - The -dry-run output is in journal format, so you can filter it, eg to - see only uncategorised transactions: - - $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions - - incomestatement - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, - unlike balance/print/register) (experimental). (is) - - --change - show balance change in each period (default) - - --cumulative - show balance change accumulated across periods (in multicolumn - reports), instead of changes during periods - - -H --historical - show historical ending balance in each period (includes postings - before report start date), instead of changes during each period - - --tree show accounts as a tree; amounts include subaccounts (default in - simple reports) - - --flat show accounts as a list; amounts exclude subaccounts except when - account is depth-clipped (default in multicolumn reports) - - -A --average - show a row average column (in multicolumn mode) - - -T --row-total - show a row total column (in multicolumn mode) - - -N --no-total - don't show the final total row - - --drop=N - omit N leading account name parts (in flat mode) - - --no-elide - don't squash boring parent accounts (in tree mode) - - --format=LINEFORMAT - in single-column balance reports: use this custom line format - - --sort-amount - sort by amount instead of account code/name - - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense - (plural forms also allowed.) - - $ hledger incomestatement - Income Statement - - Revenues: - $-2 income - $-1 gifts - $-1 salary - -------------------- - $-2 - - Expenses: - $2 expenses - $1 food - $1 supplies - -------------------- - $2 - - Total: - -------------------- - 0 - - With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the - report mode with --change/--cumulative/--historical. - - This command also supports output destination and output format selec- - tion. - - prices - Print market price directives from the journal. With -costs, also - print synthetic market prices based on transaction prices. With - -inverted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. - - print - Show transactions from the journal. Aliases: p, txns. - - -m STR --match=STR - show the transaction whose description is most similar to STR, - and is most recent - - --new show only newer-dated transactions added in each file since last - run - - -x --explicit - show all amounts explicitly - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - $ hledger print - 2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - 2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - - 2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - - 2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - - 2008/12/31 * pay off - liabilities:debts $1 - assets:bank:checking $-1 - - The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. print's output is always - a valid hledger journal. It preserves all transaction information, but - it does not preserve directives or inter-transaction comments - - Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all - amounts explicit, which can be useful for troubleshooting or for making - your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- - put. - - With -B/--cost, amounts with transaction prices are converted to cost - using that price. This can be used for troubleshooting. - - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is - no similar-enough match, no transaction will be shown. - - With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV - files. Eg: - - $ hledger -f bank1.csv print --new - # shows transactions added since last print --new on this file - - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get - reordered. See also the import command. - - This command also supports output destination and output format selec- - tion. Here's an example of print's CSV output: - - $ hledger print -Ocsv - "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" - "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" - "1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" - "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" - "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" - "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" - "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" - "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" - "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" - "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" - "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" - "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - o There is one CSV record per posting, with the parent transaction's - fields repeated. - - o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different - order, etc.) - - o The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - - o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or - greater amounts under debit.) - - print-unique - Print transactions which do not reuse an already-seen description. - - register - Show postings and their running total. Aliases: r, reg. - - --cumulative - show running total from report start date (default) - - -H --historical - show historical running total/balance (includes postings before - report start date) - - -A --average - show running average of posting amounts instead of total - (implies -empty) - - -r --related - show postings' siblings instead - - -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M - sets description width as well) - - -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular - account, to see that account's activity: - - $ hledger register checking - 2008/01/01 income assets:bank:checking $1 $1 - 2008/06/01 gift assets:bank:checking $1 $2 - 2008/06/02 save assets:bank:checking $-1 $1 - 2008/12/31 pay off assets:bank:checking $-1 0 - - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see - only recent activity, with a historically accurate running balance: - - $ hledger register checking -b 2008/6 --historical - 2008/06/01 gift assets:bank:checking $1 $2 - 2008/06/02 save assets:bank:checking $-1 $1 - 2008/12/31 pay off assets:bank:checking $-1 0 - - The --depth option limits the amount of sub-account detail displayed. - - The --average/-A flag shows the running average posting amount instead - of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one - account and one commodity. - - The --related/-r flag shows the other postings in the transactions of - the postings which would normally be shown. - - With a reporting interval, register shows summary postings, one per - interval, aggregating the postings to each account: - - $ hledger register --monthly income - 2008/01 income:salary $-1 $-1 - 2008/06 income:gifts $-1 $-2 - - Periods with no activity, and summary postings with a zero amount, are - not shown by default; use the --empty/-E flag to see them: - - $ hledger register --monthly income -E - 2008/01 income:salary $-1 $-1 - 2008/02 0 $-1 - 2008/03 0 $-1 - 2008/04 0 $-1 - 2008/05 0 $-1 - 2008/06 income:gifts $-1 $-2 - 2008/07 0 $-2 - 2008/08 0 $-2 - 2008/09 0 $-2 - 2008/10 0 $-2 - 2008/11 0 $-2 - 2008/12 0 $-2 - - Often, you'll want to see just one line per interval. The --depth - option helps with this, causing subaccounts to be aggregated: - - $ hledger register --monthly assets --depth 1h - 2008/01 assets $1 $1 - 2008/06 assets $-1 0 - 2008/12 assets $-1 $-1 - - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full - length and comparable to the others in the report. - - Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not - a bash shell variable) or by using the --width/-w option. - - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of -width's argument, comma-separated: - --width W,D . Here's a diagram: - - <--------------------------------- width (W) ----------------------------------> - date (10) description (D) account (W-41-D) amount (12) balance (12) - DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - and some examples: - - $ hledger reg # use terminal width (or 80 on windows) - $ hledger reg -w 100 # use width 100 - $ COLUMNS=100 hledger reg # set with one-time environment variable - $ export COLUMNS=100; hledger reg # set till session end (or window resize) - $ hledger reg -w 100,40 # set overall width 100, description width 40 - $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - - This command also supports output destination and output format selec- - tion. - - register-match - Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect - already-seen transactions when importing. - - rewrite - Print all transactions, adding custom postings to the matched ones. - - roi - Shows time-weighted (TWR) and money-weighted (IRR) rate of return on - your investments. See roi --help for more. - - stats - Show some journal statistics. - - -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the - above formats selects that format. - - $ hledger stats - Main journal file : /src/hledger/examples/sample.journal - Included journal files : - Transactions span : 2008-01-01 to 2009-01-01 (366 days) - Last transaction : 2008-12-31 (2333 days ago) - Transactions : 5 (0.0 per day) - Transactions last 30 days: 0 (0.0 per day) - Transactions last 7 days : 0 (0.0 per day) - Payees/descriptions : 5 - Accounts : 8 (depth 3) - Commodities : 1 ($) - - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report - for each report period. - - This command also supports output destination and output format selec- - tion. - - tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With additional QUERY arguments, only transactions matching the - query are considered. - - test - Run built-in unit tests. - - Prints test names and their results on stdout. If any test fails or - gives an error, the exit code will be non-zero. - - Test names include a group prefix. If a (exact, case sensitive) group - prefix, or a full test name is provided as the first argument, only - that group or test is run. - - If a numeric second argument is provided, it will set the randomness - seed, for repeatable results from tests using randomness (currently - none of them). - - This is mainly used by developers, but it's nice to be able to san- - ity-check your installed hledger executable at any time. All tests are - expected to pass - if you ever see otherwise, something has gone wrong, - please report a bug! - -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, but it's superseded now by the built-in roi command. - - Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- - tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good - way to start making your own! - - autosync - hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank - offers OFX Direct Connect. - - chart - hledger-chart.hs is an old pie chart generator, in need of some love. - - check - hledger-check.hs checks more powerful account balance assertions. - -ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the - full terminal width. - - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede addon command options with -- when invoked from - hledger is awkward. - - When input data contains non-ascii characters, a suitable system locale - must be configured (or there will be an unhelpful error). Eg on POSIX, - set LANG to something other than C. - - In a Microsoft Windows CMD window, non-ascii characters and colours are - not supported. - - In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger - add. - - Not all of Ledger's journal file syntax is supported. See file format - differences. - - On large data files, hledger is slower and uses more memory than - Ledger. - -TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug - tracker): - - Successfully installed, but "No command `hledger' found" - stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, - that is ~/.local/bin and ~/.cabal/bin respectively. - - I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may - need to use export. Here's an explanation. - - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide - character" errors - In order to handle non-ascii letters and symbols (like ), hledger needs - an appropriate locale. This is usually configured system-wide; you can - also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, - I'm not sure yet). - - Here's an example of setting the locale temporarily, on ubuntu - gnu/linux: - - $ file my.journal - my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded - $ locale -a - C - en_US.utf8 # <- a UTF8-aware locale is available - POSIX - $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command - - Here's one way to set it permanently, there are probably better ways: - - $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile - $ bash --login - - If we preferred to use eg fr_FR.utf8, we might have to install that - first: - - $ apt-get install language-pack-fr - $ locale -a - C - en_US.utf8 - fr_BE.utf8 - fr_CA.utf8 - fr_CH.utf8 - fr_FR.utf8 - fr_LU.utf8 - POSIX - $ LANG=fr_FR.utf8 hledger -f my.journal print - - Note some platforms allow variant locale spellings, but not all (ubuntu - accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger 1.12 December 2018 hledger(1) + Field separator to expect when reading CSV (default: ',') + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot FIELDNAME + use some other field or tag for the account name + + -I --ignore-assertions + ignore any failing balance assertions + + General reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) + + --date2 + match the secondary date instead (see command help for other + effects) + + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) + + -P --pending + include only pending postings/txns + + -C --cleared + include only cleared postings/txns + + -R --real + include only non-virtual postings + + -NUM --depth=NUM + hide/aggregate accounts or postings more than NUM levels deep + + -E --empty + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + --auto apply automated posting rules to modify transactions. + + --forecast + apply periodic transaction rules to generate future transac- + tions, to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, the + last one takes precedence. + + Some reporting options can also be written as query arguments. + + Command options + To see options for a particular command, including command-specific + options, run: hledger COMMAND -h. + + Command-specific options must be written after the command name, eg: + hledger print -x. + + Additionally, if the command is an addon, you may need to put its + options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + run the addon executable directly: hledger-ui --watch. + + Command arguments + Most hledger commands accept arguments after the command name, which + are often a query, filtering the data in some way. + + Argument files + You can save a set of command line options/arguments in a file, one per + line, and then reuse them by writing @FILENAME in a command line. To + prevent this expansion of @-arguments, precede them with a -- argument. + For more, see Save frequently used options. + + Special characters in arguments and queries + In shell command lines, option and argument values which contain "prob- + lematic" characters, ie spaces, and also characters significant to your + shell such as <, >, (, ), | and $, should be escaped by enclosing them + in quotes or by writing backslashes before the characters. Eg: + + hledger register -p 'last year' "accounts receivable (receiv- + able|payable)" amt:\>100. + + More escaping + Characters significant both to the shell and in regular expressions may + need one extra level of escaping. 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:\\$ + + Even more escaping + When hledger runs an addon executable (eg you type hledger ui, hledger + runs hledger-ui), it de-escapes command-line options and arguments + once, so you might need to triple-escape. Eg in bash, running the ui + command and matching the dollar sign, it's: + + hledger ui cur:'\\$' + + or: + + hledger ui cur:\\\\$ + + If you asked why four slashes above, this may help: + + + unescaped: $ + escaped: \$ + double-escaped: \\$ + triple-escaped: \\\\$ + + (The number of backslashes in fish shell is left as an exercise for the + reader.) + + You can always avoid the extra escaping for addons by running the addon + directly: + + hledger-ui cur:\\$ + + Less escaping + Inside an argument file, or in the search field of hledger-ui or + hledger-web, or at a GHCI prompt, you need one less level of escaping + than at the command line. And backslashes may work better than quotes. + Eg: + + ghci> :main balance cur:\$ + + Command line tips + If in doubt, keep things simple: + + o write options after the command (hledger CMD -OPTIONS ARGS) + + o run add-on executables directly (hledger-ui -OPTIONS ARGS) + + o enclose problematic args in single quotes + + o if needed, also add a backslash to escape regexp metacharacters + + To find out exactly how a command line is being parsed, add --debug=2 + to troubleshoot. + + Unicode characters + hledger is expected to handle unicode (non-ascii) characters, but this + requires a well-configured environment. + + To handle unicode characters in the command line or input data, a sys- + tem locale that can decode them must be configured (POSIX's default C + locale will not work). Eg in bash, you could do: + + export LANG=en_US.UTF-8 + + See Troubleshooting for more about this. + + Unicode characters should appear correctly in hledger's output. For + the hledger and hledger-ui tools, this requires that + + o your terminal supports unicode + + o the terminal's font includes the required unicode glyphs + + o the terminal is configured to display "wide" characters as double + width (otherwise report alignment will be off) + + 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: + + + 2004/10/1, 2004-01-01, exact date, several sepa- + 2004.9.1 rators allowed. Year is + 4+ digits, month is 1-12, + day is 1-31 + 2004 start of year + + 2004/10 start of month + 10/1 month and day in current + year + 21 day in current month + october, oct start of month in current + year + yesterday, today, tomorrow -1, 0, 1 days from today + last/this/next day/week/month/quar- -1, 0, 1 periods from the + ter/year current period + 20181201 8 digit YYYYMMDD with + valid year month and day + 201812 6 digit YYYYMM with valid + year and month + + Counterexamples - malformed digit sequences might give surprising + results: + + + 201813 6 digits with an invalid + month is parsed as start + of 6-digit year + 20181301 8 digits with an invalid + month is parsed as start + of 8-digit year + 20181232 8 digits with an invalid + day gives an error + 201801012 9+ digits beginning with a + valid YYYYMMDD gives an + error + + 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 pre- + ceeding 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" -- + 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 bound- + aries 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 commod- + ity. + + 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 -N euros + 100 assets:euros + + What are they worth at end of nov 3 ? + + $ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date specified, + defaults to today) + + $ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P direc- + tives, not transaction prices (unlike Ledger). + + Currently, -V has a limitation in multicolumn balance reports: it uses + the market prices on the report end date for all columns. (Instead of + the prices on each column's end date.) + + Combining -B and -V + Using -B/--cost and -V/--value together is currently allowed, but the + results are probably not meaningful. Let us know if you find a use for + this. + + Output destination + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- + trolled by the -o/--output-file option. + + $ hledger balance -o - # write to stdout (the default) + $ hledger balance -o FILE # write to FILE + + Output format + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or + HTML. This is controlled by the -O/--output-format option, or by spec- + ifying a .csv or .html file extension with -o/--output-file. + + $ hledger balance -O csv # write CSV to stdout + $ hledger balance -o FILE.csv # write CSV to FILE.csv + + Regular expressions + hledger uses regular expressions in a number of places: + + o query terms, on the command line and in the hledger-web search form: + REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX + + o CSV rules conditional blocks: if REGEX ... + + o account alias directives and options: alias /REGEX/ = REPLACEMENT, + --alias /REGEX/=REPLACEMENT + + hledger's regular expressions come from the regex-tdfa library. In + general they: + + o are case insensitive + + o are infix matching (do not need to match the entire thing being + matched) + + o are POSIX extended regular expressions + + o also support GNU word boundaries (\<, \>, \b, \B) + + o and parenthesised capturing groups and numeric backreferences in + replacement strings + + o do not support mode modifiers like (?s) + + Some things to note: + + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + these are not required. + + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write cur:\$. + + o On the command line, some metacharacters like $ have a special mean- + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. + +QUERIES + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a + web search: one or more space-separated search terms, quotes to enclose + whitespace, prefixes to match specific fields, a not: prefix to negate + the match. + + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match + (or negatively match): + + o any of the description terms AND + + o any of the account terms AND + + o any of the status terms AND + + o all the other terms. + + The print command instead shows transactions which: + + o match any of the description terms AND + + o have any postings matching any of the positive account terms AND + + o have no postings matching any of the negative account terms AND + + o match all the other terms. + + The following kinds of search terms can be used. Remember these can + also be prefixed with not:, eg to exclude a particular subaccount. + + REGEX, acct:REGEX + match account names by this regular expression. (With no pre- + fix, acct: is assumed.) + 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 + accounts, a + Show account names. + + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N + or -N. + + Examples: + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + activity + 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. + + Examples: + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + + add + add + Prompt for transactions and add them to the journal. + + 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 (by + description) recent transaction (filtered by the query, if any) 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 + balance, bal, b + Show accounts and their balances. + + The balance command is hledger's most versatile command. Note, despite + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may + be more convenient for that. + + By default, it displays all accounts, and each account's change in bal- + ance during the entire period of the journal. Balance changes are cal- + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a + different time period, changes from only cleared transactions, etc. + + If you include an account's complete history of postings in the report, + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- + tions in the journal; instead you'll have all transactions after a cer- + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show + real-world account balances. In some cases the -H/--historical flag is + used to ensure this (more below). + + The balance command can produce several styles of report: + + Classic balance report + This is the original balance report, as found in Ledger. It usually + looks like this: + + $ 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 + + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with + -S/--sort-amount, by their balance amount. + + "Boring" accounts, which contain a single interesting subaccount and no + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to + prevent this. + + Account balances are "inclusive" - they include the balances of any + subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are + omitted. Use -E/--empty to show them. + + A final total is displayed by default; use -N/--no-total to suppress + it, eg: + + $ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + + Customising the classic balance report + You can customise the layout of classic balance reports with --for- + mat 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 + + Flat mode + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "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 or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise + a complex set of accounts and get an overview. + + $ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Flat-mode balance reports, which normally show exclusive balances, show + inclusive balances at the depth limit. + + Multicolumn balance report + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting + interval. + + There are three types of multicolumn 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 + + Multicolumn 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). With --budget, --empty also shows unbudgeted + accounts. + + 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 + + Limitations: + + In multicolumn reports the -V/--value flag uses the market price on the + report end date, for all columns (not the price on each column's end + date). + + Eliding of boring parent accounts in tree mode, as in the classic bal- + ance report, is not yet supported in multicolumn reports. + + Budget report + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual + income, expenses, time usage, etc. --budget is most often combined + with a report interval. + + 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 report: + + $ hledger balance -M --budget + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + By default, only accounts with budget goals during the report period + are shown. In the example above, transactions in expenses:gifts and + expenses:supplies are counted towards expenses budget, but accounts + expenses:gifts and expenses:supplies are not shown, as they don't have + any budgets. + + You can use --empty shows unbudgeted accounts as well: + + $ hledger balance -M --budget --empty + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with --cumulative: + + $ hledger balance -M --budget --cumulative + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + Note, the -S/--sort-amount flag is not yet fully supported with --bud- + get. + + For more examples, see Budgeting and Forecasting. + + Nested budgets + You can add budgets to any account in your account hierarchy. If you + have budgets on both parent account and some of its children, then bud- + get(s) of the child account(s) would be added to the budget of their + parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any + account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity + means that budget for both expenses:personal and expenses is $1100. + + Transactions in expenses:personal:electronics will be counted both + towards its $100 budget and $1100 of expenses:personal , and transac- + tions in any other subaccount of expenses:personal would be counted + towards only towards the budget of expenses:personal. + + For example, let's consider these transactions: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + 2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + + 2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + + 2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + + 2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- + tions would be counted towards budgets of expenses:personal:electronics + and expenses:personal accordingly: + + $ hledger balance --budget -M + Budget performance in 2019/01: + + || Jan + ===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] + -------------------------------++------------------------------- + || 0 [ 0] + + And with --empty, we can get a better picture of budget allocation and + consumption: + + $ hledger balance --budget -M --empty + Budget performance in 2019/01: + + || Jan + ========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] + ----------------------------------------++------------------------------- + || 0 [ 0] + + Output format + The balance command supports output destination and output format + selection. + + balancesheet + balancesheet, bs + This command displays a simple balance sheet, showing historical ending + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). + + Note this report shows all account balances with normal positive sign + (like conventional financial statements, unlike balance/print/register) + (experimental). + + Example: + + $ hledger balancesheet + Balance Sheet + + Assets: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Total: + -------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for each + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates. + + This command also supports output destination and output format selec- + tion. + + balancesheetequity + balancesheetequity, bse + Just like balancesheet, but also reports Equity (which it assumes is + under a top-level equity account). + + Example: + + $ hledger balancesheetequity + Balance Sheet With Equity + + Assets: + $-2 assets + $1 bank:saving + $-3 cash + -------------------- + $-2 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Equity: + $1 equity:owner + -------------------- + $1 + + Total: + -------------------- + 0 + + cashflow + cashflow, cf + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all + account balances with normal positive sign (like conventional financial + statements, unlike balance/print/register) (experimental). + + Example: + + $ hledger cashflow + Cashflow Statement + + Cash flows: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Total: + -------------------- + $-1 + + With a reporting interval, multiple columns will be shown, one for each + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report + mode with --change/--cumulative/--historical. + + This command also supports output destination and output format selec- + tion. + + check-dates + check-dates + Check that transactions are sorted by increasing date. With --date2, + checks secondary dates instead. With --strict, dates must also be + unique. With a query, only matched transactions' dates are checked. + Reads the default journal file, or another specified with -f. + + check-dupes + check-dupes + Reports account names having the same leaf but different prefixes. In + other words, two or more leaves that are categorized differently. + Reads the default journal file, or another specified as an argument. + + An example: http://stefanorodighiero.net/software/hledger-dupes.html + + close + close, equity + Prints a "closing balances" transaction and an "opening balances" + transaction that bring account balances to and from zero, respectively. + Useful for bringing asset/liability balances forward into a new journal + file, or for closing out revenues/expenses to retained earnings at the + end of a period. + + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- + ing balances". You can chose to print just one of the transactions by + using the --opening or --closing flag. + + If you split your journal files by time (eg yearly), you will typically + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- + ing|closing) balances'.) + + If you're running a business, you might also use this command to "close + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to + change the equity account name to something like "equity:retained earn- + ings".) + + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + You can also use -p or date:PERIOD (any starting date is ignored). + + Both transactions will include balance assertions for the + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- + erated balance assertions will depend on these flags. Likewise, if you + run this command with --auto, the balance assertions will probably + always require --auto. + + Examples: + + Carrying asset/liability balances into a new file for 2019, all from + command line: + + Warning: we use >> here to append; be careful not to type a single > + which would wipe your journal! + + $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal + $ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + + Now: + + $ hledger bs -f 2019.journal # one file - balances are correct + $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct + $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + + Transactions spanning the closing date can complicate matters, breaking + balance assertions: + + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + + Here's one way to resolve that: + + ; in 2018.journal: + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + + ; in 2019.journal: + 2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking + + files + files + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + help + 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. + + Examples: + + $ 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 + import + Read new transactions added to each FILE since last run, and add them + to the main journal file. Or with --dry-run, just print the transac- + tions that would be added. + + 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 + incomestatement, is + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, + unlike balance/print/register) (experimental). + + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense + (plural forms also allowed.) + + $ hledger incomestatement + Income Statement + + Revenues: + $-2 income + $-1 gifts + $-1 salary + -------------------- + $-2 + + Expenses: + $2 expenses + $1 food + $1 supplies + -------------------- + $2 + + Total: + -------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for each + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. + + This command also supports output destination and output format selec- + tion. + + prices + prices + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With + --inverted-costs, also print inverse prices based on transaction + prices. Prices (and postings providing prices) can be filtered by a + query. + + print + print, txns, p + Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from the + journal file in date order, tidily formatted. With --date2, transac- + tions are sorted by secondary date instead. + + print's output is always a valid hledger journal. + It preserves all transaction information, but it does not preserve + directives or inter-transaction comments + + $ 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 + + Normally, the journal entry's explicit or implicit amount style is pre- + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all + amounts explicit, which can be useful for troubleshooting or for making + your journal more readable and robust against data entry errors. Note, + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- + put. + + With -B/--cost, amounts with transaction prices are converted to cost + using that price. This can be used for troubleshooting. + + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is + no similar-enough match, no transaction will be shown. + + With --new, for each FILE being read, hledger reads (and writes) a spe- + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for + ignoring already-seen entries in import data, such as downloaded CSV + files. Eg: + + $ hledger -f bank1.csv print --new + # shows transactions added since last print --new on this file + + This assumes that transactions added to FILE always have same or + increasing dates, and that transactions on the same day do not get + reordered. See also the import command. + + This command also supports output destination and output format selec- + tion. Here's an example of print's CSV output: + + $ hledger print -Ocsv + "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" + "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" + "1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" + "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" + "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" + "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" + "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" + "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" + "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" + "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o The "txnidx" (transaction index) field shows which postings belong to + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different + order, etc.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + print-unique + print-unique + Print transactions which do not reuse an already-seen description. + + Example: + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + + register + register, reg, r + Show postings and their running total. + + The register command displays postings in date order, 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 + + With --date2, it shows and sorts by secondary date instead. + + 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 (won't display correctly in --help): + + <--------------------------------- 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, & description width 40 + + This command also supports output destination and output format selec- + tion. + + register-match + register-match + Print the one posting whose transaction description is closest to DESC, + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps + ledger-autosync detect already-seen transactions when importing. + + rewrite + rewrite + Print all transactions, rewriting the postings of matched transactions. + For now the only rewrite available is adding new postings, like print + --auto. + + This is a start at a generic rewriter of transaction entries. It reads + the default journal and prints the transactions, like print, but adds + one or more specified postings to any transactions matching QUERY. The + posting amounts can be fixed, or a multiplier of the existing transac- + tion's first posting amount. + + Examples: + + hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' + hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' + hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + + = ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the + two spaces between account and amount. + + More: + + $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... + $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' + $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' + $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can + use '*' (star symbol) before the amount to indicate that that this is a + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- + modity. + + Re-write rules in a file + During the run this tool will execute so called "Automated Transac- + tions" found in any journal it process. I.e instead of specifying this + operations in command line you can put them in a journal file. + + $ rewrite-rules.journal + + Make contents look like this: + + = ^income + (liabilities:tax) *.33 + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that '=' (equality symbol) that is used instead of date in trans- + actions you usually write. It indicates the query by which you want to + match the posting to add new ones. + + $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + + $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- + ings. + + Diff output format + To use this tool for batch modification of your journal files you may + find useful output in form of unified diff. + + $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + + --- /tmp/examples/sample.journal + +++ /tmp/examples/sample.journal + @@ -18,3 +18,4 @@ + 2008/01/01 income + - assets:bank:checking $1 + + assets:bank:checking $1 + income:salary + + (liabilities:tax) 0 + @@ -22,3 +23,4 @@ + 2008/06/01 gift + - assets:bank:checking $1 + + assets:bank:checking $1 + income:gifts + + (liabilities:tax) 0 + + If you'll pass this through patch tool you'll get transactions contain- + ing the posting that matches your query be updated. Note that multiple + files might be update according to list of input files specified via + --file options and include directives inside of these files. + + Be careful. Whole transaction being re-formatted in a style of output + from hledger print. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + rewrite vs. print --auto + This command predates print --auto, and currently does much the same + thing, but with these differences: + + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + + o rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + + o rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. + + roi + roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + on your investments. + + This command assumes that you have account(s) that hold nothing but + your investments and whenever you record current appraisal/valuation of + these investments you offset unrealized profit and loss into account(s) + that, again, hold nothing but unrealized profit and loss. + + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to + be your investments or withdrawals. + + At a minimum, you need to supply a query (which could be just an + account name) to select your investments with --inv, and another query + to identify your profit and loss transactions with --pnl. + + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, + regardless of the length of reporting interval. + + stats + stats + Show some journal statistics. + + 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. + + Example: + + $ 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 ($) + + This command also supports output destination and output format selec- + tion. + + tags + 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 QUERY arguments, only transactions matching the query are + considered. + + test + test + Run built-in unit tests. + + This command runs the unit tests built in to hledger-lib and hledger, + printing test names and results on stdout. If any test fails, the exit + code will be non-zero. + + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only + that group or test is run. + + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently + none of them). + + This is mainly used by developers, but it's nice to be able to san- + ity-check your installed hledger executable at any time. All tests are + expected to pass - if you ever see otherwise, something has gone wrong, + please report a bug! + +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, but it's superseded now by the built-in roi command. + + Experimental add-ons + These are available in source form in the hledger repo's bin/ direc- + tory; installing them is pretty easy. They may be less mature and doc- + umented than built-in commands. Reading and tweaking these is a good + way to start making your own! + + autosync + hledger-autosync is a symbolic link for easily running ledger-autosync, + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank + offers OFX Direct Connect. + + chart + hledger-chart.hs is an old pie chart generator, in need of some love. + + check + hledger-check.hs checks more powerful account balance assertions. + +ENVIRONMENT + COLUMNS The screen width used by the register command. Default: the + full terminal width. + + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede addon command options with -- when invoked from + hledger is awkward. + + When input data contains non-ascii characters, a suitable system locale + must be configured (or there will be an unhelpful error). Eg on POSIX, + set LANG to something other than C. + + In a Microsoft Windows CMD window, non-ascii characters and colours are + not supported. + + In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger + add. + + Not all of Ledger's journal file syntax is supported. See file format + differences. + + On large data files, hledger is slower and uses more memory than + Ledger. + +TROUBLESHOOTING + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug + tracker): + + Successfully installed, but "No command 'hledger' found" + stack and cabal install binaries into a special directory, which should + be added to your PATH environment variable. Eg on unix-like systems, + that is ~/.local/bin and ~/.cabal/bin respectively. + + I set a custom LEDGER_FILE, but hledger is still using the default file + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may + need to use export. Here's an explanation. + + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + character" errors + In order to handle non-ascii letters and symbols (like ), hledger needs + an appropriate locale. This is usually configured system-wide; you can + also configure it temporarily. The locale may need to be one that sup- + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + I'm not sure yet). + + Here's an example of setting the locale temporarily, on ubuntu + gnu/linux: + + $ file my.journal + my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded + $ locale -a + C + en_US.utf8 # <- a UTF8-aware locale is available + POSIX + $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command + + Here's one way to set it permanently, there are probably better ways: + + $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile + $ bash --login + + If we preferred to use eg fr_FR.utf8, we might have to install that + first: + + $ apt-get install language-pack-fr + $ locale -a + C + en_US.utf8 + fr_BE.utf8 + fr_CA.utf8 + fr_CH.utf8 + fr_FR.utf8 + fr_LU.utf8 + POSIX + $ LANG=fr_FR.utf8 hledger -f my.journal print + + Note some platforms allow variant locale spellings, but not all (ubuntu + accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.13 February 2019 hledger(1)