diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -9,6 +9,35 @@ User-visible changes in the hledger command line tool and library. +# 1.29.1 2023-03-16 + +Improvements + +- Hledger.Cli.Script now also exports + + Control.Applicative + Control.Concurrent + Data.Char + Data.Functor + System.IO + System.IO.Error + + and new string helpers + + strip1Char + stripBy + strip1By + +- Allow building with GHC 9.6.1 (#2011) + +Fixes + +- The stats report no longer displays "Exact" in front of dates. (#2012) + +Docs + +- remove duplicate in `hledger close` docs (Yehoshua Pesach Wallach) + # 1.29 2023-03-11 Breaking changes diff --git a/Hledger/Cli/Commands/Close.txt b/Hledger/Cli/Commands/Close.txt --- a/Hledger/Cli/Commands/Close.txt +++ b/Hledger/Cli/Commands/Close.txt @@ -42,11 +42,6 @@ With --interleaved, each equity posting is shown next to the corresponding source/destination posting. -The default closing date is yesterday or the journal's end date, -whichever is later. You can change this by specifying a report end date; -the last day of the report period will be the closing date. Eg -e 2022 -means "close on 2022-12-31". - The default closing date is yesterday, or the journal's end date, whichever is later. You can change this by specifying a report end date; (The report start date does not matter.) The last day of the report 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 @@ -70,7 +70,7 @@ (stts, tnum) = ([ ("Main file", path) -- ++ " (from " ++ source ++ ")") ,("Included files", unlines $ drop 1 $ journalFilePaths j) - ,("Transactions span", printf "%s to %s (%d days)" (start spn) (end spn) days) + ,("Transactions span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) ,("Last transaction", maybe "none" show lastdate ++ showelapsed lastelapsed) ,("Transactions", printf "%d (%0.1f per day)" tnum txnrate) ,("Transactions last 30 days", printf "%d (%0.1f per day)" tnum30 txnrate30) @@ -100,10 +100,10 @@ direction | dys >= 0 = "days ago" :: String | otherwise = "days from now" tnum1 = length ts -- Integer would be better - start (DateSpan (Just d) _) = show d - start _ = "" - end (DateSpan _ (Just d)) = show d - end _ = "" + showstart (DateSpan (Just efd) _) = show $ fromEFDay efd + showstart _ = "" + showend (DateSpan _ (Just efd)) = show $ fromEFDay efd + showend _ = "" days = fromMaybe 0 $ daysInSpan spn txnrate | days==0 = 0 | otherwise = fromIntegral tnum1 / fromIntegral days :: Double diff --git a/Hledger/Cli/Script.hs b/Hledger/Cli/Script.hs --- a/Hledger/Cli/Script.hs +++ b/Hledger/Cli/Script.hs @@ -10,8 +10,12 @@ ) where +import Control.Applicative as Script +import Control.Concurrent as Script import Control.Monad as Script +import Data.Char as Script import Data.Either as Script +import Data.Functor as Script import Data.List as Script import Data.Maybe as Script import Data.Ord as Script @@ -26,6 +30,8 @@ import System.Environment as Script import System.Exit as Script import System.FilePath as Script +import System.IO as Script +import System.IO.Error as Script import System.Process as Script import Hledger as Script diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs --- a/Hledger/Cli/Utils.hs +++ b/Hledger/Cli/Utils.hs @@ -31,8 +31,8 @@ where import Control.Exception as C -import Control.Monad.Except (ExceptT, liftIO) - +import Control.Monad.Except (ExceptT) +import Control.Monad.IO.Class (liftIO) import Data.List import Data.Maybe import qualified Data.Text as T 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" "March 2023" "hledger-ui-1.29 " "hledger User Manuals" +.TH "HLEDGER-UI" "1" "March 2023" "hledger-ui-1.29.1 " "hledger User Manuals" @@ -15,7 +15,7 @@ \f[V]hledger ui -- [OPTIONS] [QUERYARGS]\f[R] .SH DESCRIPTION .PP -This manual is for hledger\[aq]s terminal interface, version 1.29. +This manual is for hledger\[aq]s terminal interface, version 1.29.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info --- a/embeddedfiles/hledger-ui.info +++ b/embeddedfiles/hledger-ui.info @@ -16,7 +16,7 @@ ‘hledger-ui [OPTIONS] [QUERYARGS]’ ‘hledger ui -- [OPTIONS] [QUERYARGS]’ - This manual is for hledger’s terminal interface, version 1.29. See + This manual is for hledger’s terminal interface, version 1.29.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -706,40 +706,40 @@  Tag Table: Node: Top223 -Node: OPTIONS1869 -Ref: #options1967 -Node: MOUSE7334 -Ref: #mouse7429 -Node: KEYS7672 -Ref: #keys7765 -Node: SCREENS12524 -Ref: #screens12622 -Node: Menu13330 -Ref: #menu13422 -Node: All accounts13499 -Ref: #all-accounts13638 -Node: Balance sheet accounts13897 -Ref: #balance-sheet-accounts14077 -Node: Income statement accounts14269 -Ref: #income-statement-accounts14451 -Node: Register16945 -Ref: #register17082 -Node: Transaction19110 -Ref: #transaction19233 -Node: Error20117 -Ref: #error20211 -Node: TIPS20455 -Ref: #tips20554 -Node: Watch mode20596 -Ref: #watch-mode20703 -Node: Debug output22191 -Ref: #debug-output22302 -Node: ENVIRONMENT22522 -Ref: #environment22633 -Node: FILES24056 -Ref: #files24155 -Node: BUGS24415 -Ref: #bugs24492 +Node: OPTIONS1871 +Ref: #options1969 +Node: MOUSE7336 +Ref: #mouse7431 +Node: KEYS7674 +Ref: #keys7767 +Node: SCREENS12526 +Ref: #screens12624 +Node: Menu13332 +Ref: #menu13424 +Node: All accounts13501 +Ref: #all-accounts13640 +Node: Balance sheet accounts13899 +Ref: #balance-sheet-accounts14079 +Node: Income statement accounts14271 +Ref: #income-statement-accounts14453 +Node: Register16947 +Ref: #register17084 +Node: Transaction19112 +Ref: #transaction19235 +Node: Error20119 +Ref: #error20213 +Node: TIPS20457 +Ref: #tips20556 +Node: Watch mode20598 +Ref: #watch-mode20705 +Node: Debug output22193 +Ref: #debug-output22304 +Node: ENVIRONMENT22524 +Ref: #environment22635 +Node: FILES24058 +Ref: #files24157 +Node: BUGS24417 +Ref: #bugs24494  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 @@ -11,7 +11,7 @@ hledger ui -- [OPTIONS] [QUERYARGS] DESCRIPTION - This manual is for hledger's terminal interface, version 1.29. See + This manual is for hledger's terminal interface, version 1.29.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -598,4 +598,4 @@ -hledger-ui-1.29 March 2023 HLEDGER-UI(1) +hledger-ui-1.29.1 March 2023 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" "March 2023" "hledger-web-1.29 " "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "March 2023" "hledger-web-1.29.1 " "hledger User Manuals" @@ -23,7 +23,7 @@ \f[V]hledger web -- [OPTIONS] [QUERYARGS]\f[R] # start from hledger .SH DESCRIPTION .PP -This manual is for hledger\[aq]s web interface, version 1.29. +This manual is for hledger\[aq]s web interface, version 1.29.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info --- a/embeddedfiles/hledger-web.info +++ b/embeddedfiles/hledger-web.info @@ -18,7 +18,7 @@ ‘hledger-web --serve-api [OPTIONS] # run JSON server only’ ‘hledger web -- [OPTIONS] [QUERYARGS]’ # start from hledger - This manual is for hledger’s web interface, version 1.29. See also + This manual is for hledger’s web interface, version 1.29.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -664,26 +664,26 @@  Tag Table: Node: Top225 -Node: OPTIONS2724 -Ref: #options2829 -Node: PERMISSIONS10623 -Ref: #permissions10762 -Node: EDITING UPLOADING DOWNLOADING12020 -Ref: #editing-uploading-downloading12201 -Node: RELOADING13043 -Ref: #reloading13177 -Node: JSON API13610 -Ref: #json-api13725 -Node: DEBUG OUTPUT19257 -Ref: #debug-output19382 -Node: Debug output19409 -Ref: #debug-output-119510 -Node: ENVIRONMENT19935 -Ref: #environment20055 -Node: FILES21404 -Ref: #files21504 -Node: BUGS21764 -Ref: #bugs21842 +Node: OPTIONS2726 +Ref: #options2831 +Node: PERMISSIONS10625 +Ref: #permissions10764 +Node: EDITING UPLOADING DOWNLOADING12022 +Ref: #editing-uploading-downloading12203 +Node: RELOADING13045 +Ref: #reloading13179 +Node: JSON API13612 +Ref: #json-api13727 +Node: DEBUG OUTPUT19259 +Ref: #debug-output19384 +Node: Debug output19411 +Ref: #debug-output-119512 +Node: ENVIRONMENT19937 +Ref: #environment20057 +Node: FILES21406 +Ref: #files21506 +Node: BUGS21766 +Ref: #bugs21844  End Tag Table diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt --- a/embeddedfiles/hledger-web.txt +++ b/embeddedfiles/hledger-web.txt @@ -13,8 +13,8 @@ hledger web -- [OPTIONS] [QUERYARGS] # start from hledger DESCRIPTION - This manual is for hledger's web interface, version 1.29. See also the - hledger manual for common concepts and file formats. + This manual is for hledger's web interface, version 1.29.1. See also + the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry @@ -608,4 +608,4 @@ -hledger-web-1.29 March 2023 HLEDGER-WEB(1) +hledger-web-1.29.1 March 2023 HLEDGER-WEB(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 --- a/embeddedfiles/hledger.1 +++ b/embeddedfiles/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "March 2023" "hledger-1.29 " "hledger User Manuals" +.TH "HLEDGER" "1" "March 2023" "hledger-1.29.1 " "hledger User Manuals" @@ -26,7 +26,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP -This manual is for hledger\[aq]s command line interface, version 1.29. +This manual is for hledger\[aq]s command line interface, version 1.29.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -23,10948 +23,10948 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger’s command line interface, version 1.29. -It also describes the common options, file formats and concepts used by -all hledger programs. It might accidentally teach you some -bookkeeping/accounting as well! You don’t need to know everything in -here to use hledger productively, but when you have a question about -functionality, this doc should answer it. It is detailed, so do skip -ahead or skim when needed. You can read it on hledger.org, or as an -info manual or man page on your system. You can also get it from -hledger itself with -‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’. - - The main function of the hledger CLI is to read plain text files -describing financial transactions, crunch the numbers, and print a -useful report on the terminal (or save it as HTML, CSV, JSON or SQL). -Many reports are available, as subcommands. hledger will also detect -other ‘hledger-*’ executables as extra subcommands. - - hledger reads data from one or more files in journal, timeclock, -timedot, or CSV format. The default file is ‘.hledger.journal’ in your -home directory; this can be overridden with one or more ‘-f FILE’ -options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can -also read from stdin with ‘-f-’; more on that below. - - Here is a small but valid hledger journal file describing one -transaction: - -2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more -_accounts_: bank accounts, your wallet, revenue/expense categories, -people, etc. You can choose any account names you wish, using ‘:’ to -indicate subaccounts. There must be at least two spaces between account -name and amount. Positive amounts are inflow to that account (_debit_), -negatives are outflow from it (_credit_). (Some reports show revenue, -liability and equity account balances as negative numbers as a result; -this is normal.) - - hledger’s add command can help you add transactions, or you can -install other data entry UIs like hledger-web or hledger-iadd. For more -extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM -+ vim-ledger, or VS Code + hledger-vscode are some good choices (see -https://hledger.org/editors.html). - - To get started, run ‘hledger add’ and follow the prompts, or save -some entries like the above in ‘$HOME/.hledger.journal’, then try -commands like: -‘hledger print -x’ -‘hledger aregister assets’ -‘hledger balance’ -‘hledger balancesheet’ -‘hledger incomestatement’. -Run ‘hledger’ to list the commands. See also the "Starting a journal -file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -* Menu: - -* PART 1 USER INTERFACE:: -* Options:: -* Environment:: -* Input:: -* Commands:: -* Output:: -* Limitations:: -* Troubleshooting:: -* PART 2 DATA FORMATS:: -* Journal:: -* CSV:: -* Timeclock:: -* Timedot:: -* PART 3 REPORTING CONCEPTS:: -* Time periods:: -* Depth:: -* Queries:: -* Pivoting:: -* Generating data:: -* Forecasting:: -* Budgeting:: -* Cost reporting:: -* Valuation:: -* PART 4 COMMANDS:: -* PART 5 COMMON TASKS:: - - -File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top - -1 PART 1: USER INTERFACE -************************ - - -File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top - -2 Options -********* - -* Menu: - -* General options:: -* Command options:: -* Command arguments:: -* Special characters:: -* Unicode characters:: -* 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 or COMMAND help -‘--man’ - - show general or COMMAND user manual with man -‘--info’ - - show general or COMMAND user manual with info -‘--version’ - - show general or ADDONCMD version -‘--debug[=N]’ - - show debug output (levels 1-9, default: 1) - - General input options: - -‘-f FILE --file=FILE’ - - use a different input file. For stdin, use - (default: - ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’) -‘--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’ - - disable balance assertion checks (note: does not disable balance - assignments) -‘-s --strict’ - - do extra error checking (check that all posted accounts are - declared) - - General reporting options: - -‘-b --begin=DATE’ - - include postings/txns on or after this date (will be adjusted to - preceding subperiod start when using a report interval) -‘-e --end=DATE’ - - include postings/txns before this date (will be adjusted to - following subperiod end when using a report interval) -‘-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 -‘--date2’ - - match the secondary date instead (see command help for other - effects) -‘--today=DATE’ - - override today’s date (affects relative smart dates, for - tests/examples) -‘-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/selling amount at transaction time -‘-V --market’ - - convert amounts to their market value in default valuation - commodities -‘-X --exchange=COMM’ - - convert amounts to their market value in commodity COMM -‘--value’ - - convert amounts to cost or market value, more flexibly than - -B/-V/-X -‘--infer-market-prices’ - - use transaction prices (recorded with @ or @@) as additional market - prices, as if they were P directives -‘--auto’ - - apply automated posting rules to modify transactions. -‘--forecast’ - - generate future transactions from periodic transaction rules, for - the next 6 months or till report end date. In hledger-ui, also - make ordinary future transactions visible. -‘--commodity-style’ - - Override the commodity style in the output for the specified - commodity. For example ’EUR1.000,00’. -‘--color=WHEN (or --colour=WHEN)’ - - Should color-supporting commands use ANSI color codes in text - output. ’auto’ (default): whenever stdout seems to be a - color-supporting terminal. ’always’ or ’yes’: always, useful eg - when piping output into ’less -R’. ’never’ or ’no’: never. A - NO_COLOR environment variable overrides this. -‘--pretty[=WHEN]’ - - Show prettier output, e.g. using unicode box-drawing characters. - Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’ - also work). If you provide an argument you must use ’=’, e.g. - ’–pretty=yes’. - - When a reporting option appears more than once in the command line, -the 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 add-on, you may need to put its -options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can -run the add-on executable directly: ‘hledger-ui --watch’. - - -File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options - -2.3 Command arguments -===================== - -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. - - You can save a set of command line options/arguments in a file, and -then reuse them by writing ‘@FILENAME’ as a command line argument. Eg: -‘hledger bal @foo.args’. (To prevent this, eg if you have an argument -that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal --- @ARG’). - - Inside the argument file, each line should contain just one option or -argument. Avoid the use of spaces, except inside quotes (or you’ll see -a confusing error). Between a flag and its argument, use = (or -nothing). Bad: - -assets depth:2 --X USD - - Good: - -assets -depth:2 --X=USD - - For special characters (see below), use one less level of quoting -than you would at the command prompt. Bad: - --X"$" - - Good: - --X$ - - See also: Save frequently used options. - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options - -2.4 Special characters -====================== - -* Menu: - -* Single escaping shell metacharacters:: -* Double escaping regular expression metacharacters:: -* Triple escaping for add-on commands:: -* Less escaping:: - - -File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters - -2.4.1 Single escaping (shell metacharacters) --------------------------------------------- - -In shell command lines, characters significant to your shell - such as -spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped" -if you want hledger to see them. This is done by enclosing them in -single or double quotes, or by writing a backslash before them. Eg to -match an account name containing a space: - -$ hledger register 'credit card' - - or: - -$ hledger register credit\ card - - Windows users should keep in mind that ‘cmd’ treats single quote as a -regular character, so you should be using double quotes exclusively. -PowerShell treats both single and double quotes as quotes. - - -File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters - -2.4.2 Double escaping (regular expression metacharacters) ---------------------------------------------------------- - -Characters significant in regular expressions (described below) - such -as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be -"regex-escaped" if you don’t want them to be interpreted by hledger’s -regular expression engine. This is done by writing backslashes before -them, but since backslash is typically also a shell metacharacter, both -shell-escaping and regex-escaping will be needed. Eg to match a literal -‘$’ sign while using the bash shell: - -$ hledger balance cur:'\$' - - or: - -$ hledger balance cur:\\$ - - -File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters - -2.4.3 Triple escaping (for add-on commands) -------------------------------------------- - -When you use hledger to run an external add-on command (described -below), one level of shell-escaping is lost from any options or -arguments intended for by the add-on command, so those need an extra -level of shell-escaping. Eg to match a literal ‘$’ sign while using the -bash shell and running an add-on command (‘ui’): - -$ hledger ui cur:'\\$' - - or: - -$ hledger ui cur:\\\\$ - - If you wondered why _four_ backslashes, perhaps this helps: - -unescaped: ‘$’ -escaped: ‘\$’ -double-escaped: ‘\\$’ -triple-escaped: ‘\\\\$’ - - Or, you can avoid the extra escaping by running the add-on executable -directly: - -$ hledger-ui cur:\\$ - - -File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters - -2.4.4 Less escaping -------------------- - -Options and arguments are sometimes used in places other than the shell -command line, where shell-escaping is not needed, so there you should -use one less level of escaping. Those places include: - - • an @argumentfile - • hledger-ui’s filter field - • hledger-web’s search form - • GHCI’s prompt (used by developers). - - -File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options - -2.5 Unicode characters -====================== - -hledger is expected to handle non-ascii characters correctly: - - • they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web’s - search/add/edit forms, etc.) - - • they should be displayed correctly by all hledger tools, and - on-screen alignment should be preserved. - - This requires a well-configured environment. Here are some tips: - - • A system locale must be configured, and it must be one that can - decode the characters being used. In bash, you can set a locale - like this: ‘export LANG=en_US.UTF-8’. There are some more details - in Troubleshooting. This step is essential - without it, hledger - will quit on encountering a non-ascii character (as with all - GHC-compiled programs). - - • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode - - • the terminal must be using a font which includes the required - unicode glyphs - - • the terminal should be configured to display wide characters as - double width (for report alignment) - - • on Windows, for best results you should run hledger in the same - kind of environment in which it was built. Eg hledger built in the - standard CMD.EXE environment (like the binaries on our download - page) might show display problems when run in a cygwin or msys - terminal, and vice versa. (See eg #961). - - -File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options - -2.6 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 directive and ‘--alias’ option: ‘alias /REGEX/ = - REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’ - - hledger’s regular expressions come from the regex-tdfa library. If -they’re not doing what you expect, it’s important to know exactly what -they support: - - 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing - being matched) - 3. they are POSIX ERE (extended regular expressions) - 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’) - 5. they do not support backreferences; if you write ‘\1’, it will - match the digit ‘1’. Except when doing text replacement, eg in - account aliases, where backreferences can be used in the - replacement string to reference capturing groups in the search - regexp. - 6. they do not support mode modifiers (‘(?s)’), character classes - (‘\w’, ‘\d’), or anything else not mentioned above. - - 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: Environment, Next: Input, Prev: Options, Up: Top - -3 Environment -************* - -*LEDGER_FILE* The journal file path when not specified with ‘-f’. - - On unix computers, the default value is: ‘~/.hledger.journal’. - - A more typical value is something like ‘~/finance/YYYY.journal’, -where ‘~/finance’ is a version-controlled finance directory and YYYY is -the current year. Or, ‘~/finance/current.journal’, where -current.journal is a symbolic link to YYYY.journal. - - The usual way to set this permanently is to add a command to one of -your shell’s startup files (eg ‘~/.profile’): - -export LEDGER_FILE=~/finance/current.journal` - - On some Mac computers, there is a more thorough way to set -environment variables, that will also affect applications started from -the GUI (eg, Emacs started from a dock icon): In -‘~/.MacOSX/environment.plist’, add an entry like: - -{ - "LEDGER_FILE" : "~/finance/current.journal" -} - - For this to take effect you might need to ‘killall Dock’, or reboot. - - On Windows computers, the default value is probably -‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a -command like this in a powershell window (let us know if you need to be -an Administrator, and if this persists across a reboot): - -> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - - Or, change it in settings: see -https://www.java.com/en/download/help/path.html. - - *COLUMNS* The screen width used by the register command. Default: -the full terminal width. - - *NO_COLOR* If this variable exists with any value, hledger will not -use ANSI color codes in terminal output. This is overriden by the -–color/–colour option. - - -File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top - -4 Input -******* - -hledger reads transactions from one or more data files. The default -data file is ‘$HOME/.hledger.journal’ (or on Windows, something like -‘C:\Users\YOURNAME\.hledger.journal’). - - You can override this with the ‘$LEDGER_FILE’ environment variable: - -$ setenv LEDGER_FILE ~/finance/2016.journal -$ hledger stats - - or with one or more ‘-f/--file’ options: - -$ hledger -f /some/file -f another_file stats - - The file name ‘-’ means standard input: - -$ cat some.journal | hledger -f- - -* Menu: - -* Data formats:: -* Multiple files:: -* Strict mode:: - - -File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input - -4.1 Data formats -================ - -Usually the data file is in hledger’s journal format, but it can be in -any of the supported file formats, which currently are: - -Reader: Reads: Used for file - extensions: --------------------------------------------------------------------------- -‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’ - journals, for transactions ‘.hledger’ ‘.ledger’ -‘timeclock’timeclock files, for precise time ‘.timeclock’ - logging -‘timedot’timedot files, for approximate time ‘.timedot’ - logging -‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’ - values, for data import - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions -shown above. If it can’t recognise the file extension, it assumes -‘journal’ format. So for non-journal files, it’s important to use a -recognised file extension, so as to either read successfully or to show -relevant error messages. - - You can also force a specific reader/format by prefixing the file -path with the format and a colon. Eg, to read a .dat file as csv -format: - -$ hledger -f csv:/some/csv-file.dat stats - - Or to read stdin (‘-’) as timeclock format: - -$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- - - -File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input - -4.2 Multiple files -================== - -You can specify multiple ‘-f’ options, to read multiple files as one big -journal. There are some limitations with this: - - • most directives do not affect sibling files - • balance assertions will not see any account balances from previous - files - - If you need either of those things, you can - - • use a single parent file which includes the others - • or concatenate the files into one before reading, eg: ‘cat - a.journal b.journal | hledger -f- CMD’. - - -File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input - -4.3 Strict mode -=============== - -hledger checks input files for valid data. By default, the most -important errors are detected, while still accepting easy journal files -without a lot of declarations: - - • Are the input files parseable, with valid syntax ? - • Are all transactions balanced ? - • Do all balance assertions pass ? - - With the ‘-s’/‘--strict’ flag, additional checks are performed: - - • Are all accounts posted to, declared with an ‘account’ directive ? - (Account error checking) - • Are all commodities declared with a ‘commodity’ directive ? - (Commodity error checking) - • Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks – the ones -listed above and some more. - - -File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top - -5 Commands -********** - -hledger provides a number of built-in subcommands (described below). -Most of these read your data without changing it, and display a report. -A few assist with data entry and management. - - Run ‘hledger’ with no arguments to list the commands available, and -‘hledger CMD’ to run a command. CMD can be the full command name, or -its standard abbreviation shown in the commands list, or any unambiguous -prefix of the name. Eg: ‘hledger bal’. - -* Menu: - -* Add-on commands:: - - -File: hledger.info, Node: Add-on commands, Up: Commands - -5.1 Add-on commands -=================== - -Add-on commands are extra subcommands provided by programs or scripts in -your PATH - - • whose name starts with ‘hledger-’ - • whose name ends with a recognised file extension: - ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’ - or none - • and (on unix, mac) which are executable by the current user. - - Addons can be written in any language, but haskell scripts or -programs have a big advantage: they can use hledger’s library code, for -command-line options, parsing and reporting. - - Several add-on commands are installed by the hledger-install script. -See https://hledger.org/scripts.html for more details. - - Note in a hledger command line, add-on command flags must have a -double dash (‘--’) preceding them. Eg you must write: - -$ hledger web -- --serve - - and not: - -$ hledger web --serve - - (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’). - - The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’. - - If you have any trouble with this, remember you can always run the -add-on program directly, eg: - -$ hledger-web --serve - - -File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top - -6 Output -******** - -* Menu: - -* Output destination:: -* Output format:: -* Commodity styles:: -* Colour:: -* Box-drawing:: -* Debug output:: - - -File: hledger.info, Node: Output destination, Next: Output format, Up: Output - -6.1 Output destination -====================== - -hledger commands send their output to the terminal by default. You can -of course redirect this, eg into a file, using standard shell syntax: - -$ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also -provide the ‘-o/--output-file’ option, which does the same thing without -needing the shell. Eg: - -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) - - -File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output - -6.2 Output format -================= - -Some commands offer other kinds of output, not just text on the -terminal. Here are those commands and the formats currently supported: - -- txt csv html json sql ------------------------------------------------------------------------------ -aregister Y Y Y Y -balance Y _1_ Y _1_ Y _1,2_ Y -balancesheet Y _1_ Y _1_ Y _1_ Y -balancesheetequity Y _1_ Y _1_ Y _1_ Y -cashflow Y _1_ Y _1_ Y _1_ Y -incomestatement Y _1_ Y _1_ Y _1_ Y -print Y Y Y Y -register Y Y Y - - • _1 Also affected by the balance commands’ ‘--layout’ option._ - • _2 ‘balance’ does not support html output without a report interval - or with ‘--budget’._ - - The output format is selected by the ‘-O/--output-format=FMT’ option: - -$ hledger print -O csv # print CSV on stdout - - or by the filename extension of an output file specified with the -‘-o/--output-file=FILE.FMT’ option: - -$ hledger balancesheet -o foo.csv # write CSV to foo.csv - - The ‘-O’ option can be combined with ‘-o’ to override the file -extension, if needed: - -$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - - Some notes about the various output formats: - -* Menu: - -* CSV output:: -* HTML output:: -* JSON output:: -* SQL output:: - - -File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format - -6.2.1 CSV output ----------------- - - • In CSV output, digit group marks (such as thousands separators) are - disabled automatically. - - -File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format - -6.2.2 HTML output ------------------ - - • HTML output can be styled by an optional ‘hledger.css’ file in the - same directory. - - -File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format - -6.2.3 JSON output ------------------ - - • This is not yet much used; real-world feedback is welcome. - - • Our JSON is rather large and verbose, since it is a faithful - representation of hledger’s internal data types. To understand the - JSON, read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. - - • hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can - arise in practice (from automatically-calculated transaction - prices), and would break most JSON consumers. So in JSON, we show - quantities as simple Numbers with at most 10 decimal places. We - don’t limit the number of integer digits, but that part is under - your control. We hope this approach will not cause problems in - practice; if you find otherwise, please let us know. (Cf #1195) - - -File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format - -6.2.4 SQL output ----------------- - - • This is not yet much used; real-world feedback is welcome. - - • SQL output is expected to work with sqlite, MySQL and PostgreSQL - - • SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables - created via SQL output of hledger, you would probably want to - either clear tables of existing data (via ‘delete’ or ‘truncate’ - SQL statements) or drop tables completely as otherwise your - postings will be duped. - - -File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output - -6.3 Commodity styles -==================== - -When displaying amounts, hledger infers a standard display style for -each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a ‘-c/--commodity-style’ option -(except for cost amounts and amounts displayed by the ‘print’ command, -which are always displayed with all decimal digits). For example, the -following will force dollar amounts to be displayed as shown: - -$ hledger print -c '$1.000,0' - - This option can repeated to set the display style for multiple -commodities/currencies. Its argument is as described in the commodity -directive. - - -File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output - -6.4 Colour -========== - -In terminal output, some commands can produce colour when the terminal -supports it: - - • if the ‘--color/--colour’ option is given a value of ‘yes’ or - ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used; - • otherwise, if the ‘NO_COLOR’ environment variable is set, colour - will not be used; - • otherwise, colour will be used if the output (terminal or file) - supports it. - - -File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output - -6.5 Box-drawing -=============== - -In terminal output, you can enable unicode box-drawing characters to -render prettier tables: - - • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or - ‘no’ or ‘never’), unicode characters will (or will not) be used; - • otherwise, unicode characters will not be used. - - -File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output - -6.6 Debug output -================ - -We intend hledger to be relatively easy to troubleshoot, introspect and -develop. You can add ‘--debug[=N]’ to any hledger command line to see -additional debug output. N ranges from 1 (least output, the default) to -9 (maximum output). Typically you would start with 1 and increase until -you are seeing enough. Debug output goes to stderr, and is not affected -by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg: -‘2>&1’). It will be interleaved with normal output, which can help -reveal when parts of the code are evaluated. To capture debug output in -a log file instead, you can usually redirect stderr, eg: - -hledger bal --debug=3 2>hledger.log - - -File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top - -7 Limitations -************* - -The need to precede add-on 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. - - On Windows, non-ascii characters may not display correctly when -running a hledger built in CMD in MSYS/CYGWIN, or vice-versa. - - 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 hledger -and Ledger > Differences > journal format. - - On large data files, hledger is slower and uses more memory than -Ledger. - - -File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top - -8 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. - - *Getting errors like "Illegal byte sequence" or "Invalid or -incomplete multibyte or wide character" or "commitAndReleaseBuffer: -invalid argument (invalid character)"* -Programs compiled with GHC (hledger, haskell build tools, etc.) need to -have a UTF-8-aware locale configured in the environment, otherwise they -will fail with these kinds of errors when they encounter non-ascii -characters. - - To fix it, set the LANG environment variable to some locale which -supports UTF-8. The locale you choose must be installed on your system. - - Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux: - -$ file my.journal -my.journal: UTF-8 Unicode text # the file is UTF8-encoded -$ echo $LANG -C # LANG is set to the default locale, which does not support UTF8 -$ locale -a # which locales are installed ? -C -en_US.utf8 # here's a UTF8-aware one we can use -POSIX -$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command - - If available, ‘C.UTF-8’ will also work. If your preferred locale -isn’t listed by ‘locale -a’, you might need to install it. Eg on -Ubuntu/Debian: - -$ 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 - - Here’s how you could set it permanently, if you use a bash shell: - -$ echo "export LANG=en_US.utf8" >>~/.bash_profile -$ bash --login - - Exact spelling and capitalisation may be important. Note the -difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu) -allow variant spellings, but others (eg macos) require it to be exact: - -$ locale -a | grep -iE en_us.*utf -en_US.UTF-8 -$ LANG=en_US.UTF-8 hledger -f my.journal print - - -File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top - -9 PART 2: DATA FORMATS -********************** - - -File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top - -10 Journal -********** - -hledger’s default file format, representing a General Journal. Here’s a -cheatsheet/mini-tutorial, or you can skip ahead to About journal format. - -* Menu: - -* Journal cheatsheet:: -* About journal format:: -* Comments:: -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Transaction comments:: -* Postings:: -* Account names:: -* Amounts:: -* Costs:: -* Balance assertions:: -* Posting comments:: -* Tags:: -* Directives:: -* account directive:: -* alias directive:: -* commodity directive:: -* decimal-mark directive:: -* include directive:: -* P directive:: -* payee directive:: -* tag directive:: -* Periodic transactions:: -* Other syntax:: - - -File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal - -10.1 Journal cheatsheet -======================= - -# Here is the main syntax of hledger's journal format -# (omitting extra Ledger compatibility syntax). -# hledger journals contain comments, directives, and transactions, in any order: - -############################################################################### -# 1. Comment lines are for notes or temporarily disabling things. -# They begin with #, ;, or a line containing the word "comment". - -# hash comment line -; semicolon comment line -comment -These lines -are commented. -end comment - -# Some but not all hledger entries can have same-line comments attached to them, -# from ; (semicolon) to end of line. - -############################################################################### -# 2. Directives modify parsing or reports in some way. -# They begin with a word or letter (or symbol). - -account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. -account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) -alias chkg = assets:checking -commodity $0.00 -decimal-mark . -include /dev/null -payee Whole Foods -P 2022-01-01 AAAA $1.40 -~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - -############################################################################### -# 3. Transactions are what it's all about; they are dated events, -# usually describing movements of money. -# They begin with a date. - -# DATE DESCRIPTION ; This is a transaction comment. -# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. -# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. -# ; ^^ At least 2 spaces between account and amount. -# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - -2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - -2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - -Kv -2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - -2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - -2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - -1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - -2022.01.01 These date -2022/1/1 formats are -12/31 also allowed (but consistent YYYY-MM-DD is recommended). - - -File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal - -10.2 About journal format -========================= - -hledger’s usual data source is a plain text file containing journal -entries in hledger journal format. This file represents a standard -accounting general journal. I use file names ending in ‘.journal’, but -that’s not required. The journal file contains a number of transaction -entries, each describing a transfer of money (or any commodity) between -two or more named accounts, in a simple format readable by both hledger -and humans. - - hledger’s journal format is a compatible subset, mostly, of ledger’s -journal format, so hledger can work with compatible ledger journal files -as well. It’s safe, and encouraged, to run both hledger and ledger on -the same journal file, eg to validate the results you’re getting. - - You can use hledger without learning any more about this file; just -use the add or web or import commands to create and update it. - - Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor addons -such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and -hledger-vscode for Visual Studio Code, make this easier, adding colour, -formatting, tab completion, and useful commands. See Editor -configuration at hledger.org for the full list. - - Here’s a description of each part of the file format (and hledger’s -data model). - - A hledger journal file can contain three kinds of thing: file -comments, transactions, and/or directives (counting periodic transaction -rules and auto posting rules as directives). - - -File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal - -10.3 Comments -============= - -Lines in the journal will be ignored if they begin with a hash (‘#’) or -a semicolon (‘;’). (See also Other syntax.) hledger will also ignore -regions beginning with a ‘comment’ line and ending with an ‘end comment’ -line (or file end). Here’s a suggestion for choosing between them: - - • ‘#’ for top-level notes - • ‘;’ for commenting out things temporarily - • ‘comment’ for quickly commenting large regions (remember it’s - there, or you might get confused) - - Eg: - -# a comment line -; another commentline -comment -A multi-line comment block, -continuing until "end comment" directive -or the end of the current file. -end comment - - Some hledger entries can have same-line comments attached to them, -from ; (semicolon) to end of line. See Transaction comments, Posting -comments, and Account comments below. - - -File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal - -10.4 Transactions -================= - -Transactions are the main unit of information in a journal file. They -represent events, typically a movement of some quantity of commodities -between two or more named accounts. - - Each transaction is recorded as a journal entry, beginning with a -simple date in column 0. This can be followed by any of the following -optional fields, separated by spaces: - - • a status character (empty, ‘!’, or ‘*’) - • a code (any short number or text, enclosed in parentheses) - • a description (any remaining text until end of line or a semicolon) - • a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - • 0 or more indented _posting_ lines, describing what was transferred - and the accounts involved (indented comment lines are also allowed, - but not blank lines or non-indented lines). - - Here’s a simple journal file containing one transaction: - -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - -File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal - -10.5 Dates -========== - -* Menu: - -* Simple dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates - -10.5.1 Simple dates -------------------- - -Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or -‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may -be omitted, in which case it will be inferred from the context: the -current transaction, the default year set with a ‘Y’ directive, or the -current date when the command is run. Some examples: ‘2010-01-31’, -‘2010/01/31’, ‘2010.1.31’, ‘1/31’. - - (The UI also accepts simple dates, as well as the more flexible smart -dates documented in the hledger manual.) - - -File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates - -10.5.2 Posting dates --------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like ‘date:DATE’. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction’s date. -The ‘date:’ tag must have a valid simple date value if it is present, eg -a ‘date:’ tag with no value is not allowed. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal - -10.6 Status -=========== - -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: - -mark status - ------------------ - unmarked -‘!’ pending -‘*’ cleared - - When reporting, you can filter by status with the ‘-U/--unmarked’, -‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’, -and ‘status:*’ queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" -state is called "uncleared". As of hledger 1.3 we have renamed it to -unmarked for clarity. - - To replicate Ledger and old hledger’s behaviour of also matching -pending, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. Some editor modes provide highlighting and -shortcuts for working with status. Eg in Emacs ledger-mode, you can -toggle transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to -you. Here’s one suggestion: - -status meaning --------------------------------------------------------------------------- -uncleared recorded but not yet reconciled; needs review -pending tentatively reconciled (if needed, eg during a big - reconciliation) -cleared complete, reconciled as far as possible, and considered - correct - - With this scheme, you would use ‘-PC’ to see the current balance at -your bank, ‘-U’ to see things which will probably hit your bank soon -(like uncashed checks), and no flags to see the most up-to-date state of -your finances. - - -File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal - -10.7 Code -========= - -After the status mark, but before the description, you can optionally -write a transaction "code", enclosed in parentheses. This is a good -place to record a check number, or some other important transaction id -or reference number. - - -File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal - -10.8 Description -================ - -A transaction’s description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -10.8.1 Payee and note ---------------------- - -You can optionally include a ‘|’ (pipe) character in descriptions to -subdivide the description into separate fields for payee/payer name on -the left (up to the first ‘|’) and an additional note field on the right -(after the first ‘|’). This may be worthwhile if you need to do more -precise querying and pivoting by payee or by note. - - -File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal - -10.9 Transaction comments -========================= - -Text following ‘;’, after a transaction description, and/or on indented -lines immediately below it, form comments for that transaction. They -are reproduced by ‘print’ but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal - -10.10 Postings -============== - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - • (optional) a status character (empty, ‘!’, or ‘*’), followed by a - space - • (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - • (optional) *two or more spaces* or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are -being removed. - - The amounts within a transaction must always sum up to zero. As a -convenience, one amount may be left blank; it will be inferred so as to -balance the transaction. - - Be sure to note the unusual two-space delimiter between account name -and amount. This makes it easy to write account names containing -spaces. But if you accidentally leave only one space (or tab) before -the amount, the amount will be considered part of the account name. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal - -10.11 Account names -=================== - -Accounts are the main way of categorising things in hledger. As in -Double Entry Bookkeeping, they can represent real world accounts (such -as a bank account), or more abstract categories such as "money borrowed -from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are ‘assets’, -‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these -referred to as A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. For example, from the account names ‘assets:bank:checking’ -and ‘expenses:food’, hledger will infer this hierarchy of five accounts: - -assets -assets:bank -assets:bank:checking -expenses -expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - -assets - bank - checking -expenses - food - - hledger reports can summarise the account tree to any depth, so you -can go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. Note, when an account name and an -amount are written on the same line, they must be separated by *two or -more spaces* (or tabs). - - Parentheses or brackets enclosing the full account name indicate -virtual postings, described below. Parentheses or brackets internal to -the account name have no special meaning. - - Account names can be altered temporarily or permanently by account -aliases. - - -File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal - -10.12 Amounts -============= - -After the account name, there is usually an amount. (Important: between -account name and amount, there must be *two or more spaces*.) - - hledger’s amount format is flexible, supporting several international -formats. Here are some examples. Amounts have a number (the -"quantity"): - -1 - - ..and usually a currency symbol or commodity name (more on this -below), to the left or right of the quantity, with or without a -separating space: - -$1 -4000 AAPL -3 "green apples" - - Amounts can be preceded by a minus sign (or a plus sign, though plus -is the default), The sign can be written before or after a left-side -commodity symbol: - --$1 -$-1 - - One or more spaces between the sign and the number are acceptable -when parsing (but they won’t be displayed in output): - -+ $1 -$- 1 - - Scientific E notation is allowed: - -1E-6 -EUR 1E3 - -* Menu: - -* Decimal marks digit group marks:: -* Commodity:: -* Directives influencing number parsing and display:: -* Commodity display style:: -* Rounding:: - - -File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts - -10.12.1 Decimal marks, digit group marks ----------------------------------------- - -A _decimal mark_ can be written as a period or a comma: - -1.23 -1,23456780000009 - - In the integer part of the quantity (left of the decimal mark), -groups of digits can optionally be separated by a _digit group mark_ - a -space, comma, or period (different from the decimal mark): - - $1,000,000.00 - EUR 2.000.000,00 -INR 9,99,99,999.00 - 1 000 000.9455 - - Note, a number containing a single digit group mark and no decimal -mark is ambiguous. Are these digit group marks or decimal marks ? - -1,000 -1.000 - - If you don’t tell it otherwise, hledger will assume both of the above -are decimal marks, parsing both numbers as 1. - - To prevent confusing parsing mistakes and undetected typos, -especially if your data contains digit group marks (eg, thousands -separators), we recommend explicitly declaring the decimal mark -character in each journal file, using a directive at the top of the -file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’ -directives will also work. These are described below. - - -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts - -10.12.2 Commodity ------------------ - -Amounts in hledger have both a "quantity", which is a signed decimal -number, and a "commodity", which is a currency symbol, stock ticker, or -any word or phrase describing something you are tracking. - - If the commodity name contains non-letters (spaces, numbers, or -punctuation), you must always write it inside double quotes (‘"green -apples"’, ‘"ABC123"’). - - If you write just a bare number, that too will have a commodity, with -name ‘""’; we call that the "no-symbol commodity". - - Actually, hledger combines these single-commodity amounts into more -powerful multi-commodity amounts, which are what it works with most of -the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456 -TSLA’. In practice, you will only see multi-commodity amounts in -hledger’s output; you can’t write them directly in the journal file. - - (If you are writing scripts or working with hledger’s internals, -these are the ‘Amount’ and ‘MixedAmount’ types.) - - -File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts - -10.12.3 Directives influencing number parsing and display ---------------------------------------------------------- - -You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to -declare and control these things more explicitly and precisely. These -are described below, but here’s a quick example: - -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 - - -File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts - -10.12.4 Commodity display style -------------------------------- - -For the amounts in each commodity, hledger chooses a consistent display -style to use in most reports. (Exceptions: price amounts, and all -amounts displayed by the ‘print’ command, are displayed with all of -their decimal digits visible.) - - A commodity’s display style is inferred as follows. - - First, if a default commodity is declared with ‘D’, this commodity -and its style is applied to any no-symbol amounts in the journal. - - Then each commodity’s style is inferred from one of the following, in -order of preference: - - • The commodity directive for that commodity (including the no-symbol - commodity), if any. - • The amounts in that commodity seen in the journal’s transactions. - (Posting amounts only; prices and periodic or auto rules are - ignored, currently.) - • The built-in fallback style, which looks like this: ‘$1000.00’. - (Symbol on the left, period decimal mark, two decimal places.) - - A style is inferred from journal amounts as follows: - - • Use the general style (decimal mark, symbol placement) of the first - amount - • Use the first-seen digit group style (digit group mark, digit group - sizes), if any - • Use the maximum number of decimal places of all. - - Cost amounts don’t affect the commodity display style directly, but -occasionally they can do so indirectly (eg when a posting’s amount is -inferred using a cost). If you find this causing problems, use a -commodity directive to fix the display style. - - To summarise: each commodity’s amounts will be normalised to (a) the -style declared by a ‘commodity’ directive, or (b) the style of the first -posting amount in the journal, with the first-seen digit group style and -the maximum-seen number of decimal places. So if your reports are -showing amounts in a way you don’t like, eg with too many decimal -places, use a commodity directive. Some examples: - -# declare euro, dollar, bitcoin and no-symbol commodities and set their -# input number formats and output display styles: -commodity EUR 1.000, -commodity $1000.00 -commodity 1000.00000000 BTC -commodity 1 000. - - The inferred commodity style can be overridden by supplying a command -line option. - - -File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts - -10.12.5 Rounding ----------------- - -Amounts are stored internally as decimal numbers with up to 255 decimal -places, and displayed with the number of decimal places specified by the -commodity display style. Note, hledger uses banker’s rounding: it -rounds to the nearest even number, eg 0.5 displayed with zero decimal -places is "0"). - - -File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal - -10.13 Costs -=========== - -After a posting amount, you can note its cost (when buying) or selling -price (when selling) in another commodity, by writing either ‘@ -UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion -transaction, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, -discussions, or code; that term was directionally neutral and reminded -that it is a price specific to a transaction, but we now just call it -"cost", with the understanding that the transaction could be a purchase -or a sale.) - - Costs are usually written explicitly with ‘@’ or ‘@@’, but can also -be inferred automatically for simple multi-commodity transactions. -Note, if costs are inferred, the order of postings is significant; the -first posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign -currency in hledger, using the cost notation either explicitly or -implicitly: - - 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction. - Note the effect of posting order: the price is added to first - posting, making it ‘€100 @@ $135’, as in example 2: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the ‘-B/--cost’ -flag; this is discussed more in the ˜COST REPORTING section. - -* Menu: - -* Other cost/lot notations:: - - -File: hledger.info, Node: Other cost/lot notations, Up: Costs - -10.13.1 Other cost/lot notations --------------------------------- - -A slight digression for Ledger and Beancount users. Ledger has a number -of cost/lot-related notations: - - • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ - • expresses a conversion rate, as in hledger - • when buying, also creates a lot than can be selected at - selling time - - • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost) - • like the above, but also means "this cost was exceptional, - don’t use it when inferring market prices". - - Currently, hledger treats the above like ‘@’ and ‘@@’; the -parentheses are ignored. - - • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price) - • when buying, means "this cost is also the fixed price, don’t - let it fluctuate in value reports" - - • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price) - • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’, - also creates a lot - • when selling, combined with ‘@ ...’, specifies an investment - lot by its cost basis; does not check if that lot is present - - • and related: ‘[YYYY/MM/DD]’ (lot date) - • when buying, attaches this acquisition date to the lot - • when selling, selects a lot by its acquisition date - - • ‘(SOME TEXT)’ (lot note) - • when buying, attaches this note to the lot - • when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. (This can break transaction -balancing.) - - For Beancount users, the notation and behaviour is different: - - • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ - • expresses a cost without creating a lot, as in hledger - • when buying (augmenting) or selling (reducing) a lot, combined - with ‘{...}’: documents the cost/selling price (not used for - transaction balancing) - - • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ - • when buying (augmenting), expresses the cost for transaction - balancing, and also creates a lot with this cost basis - attached - • when selling (reducing), - • selects a lot by its cost basis - • raises an error if that lot is not present or can not be - selected unambiguously (depending on booking method - configured) - • expresses the selling price for transaction balancing - - Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation -but ignores it. - - • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST, - "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc. - - Currently, hledger rejects these. - - -File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal - -10.14 Balance assertions -======================== - -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s -amount. Eg here we assert the expected dollar balance in accounts a and -b after each posting: - -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the ‘-I/--ignore-assertions’ flag, which can be useful for -troubleshooting or for reading Ledger files. (Note: this flag currently -does not disable balance assignments, described below). - -* Menu: - -* Assertions and ordering:: -* Assertions and multiple included files:: -* Assertions and multiple -f files:: -* Assertions and commodities:: -* Assertions and prices:: -* Assertions and subaccounts:: -* Assertions and virtual postings:: -* Assertions and auto postings:: -* Assertions and precision:: - - -File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions - -10.14.1 Assertions and ordering -------------------------------- - -hledger sorts an account’s postings and assertions first by date and -then (for postings on the same day) by parse order. Note this is -different from Ledger, which sorts assertions only by parse order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder -differently-dated transactions within the journal. But if you reorder -same-dated transactions or postings, assertions might break and require -updating. This order dependence does bring an advantage: precise -control over the order of postings and assertions within a day, so you -can assert intra-day balances. - - -File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions - -10.14.2 Assertions and multiple included files ----------------------------------------------- - -Multiple files included with the ‘include’ directive are processed as if -concatenated into one file, preserving their order and the posting order -within each file. It means that balance assertions in later files will -see balance from earlier files. - - And if you have multiple postings to an account on the same day, -split across multiple files, and you want to assert the account’s -balance on that day, you’ll need to put the assertion in the right file -- the last one in the sequence, probably. - - -File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions - -10.14.3 Assertions and multiple -f files ----------------------------------------- - -Unlike ‘include’, when multiple files are specified on the command line -with multiple ‘-f/--file’ options, balance assertions will not see -balance from earlier files. This can be useful when you do not want -problems in earlier files to disrupt valid assertions in later files. - - If you do want assertions to see balance from earlier files, use -‘include’, or concatenate the files temporarily. - - -File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions - -10.14.4 Assertions and commodities ----------------------------------- - -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity’s balance within the -(possibly multi-commodity) account balance. This is how assertions work -in Ledger also. We could call this a "partial" balance assertion. - - To assert the balance of more than one commodity in an account, you -can write multiple postings, each asserting one commodity’s balance. - - You can make a stronger "total" balance assertion by writing a double -equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no -other commodities in the account besides the asserted one (or at least, -that their balance is 0). - -2013/1/1 - a $1 - a 1€ - b $-1 - c -1€ - -2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1€ - b 0 == $-1 - c 0 == -1€ - -2013/1/3 ; This assertion fails as 'a' also contains 1€ - a 0 == $1 - - It’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: - -2013/1/1 - a:usd $1 - a:euro 1€ - b - -2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1€ - - -File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions - -10.14.5 Assertions and prices ------------------------------ - -Balance assertions ignore costs, 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.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions - -10.14.6 Assertions and subaccounts ----------------------------------- - -The balance assertions above (‘=’ and ‘==’) do not count the balance -from subaccounts; they check the account’s exclusive balance only. You -can assert the balance including subaccounts by writing ‘=*’ or ‘==*’, -eg: - -2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 - - -File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions - -10.14.7 Assertions and virtual postings ---------------------------------------- - -Balance assertions always consider both real and virtual postings; they -are not affected by the ‘--real/-R’ flag or ‘real:’ query. - - -File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions - -10.14.8 Assertions and auto postings ------------------------------------- - -Balance assertions _are_ affected by the ‘--auto’ flag, which generates -auto postings, which can alter account balances. Because auto postings -are optional in hledger, accounts affected by them effectively have two -balances. But balance assertions can only test one or the other of -these. So to avoid making fragile assertions, either: - - • assert the balance calculated with ‘--auto’, and always use - ‘--auto’ with that file - • or assert the balance calculated without ‘--auto’, and never use - ‘--auto’ with that file - • or avoid balance assertions on accounts affected by auto postings - (or avoid auto postings entirely). - - -File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions - -10.14.9 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.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal - -10.15 Posting comments -====================== - -Text following ‘;’, at the end of a posting line, and/or on indented -lines immediately below it, form comments for that posting. They are -reproduced by ‘print’ but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - -File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal - -10.16 Tags -========== - -Tags are a way to add extra labels or labelled data to transactions, -postings, or accounts, which you can then search or pivot on. - - They are written as a word (optionally hyphenated) immediately -followed by a full colon, in a transaction or posting or account -directive’s comment. (This is an exception to the usual rule that -things in comments are ignored.) Eg, here four different tags are -recorded: one on the checking account, two on the transaction, and one -on the expenses posting: - -account assets:checking ; accounttag: - -2017/1/16 bought groceries ; transactiontag-1: - ; transactiontag-2: - assets:checking $-1 - expenses:food $1 ; postingtag: - - Postings also inherit tags from their transaction and their account. -And transactions also acquire tags from their postings (and postings’ -accounts). So in the example above, the expenses posting effectively -has all four tags (by inheriting from account and transaction), and the -transaction also has all four tags (by acquiring from the expenses -posting). - - You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by -tag name with a ‘tag:NAMEREGEX’ query. - -* Menu: - -* Tag values:: - - -File: hledger.info, Node: Tag values, Up: Tags - -10.16.1 Tag values ------------------- - -Tags can have a value, which is any text after the colon up until a -comma or end of line (with surrounding whitespace removed). Note this -means that hledger tag values can not contain commas. Eg in the -following posting, the three tags’ values are "value 1", "value 2", and -"" (empty) respectively: - - expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - - Note that tags can be repeated, and are additive rather than -overriding: when the same tag name is seen again with a new value, the -new name:value pair is added to the tags. (It is not possible to -override a tag’s value or remove a tag.) - - You can list a tag’s values with ‘hledger tags TAGNAME --values’, or -match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query. - - -File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal - -10.17 Directives -================ - -A directive is a line in the journal beginning with a special keyword, -that influences how the journal is processed, how things are displayed, -and so on. hledger’s directives are based on (a subset of) Ledger’s, -but there are many differences, and also some differences between -hledger versions. Here are some more definitions: - - • _subdirective_ - Some directives support subdirectives, written - indented below the parent directive. - - • _decimal mark_ - The character to interpret as a decimal mark - (period or comma) when parsing amounts of a commodity. - - • _display style_ - How to display amounts of a commodity in output: - symbol side and spacing, digit groups, decimal mark, and number of - decimal places. - - Directives are not required when starting out with hledger, but you -will probably want to add some as your needs grow. Here some key -directives for particular needs: - -purpose directives --------------------------------------------------------------------------- -*READING DATA:* -Declare file’s decimal mark to help parse ‘decimal-mark’ -amounts accurately -Rewrite account names ‘alias’ -Comment out sections of the data ‘comment’ -Include extra data files ‘include’ -*GENERATING DATA:* -Generate recurring transactions or budget ‘~’ -goals -Generate extra postings on transactions ‘=’ -*CHECKING FOR ERRORS:* -Define valid entities to provide more ‘account’, ‘commodity’, -error checking ‘payee’ -*REPORTING:* -Declare accounts’ type and display order ‘account’ -Declare commodity display styles ‘commodity’ -Declare market prices ‘P’ - -* Menu: - -* Directive effects:: -* Directives and multiple files:: - - -File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives - -10.17.1 Directive effects -------------------------- - -And here is what each directive does, and which files and journal -entries (transactions) it affects: - -directivewhat it does ends - at - file - end? ---------------------------------------------------------------------------- -*‘account’*Declares an account, for checking all entries in all files; andN - its display order and type. Subdirectives: any text, ignored. -*‘alias’*Rewrites account names, in following entries until end of Y - current file or ‘end aliases’. Command line equivalent: - ‘--alias’ -*‘comment’*Ignores part of the journal file, until end of current file orY - ‘end comment’. -*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N - all amounts in all files 2. the decimal mark for parsing - amounts of this commodity, in the following entries until end of - current file (if there is no ‘decimal-mark’ directive) 3. and - the display style for amounts of this commodity 4. which is - also the precision to use for balanced-transaction checking in - this commodity. Takes precedence over ‘D’. Subdirectives: - ‘format’ (Ledger-compatible syntax). Command line equivalent: - ‘-c/--commodity-style’ -*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y - commodities in following entries until next ‘decimal-mark’ or - end of current file. Included files can override. Takes - precedence over ‘commodity’ and ‘D’. -*‘include’*Includes entries and directives from another file, as if theyN - were written inline. Command line alternative: multiple - ‘-f/--file’ -*‘payee’*Declares a payee name, for checking all entries in all files. N -*‘P’*Declares the market price of a commodity on some date, for value N - reports. -*‘~’*Declares a periodic transaction rule that generates future N -(tilde)transactions with ‘--forecast’ and budget goals with ‘balance - --budget’. -Other -syntax: -*‘applyPrepends a common parent account to all account names, in Y -account’*following entries until end of current file or ‘end apply - account’. -*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no ‘commodity’ directive for this commodity: its - decimal mark, balancing precision, and display style, as above. -*‘Y’*Sets a default year to use for any yearless dates, in following Y - entries until end of current file. -*‘=’*Declares an auto posting rule that generates extra postings on partly -(equals)matched transactions with ‘--auto’, in current, parent, and - child files (but not sibling files, see #1212). -*OtherOther directives from Ledger’s file format are accepted but -Ledgerignored. -directives* - - -File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives - -10.17.2 Directives and multiple files -------------------------------------- - -If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive, -hledger will process multiple input files. But directives which affect -input typically have effect only until the end of the file in which they -occur (and on any included files in that region). - - This may seem inconvenient, but it’s intentional; it makes reports -stable and deterministic, independent of the order of input. Otherwise -you could see different numbers if you happened to write -f options in a -different order, or if you moved includes around while cleaning up your -files. - - It can be surprising though; for example, it means that ‘alias’ -directives do not affect parent or sibling files (see below). - - -File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal - -10.18 ‘account’ directive -========================= - -‘account’ directives can be used to declare accounts (ie, the places -that amounts are transferred from and to). Though not required, these -declarations can provide several benefits: - - • They can document your intended chart of accounts, providing a - reference. - • In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - • They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - • They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - • They can store additional account information as comments, or as - tags which can be used to filter or pivot reports. - • They can help hledger know your accounts’ types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - - They are written as the word ‘account’ followed by a hledger-style -account name, eg: - -account assets:bank:checking - - Note, however, that accounts declared in account directives are not -allowed to have surrounding brackets and parentheses, unlike accounts -used in postings. So the following journal will not parse: - -account (assets:bank:checking) - -* Menu: - -* Account comments:: -* Account subdirectives:: -* Account error checking:: -* Account display order:: -* Account types:: - - -File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive - -10.18.1 Account comments ------------------------- - -Text following *two or more spaces* and ‘;’ at the end of an account -directive line, and/or following ‘;’ on indented lines immediately below -it, form comments for that account. They are ignored except they may -contain tags, which are not ignored. - - The two-space requirement for same-line account comments is because -‘;’ is allowed in account names. - -account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - -File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive - -10.18.2 Account subdirectives ------------------------------ - -Ledger-style indented subdirectives are also accepted, but currently -ignored: - -account assets:bank:checking - format subdirective is ignored - - -File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive - -10.18.3 Account error checking ------------------------------- - -By default, accounts need not be declared; they come into existence when -a posting references them. This is convenient, but it means hledger -can’t warn you when you mis-spell an account name in the journal. -Usually you’ll find that error later, as an extra account in balance -reports, or an incorrect balance when reconciling. - - In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will -report an error if any transaction uses an account name that has not -been declared by an account directive. Some notes: - - • The declaration is case-sensitive; transactions must use the - correct account name capitalisation. - • The account directive’s scope is "whole file and below" (see - directives). This means it affects all of the current file, and - any files it includes, but not parent or sibling files. The - position of account directives within the file does not matter, - though it’s usual to put them at the top. - • Accounts can only be declared in ‘journal’ files, but will affect - included files of all types. - • It’s currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - -File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive - -10.18.4 Account display order ------------------------------ - -The order in which account directives are written influences the order -in which accounts appear in reports, hledger-ui, hledger-web etc. By -default accounts appear in alphabetical order, but if you add these -account directives to the journal file: - -account assets -account liabilities -account equity -account revenues -account expenses - - those accounts will be displayed in declaration order: - -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses - - Any undeclared accounts are displayed last, in alphabetical order. - - 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 - • sibling accounts stay together (you couldn’t display ‘x:y’ in - between ‘a:b’ and ‘a:c’). - - -File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive - -10.18.5 Account types ---------------------- - -hledger knows that accounts come in several types: assets, liabilities, -expenses and so on. This enables easy reports like balancesheet and -incomestatement, and filtering by account type with the ‘type:’ query. - - As a convenience, hledger will detect these account types -automatically if you are using common english-language top-level account -names (described below). But generally we recommend you declare types -explicitly, by adding a ‘type:’ tag to your top-level account -directives. Subaccounts will inherit the type of their parent. The -tag’s value should be one of the five main account types: - - • ‘A’ or ‘Asset’ (things you own) - • ‘L’ or ‘Liability’ (things you owe) - • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of - assets & liabilities) - • ‘R’ or ‘Revenue’ (what you received money from, AKA income; - technically part of Equity) - • ‘X’ or ‘Expense’ (what you spend money on; technically part of - Equity) - - or, it can be (these are used less often): - - • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the - cashflow report) - • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST - REPORTING).) - - Here is a typical set of account type declarations: - -account assets ; type: A -account liabilities ; type: L -account equity ; type: E -account revenues ; type: R -account expenses ; type: X - -account assets:bank ; type: C -account assets:cash ; type: C - -account equity:conversion ; type: V - - Here are some tips for working with account types. - - • The rules for inferring types from account names are as follows. - These are just a convenience that sometimes help new users get - going; if they don’t work for you, just ignore them and declare - your account types. See also Regular expressions. - - If account's name contains this (CI) regular expression: | its type is: - --------------------------------------------------------------------|------------- - ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash - ^assets?(:|$) | Asset - ^(debts?|liabilit(y|ies))(:|$) | Liability - ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion - ^equity(:|$) | Equity - ^(income|revenue)s?(:|$) | Revenue - ^expenses?(:|$) | Expense - - • If you declare any account types, it’s a good idea to declare an - account for all of the account types, because a mixture of declared - and name-inferred types can disrupt certain reports. - - • Certain uses of account aliases can disrupt account types. See - Rewriting accounts > Aliases and account types. - - • As mentioned above, subaccounts will inherit a type from their - parent account. More precisely, an account’s type is decided by - the first of these that exists: - - 1. A ‘type:’ declaration for this account. - 2. A ‘type:’ declaration in the parent accounts above it, - preferring the nearest. - 3. An account type inferred from this account’s name. - 4. An account type inferred from a parent account’s name, - preferring the nearest parent. - 5. Otherwise, it will have no type. - - • For troubleshooting, you can list accounts and their types with: - - $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] - - -File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal - -10.19 ‘alias’ directive -======================= - -You can define account alias rules which rewrite your account names, or -parts of them, before generating reports. This can be useful for: - - • expanding shorthand account names to their full form, allowing - easier data entry and a less verbose journal - • adapting old journals to your current chart of accounts - • experimenting with new account organisations, like a new hierarchy - • combining two accounts into one, eg to see their sum or difference - on one line - • customising reports - - Account aliases also rewrite account names in account directives. -They do not affect account names being entered via hledger add or -hledger-web. - - Account aliases are very powerful. They are generally easy to use -correctly, but you can also generate invalid account names with them; -more on this below. - - See also Rewrite account names. - -* Menu: - -* Basic aliases:: -* Regex aliases:: -* Combining aliases:: -* Aliases and multiple files:: -* end aliases directive:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive - -10.19.1 Basic aliases ---------------------- - -To set an account alias, use the ‘alias’ directive in your journal file. -This affects all subsequent journal entries in the current file or its -included files (but note: not sibling or parent files). The spaces -around the = are optional: - -alias OLD = NEW - - Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line. -This affects all entries. It’s useful for trying out aliases -interactively. - - OLD and NEW are case sensitive full account names. hledger will -replace any occurrence of the old account name with the new one. -Subaccounts are also affected. Eg: - -alias checking = assets:bank:wells fargo:checking -; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - -File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive - -10.19.2 Regex aliases ---------------------- - -There is also a more powerful variant that uses a regular expression, -indicated by wrapping the pattern in forward slashes. (This is the only -place where hledger requires forward slashes around a regular -expression.) - - Eg: - -alias /REGEX/ = REPLACEMENT - - or: - -$ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by -REPLACEMENT. REGEX is case-insensitive as usual. - - If you need to match a forward slash, escape it with a backslash, eg -‘/\/=:’. - - If REGEX contains parenthesised match groups, these can be referenced -by the usual backslash and number in REPLACEMENT: - -alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 -; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - REPLACEMENT continues to the end of line (or on command line, to end -of option argument), so it can contain trailing whitespace. - - -File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive - -10.19.3 Combining aliases -------------------------- - -You can define as many aliases as you like, using journal directives -and/or command line options. - - Recursive aliases - where an account name is rewritten by one alias, -then by another alias, and so on - are allowed. Each alias sees the -effect of previously applied aliases. - - In such cases it can be important to understand which aliases will be -applied and in which order. For (each account name in) each journal -entry, we apply: - - 1. ‘alias’ directives preceding the journal entry, most recently - parsed first (ie, reading upward from the journal entry, bottom to - top) - 2. ‘--alias’ options, in the order they appeared on the command line - (left to right). - - In other words, for (an account name in) a given journal entry: - - • the nearest alias declaration before/above the entry is applied - first - • the next alias before/above that will be be applied next, and so on - • aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps -provide semantic stability - aliases will keep working the same way -independent of which files are being read and in which order. - - In case of trouble, adding ‘--debug=6’ to the command line will show -which aliases are being applied when. - - -File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive - -10.19.4 Aliases and multiple files ----------------------------------- - -As explained at Directives and multiple files, ‘alias’ directives do not -affect parent or sibling files. Eg in this command, - -hledger -f a.aliases -f b.journal - - account aliases defined in a.aliases will not affect b.journal. -Including the aliases doesn’t work either: - -include a.aliases - -2020-01-01 ; not affected by a.aliases - foo 1 - bar - - This means that account aliases should usually be declared at the -start of your top-most file, like this: - -alias foo=Foo -alias bar=Bar - -2020-01-01 ; affected by aliases above - foo 1 - bar - -include c.journal ; also affected - - -File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive - -10.19.5 ‘end aliases’ directive -------------------------------- - -You can clear (forget) all currently defined aliases (seen in the -journal so far, or defined on the command line) with this directive: - -end aliases - - -File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive - -10.19.6 Aliases can generate bad account names ----------------------------------------------- - -Be aware that account aliases can produce malformed account names, which -could cause confusing reports or invalid ‘print’ output. For example, -you could erase all account names: - -2021-01-01 - a:aa 1 - b - -$ hledger print --alias '/.*/=' -2021-01-01 - 1 - - The above ‘print’ output is not a valid journal. Or you could insert -an illegal double space, causing ‘print’ output that would give a -different journal when reparsed: - -2021-01-01 - old 1 - other - -$ hledger print --alias old="new USD" | hledger -f- print -2021-01-01 - new USD 1 - other - - -File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive - -10.19.7 Aliases and account types ---------------------------------- - -If an account with a type declaration (see Declaring accounts > Account -types) is renamed by an alias, normally the account type remains in -effect. - - However, renaming in a way that reshapes the account tree (eg -renaming parent accounts but not their children, or vice versa) could -prevent child accounts from inheriting the account type of their -parents. - - Secondly, if an account’s type is being inferred from its name, -renaming it by an alias could prevent or alter that. - - If you are using account aliases and the ‘type:’ query is not -matching accounts as you expect, try troubleshooting with the accounts -command, eg something like: - -$ hledger accounts --alias assets=bassetts type:a - - -File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal - -10.20 ‘commodity’ directive -=========================== - -You can use ‘commodity’ directives to declare your commodities. In fact -the ‘commodity’ directive performs several functions at once: - - 1. It declares commodities which may be used in the journal. This can - optionally be enforced, providing useful error checking. (Cf - Commodity error checking) - - 2. It declares which decimal mark character (period or comma), to - expect when parsing input - useful to disambiguate international - number formats in your data. Without this, hledger will parse both - ‘1,000’ and ‘1.000’ as 1. (Cf Amounts) - - 3. It declares how to render the commodity’s amounts when displaying - output - the decimal mark, any digit group marks, the number of - decimal places, symbol placement and so on. (Cf Commodity display - style) - - You will run into one of the problems solved by commodity directives -sooner or later, so we recommend using them, for robust and predictable -parsing and display. - - Generally you should put them at the top of your journal file (since -for function 2, they affect only following amounts, cf #793). - - A commodity directive is just the word ‘commodity’ followed by a -sample amount, like this: - -;commodity SAMPLEAMOUNT - -commodity $1000.00 -commodity 1,000.0000 AAAA ; optional same-line comment - - It may also be written on multiple lines, and use the ‘format’ -subdirective, as in Ledger. Note in this case the commodity symbol -appears twice; it must be the same in both places: - -;commodity SYMBOL -; format SAMPLEAMOUNT - -; display indian rupees with currency name on the left, -; thousands, lakhs and crores comma-separated, -; period as decimal point, and two decimal places. -commodity INR - format INR 1,00,00,000.00 - - Other indented subdirectives are currently ignored. - - Remember that if the commodity symbol contains spaces, numbers, or -punctuation, it must be enclosed in double quotes (cf Commodity). - - The amount’s quantity does not matter; only the format is -significant. It must include a decimal mark - either a period or a -comma - followed by 0 or more decimal digits. - - A few more examples: - -# number formats for $, EUR, INR and the no-symbol commodity: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.0 -commodity 1 000 000. - - Note hledger normally uses banker’s rounding, so 0.5 displayed with -zero decimal digits is "0". (More at Commodity display style.) - - Even in the presence of commodity directives, the commodity display -style can still be overridden by supplying a command line option. - -* Menu: - -* Commodity error checking:: - - -File: hledger.info, Node: Commodity error checking, Up: commodity directive - -10.20.1 Commodity error checking --------------------------------- - -In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will -report an error if a commodity symbol is used that has not been declared -by a ‘commodity’ directive. This works similarly to account error -checking, see the notes there for more details. - - Note, this disallows amounts without a commodity symbol, because -currently it’s not possible (?) to declare the "no-symbol" commodity -with a directive. This is one exception for convenience: zero amounts -are always allowed to have no commodity symbol. - - -File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal - -10.21 ‘decimal-mark’ directive -============================== - -You can use a ‘decimal-mark’ directive - usually one per file, at the -top of the file - to declare which character represents a decimal mark -when parsing amounts in this file. It can look like - -decimal-mark . - - or - -decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we -recommend it, especially if the file contains digit group marks (eg -thousands separators). - - -File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal - -10.22 ‘include’ directive -========================= - -You can pull in the content of additional files by writing an include -directive, like this: - -include FILEPATH - - Only journal files can include, and only journal, timeclock or -timedot files can be included (not CSV files, currently). - - If the file path does not begin with a slash, it is relative to the -current file’s folder. - - A tilde means home directory, eg: ‘include ~/main.journal’. - - The path may contain glob patterns to match multiple files, eg: -‘include *.journal’. - - There is limited support for recursive wildcards: ‘**/’ (the slash is -required) matches 0 or more subdirectories. It’s not super convenient -since you have to avoid include cycles and including directories, but -this can be done, eg: ‘include */**/*.journal’. - - The path may also be prefixed to force a specific file format, -overriding the file extension (as described in hledger.1 -> Input -files): ‘include timedot:~/notes/2020*.md’. - - -File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal - -10.23 ‘P’ directive -=================== - -The ‘P’ directive declares a market price, which is a conversion rate -between two commodities on a certain date. This allows value reports to -convert amounts of one commodity to their value in another, on or after -that date. These prices are often obtained from a stock exchange, -cryptocurrency exchange, the or foreign exchange market. - - The format is: - -P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the -commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and -quantity) of commodity 2 that one unit of commodity 1 is worth on this -date. Examples: - -# one euro was worth $1.35 from 2009-01-01 onward: -P 2009-01-01 € $1.35 - -# and $1.40 from 2010-01-01 onward: -P 2010-01-01 € $1.40 - - The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show -amount values in another commodity. See Valuation. - - -File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal - -10.24 ‘payee’ directive -======================= - -‘payee PAYEE NAME’ - - This directive can be used to declare a limited set of payees which -may appear in transaction descriptions. The "payees" check will report -an error if any transaction refers to a payee that has not been -declared. Eg: - -payee Whole Foods - - Any indented subdirectives are currently ignored. - - -File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal - -10.25 ‘tag’ directive -===================== - -‘tag TAGNAME’ - - This directive can be used to declare a limited set of tag names -allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - -tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is -used. It is quite easy to accidentally create a tag through normal use -of colons in comments(#comments]; if you want to prevent this, you can -declare and check your tags . - - -File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal - -10.26 Periodic transactions -=========================== - -The ‘~’ directive declares recurring transactions. Such directives -allow hledger to generate temporary future transactions (visible in -reports, not in the journal file) to help with forecasting or budgeting. - - Periodic transactions can be a little tricky, so before you use them, -read this whole section, or at least these tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - 2. For troubleshooting, show the generated transactions with ‘hledger - print --forecast tag:generated’ or ‘hledger register --forecast - tag:generated’. - 3. Forecasted transactions will begin only after the last - non-forecasted transaction’s date. - 4. Forecasted transactions will end 6 months from today, by default. - See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs - improvement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in ‘weekly from DATE’, DATE - must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give - an error. - 7. Other period expressions with an interval are automatically - expanded to cover a whole number of that interval. (This is done - to improve reports, but it also affects periodic transactions. - Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th - day of month from 2020/01’, which is equivalent to ‘~ every 10th - day of month from 2020/01/01’, will be adjusted to start on - 2019/12/10. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -10.26.1 Periodic rule syntax ----------------------------- - -A periodic transaction rule looks like a normal journal entry, with the -date replaced by a tilde (‘~’) followed by a period expression -(mnemonic: ‘~’ looks like a recurring sine wave.): - -# every first of month -~ monthly - expenses:rent $2000 - assets:bank:checking - -# every 15th of month in 2023's first quarter: -~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying -multi-period reports, just interpreted differently; there, it specifies -report periods; here it specifies recurrence dates (the periods’ start -dates). - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -10.26.2 Periodic rules and relative dates ------------------------------------------ - -Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’, -‘next quarter’) are usually not recommended in periodic rules, since the -results will change as time passes. If used, they will be interpreted -relative to, in order of preference: - - 1. the first day of the default year specified by a recent ‘Y’ - directive - 2. or the date specified with ‘--today’ - 3. or the date on which you are running the report. - - They will not be affected at all by report period or forecast period -dates. - - -File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions - -10.26.3 Two spaces between period expression and description! -------------------------------------------------------------- - -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 - - So, - - • Do write two spaces between your period expression and your - transaction description, if any. - • Don’t accidentally write two spaces in the middle of your period - expression. - - -File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal - -10.27 Other syntax -================== - -hledger journal format supports quite a few other features, mainly to -make interoperating with or converting from Ledger easier. Note some of -the features below are powerful and can be useful in special cases, but -in general, features in this section are considered less important or -even not recommended for most users. Downsides are mentioned to help -you decide if you want to use them. - -* Menu: - -* Auto postings:: -* Balance assignments:: -* Bracketed posting dates:: -* D directive:: -* apply account directive:: -* Y directive:: -* Secondary dates:: -* Star comments:: -* Valuation expressions:: -* Virtual postings:: -* Other Ledger directives:: - - -File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax - -10.27.1 Auto postings ---------------------- - -The ‘=’ directive declares a rule for automatically adding temporary -extra postings (visible in reports, not in the journal file) to all -transactions matched by a certain query, when you use the ‘--auto’ flag. - - Downsides: depending on generated data for your reports makes your -financial data less portable, less future-proof, and less trustworthy in -an audit. Also, because the feature is optional, other features like -balance assertions can break depending on whether it is on or off. - - An auto posting rule looks a bit like a transaction: - -= QUERY - ACCOUNT AMOUNT - ... - ACCOUNT [AMOUNT] - - except the first line is an equals sign (mnemonic: ‘=’ suggests -matching), followed by a query (which matches existing postings), and -each "posting" line describes a posting to be generated, and the posting -amounts can be: - - • a normal amount with a commodity symbol, eg ‘$2’. This will be - used as-is. - • a number, eg ‘2’. The commodity symbol (if any) from the matched - posting will be added to this. - • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The - matched posting’s amount (and total price, if any) will be - multiplied by N. - • a multiplier with a commodity symbol, eg ‘*$2’ (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. - - Any query term containing spaces must be enclosed in single or double -quotes, as on the command line. Eg, note the quotes around the second -query term below: - -= expenses:groceries 'expenses:dining out' - (budget:funds:dining out) *-1 - - Some examples: - -; every time I buy food, schedule a dollar donation -= expenses:food - (liabilities:charity) $-1 - -; when I buy a gift, also deduct that amount from a budget envelope subaccount -= expenses:gifts - assets:checking:gifts *-1 - assets:checking *1 - -2017/12/1 - expenses:food $10 - assets:checking - -2017/12/14 - expenses:gifts $20 - assets:checking - -$ hledger print --auto -2017-12-01 - expenses:food $10 - assets:checking - (liabilities:charity) $-1 - -2017-12-14 - expenses:gifts $20 - assets:checking - assets:checking:gifts -$20 - assets:checking $20 - -* Menu: - -* Auto postings and multiple files:: -* Auto postings and dates:: -* Auto postings and transaction balancing / inferred amounts / balance assertions:: -* Auto posting tags:: - - -File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings - -10.27.1.1 Auto postings and multiple files -.......................................... - -An auto posting rule can affect any transaction in the current file, or -in any parent file or child file. Note, currently it will not affect -sibling files (when multiple ‘-f’/‘--file’ are used - see #1212). - - -File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings - -10.27.1.2 Auto postings and dates -................................. - -A posting date (or secondary date) in the matched posting, or (taking -precedence) a posting date in the auto posting rule itself, will also be -used in the generated posting. - - -File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings - -10.27.1.3 Auto postings and transaction balancing / inferred -............................................................ - -amounts / balance assertions Currently, 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. - - This also means that you cannot have more than one auto-posting with -a missing amount applied to a given transaction, as it will be unable to -infer amounts. - - -File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings - -10.27.1.4 Auto posting tags -........................... - -Automated postings will have some extra tags: - - • ‘generated-posting:= QUERY’ - shows this was generated by an auto - posting rule, and the query - • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear - in hledger’s output. This can be used to match postings generated - "just now", rather than generated in the past and saved to the - journal. - - Also, any transaction that has been changed by auto posting rules -will have these tags added: - - • ‘modified:’ - this transaction was modified - • ‘_modified:’ - a hidden tag not appearing in the comment; this - transaction was modified "just now". - - -File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax - -10.27.2 Balance assignments ---------------------------- - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account’s balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). - - Downsides: using balance assignments makes your journal less -explicit; to know the exact amount posted, you have to run hledger or do -the calculations yourself, instead of just reading it. Also balance -assignments’ forcing of balances can hide errors. These things make -your financial data less portable, less future-proof, and less -trustworthy in an audit. - -* Menu: - -* Balance assignments and prices:: - - -File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments - -10.27.2.1 Balance assignments and prices -........................................ - -A cost 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.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax - -10.27.3 Bracketed posting dates -------------------------------- - -For setting posting dates and secondary posting dates, Ledger’s -bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or -‘[=DATE2]’ in posting comments. hledger will attempt to parse any -square-bracketed sequence of the ‘0123456789/-.=’ characters in this -way. With this syntax, DATE infers its year from the transaction and -DATE2 infers its year from DATE. - - Downsides: another syntax to learn, redundant with hledger’s -‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date -syntax. - - -File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax - -10.27.4 ‘D’ directive ---------------------- - -‘D AMOUNT’ - - This directive sets a default commodity, to be used for any -subsequent commodityless amounts (ie, plain numbers) seen while parsing -the journal. This effect lasts until the next ‘D’ directive, or the end -of the journal. - - For compatibility/historical reasons, ‘D’ also acts like a -‘commodity’ directive (setting the commodity’s decimal mark for parsing -and display style for output). So its argument is not just a commodity -symbol, but a full amount demonstrating the style. The amount must -include a decimal mark (either period or comma). Eg: - -; commodity-less amounts should be treated as dollars -; (and displayed with the dollar sign on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity’s display style, a ‘commodity’ directive has -highest priority, then a ‘D’ directive. - - For detecting a commodity’s decimal mark during parsing, -‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’. - - For checking commodity symbols with the check command, a ‘commodity’ -directive is required (‘hledger check commodities’ ignores ‘D’ -directives). - - Downsides: omitting commodity symbols makes your financial data less -explicit, less portable, and less trustworthy in an audit. It is -usually an unsustainable shortcut; sooner or later you will want to -track multiple commodities. D is overloaded with functions redundant -with ‘commodity’ and ‘decimal-mark’. And it works differently from -Ledger’s ‘D’. - - -File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax - -10.27.5 ‘apply account’ directive ---------------------------------- - -This directive sets a default parent account, which will be prepended to -all accounts in following entries, until an ‘end apply account’ -directive or end of current file. Eg: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - ‘account’ directives are also affected, and so is any ‘include’d -content. - - Account names entered via hledger add or hledger-web are not -affected. - - Account aliases, if any, are applied after the parent account is -prepended. - - Downsides: this can make your financial data less explicit, less -portable, and less trustworthy in an audit. - - -File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax - -10.27.6 ‘Y’ directive ---------------------- - -‘Y YEAR’ - - or (deprecated backward-compatible forms): - - ‘year YEAR’ ‘apply year YEAR’ - - The space is optional. This sets a default year to be used for -subsequent dates which don’t specify a year. Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -year 2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at -least) makes your financial data less explicit, less portable, and less -trustworthy in an audit. Such dates can get separated from their -corresponding Y directive, eg when evaluating a region of the journal in -your editor. A missing Y directive makes reports dependent on today’s -date. - - -File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax - -10.27.7 Secondary dates ------------------------ - -A secondary date is written after the primary date, following an equals -sign. If the year is omitted, the primary date’s year is assumed. When -running reports, the primary (left) date is used by default, but with -the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary -(right) date will be used instead. - - The meaning of secondary dates is up to you, but it’s best to follow -a consistent rule. Eg "primary = the bank’s clearing date, secondary = -date the transaction was initiated, if different". - - Downsides: makes your financial data more complicated, less portable, -and less trustworthy in an audit. Keeping the meaning of the two dates -consistent requires discipline, and you have to remember which reporting -mode is appropriate for a given report. Posting dates are simpler and -better. - - -File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax - -10.27.8 Star comments ---------------------- - -Lines beginning with ‘*’ (star/asterisk) are also comment lines. This -feature allows Emacs users to insert org headings in their journal, -allowing them to fold/unfold/navigate it like an outline when viewed -with org mode. - - Downsides: another, unconventional comment syntax to learn. -Decreases your journal’s portability. And switching to Emacs org mode -just for folding/unfolding meant losing the benefits of ledger mode; -nowadays you can add outshine mode to ledger mode to get folding without -losing ledger mode’s features. - - -File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax - -10.27.9 Valuation expressions ------------------------------ - -Ledger allows a valuation function or value to be written in double -parentheses after an amount. hledger ignores these. - - -File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax - -10.27.10 Virtual postings -------------------------- - -A posting with parentheses around the account name is called a _virtual -posting_ or _unbalanced posting_, which means it is exempt from the -usual rule that a transaction’s postings must balance add up to zero. - - This is not part of double entry bookkeeping, so you might choose to -avoid this feature. Or you can use it sparingly for certain special -cases where it can be convenient. Eg, you could set opening balances -without using a balancing equity account: - -2022-01-01 opening balances - (assets:checking) $1000 - (assets:savings) $2000 - - A posting with brackets around the account name is called a _balanced -virtual posting_. The balanced virtual postings in a transaction must -add up to zero (separately from other postings). Eg: - -2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Postings whose account names are neither parenthesised nor bracketed -are called _real postings_. You can exclude virtual postings from -reports with the ‘-R/--real’ flag or a ‘real:1’ query. - - Downsides: violates double entry bookkeeping, can be used to avoid -figuring out correct entries, makes your financial data less portable -and less trustworthy in an audit. - - -File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax - -10.27.11 Other Ledger directives --------------------------------- - -These other Ledger directives are currently accepted but ignored. This -allows hledger to read more Ledger files, but be aware that hledger’s -reports may differ from Ledger’s if you use these. - -apply fixed COMM AMT -apply tag TAG -assert EXPR -bucket / A ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR -end apply fixed -end apply tag -end apply year -end tag -eval / expr EXPR -python - PYTHONCODE -tag NAME -value EXPR ---command-line-flags - - See also https://hledger.org/ledger.html for a detailed -hledger/Ledger syntax comparison. - - -File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top - -11 CSV -****** - -hledger can read CSV files (Character Separated Value - usually comma, -semicolon, or tab) containing dated records, automatically converting -each record into a transaction. - - (To learn about _writing_ CSV, see CSV output.) - - For best error messages when reading CSV/TSV/SSV files, make sure -they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use -a hledger file prefix (see File Extension below). - - Each CSV file must be described by a corresponding _rules file_. -This contains rules describing the CSV data (header line, fields layout, -date format etc.), how to construct hledger transactions from it, and -how to categorise transactions based on description or other attributes. - - By default hledger looks for a rules file named like the CSV file -with an extra ‘.rules’ extension, in the same directory. Eg when asked -to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can -specify a different rules file with the ‘--rules-file’ option. If no -rules file is found, hledger will create a sample rules file, which -you’ll need to adjust. - - At minimum, the rules file must identify the date and amount fields, -and often it also specifies the date format and how many header lines -there are. Here’s a simple CSV file and a rules file for it: - -Date, Description, Id, Amount -12/11/2019, Foo, 123, 10.23 - -# basic.csv.rules -skip 1 -fields date, description, , amount -date-format %d/%m/%Y - -$ hledger print -f basic.csv -2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There’s an introductory Importing CSV data tutorial on hledger.org, -and more CSV rules examples below, and a larger collection at -https://github.com/simonmichael/hledger/tree/master/examples/csv. - -* Menu: - -* CSV rules cheatsheet:: -* separator:: -* skip:: -* date-format:: -* timezone:: -* newest-first:: -* intra-day-reversed:: -* decimal-mark:: -* fields list:: -* Field assignment:: -* Field names:: -* if block:: -* Matchers:: -* if table:: -* balance-type:: -* include:: -* Working with CSV:: -* CSV rules examples:: - - -File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV - -11.1 CSV rules cheatsheet -========================= - -The following kinds of rule can appear in the rules file, in any order. -(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.) - -*‘separator’* declare the field separator, instead of - relying on file extension -*‘skip’* skip one or more header lines at start of file -*‘date-format’* declare how to parse CSV dates/date-times -*‘timezone’* declare the time zone of ambiguous CSV - date-times -*‘newest-first’* improve txn order when: there are multiple - records, newest first, all with the same date -*‘intra-day-reversed’* improve txn order when: same-day txns are in - opposite order to the overall file -*‘decimal-mark’* declare the decimal mark used in CSV amounts, - when ambiguous -*‘fields’ list* name CSV fields for easy reference, and - optionally assign their values to hledger - fields -*Field assignment* assign a CSV value or interpolated text value - to a hledger field -*‘if’ block* conditionally assign values to hledger fields, - or ‘skip’ a record or ‘end’ (skip rest of - file) -*‘if’ table* conditionally assign values to hledger fields, - using compact syntax -*‘balance-type’* select which type of balance - assertions/assignments to generate -*‘include’* inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are -evaluated. - - -File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV - -11.2 ‘separator’ -================ - -You can use the ‘separator’ rule to read other kinds of -character-separated data. The argument is any single separator -character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for -comma-separated values (CSV): - -separator , - - or for semicolon-separated values (SSV): - -separator ; - - or for tab-separated values (TSV): - -separator TAB - - If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a -‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be -inferred automatically, and you won’t need this rule. - - -File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV - -11.3 ‘skip’ -=========== - -skip N - - The word ‘skip’ followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines at the start of the input -data. (Empty/blank lines are skipped automatically, so you don’t need -to count those.) You’ll need this whenever your CSV data contains -header lines. Header lines skipped in this way are ignored, and not -parsed as CSV. - - ‘skip’ can also be used inside if blocks (described below), to skip -individual data records. Note records skipped in this way are still -required to be valid CSV, even though otherwise ignored. - - -File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV - -11.4 ‘date-format’ -================== - -date-format DATEFMT - - This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV -dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, -you’ll need to add a date-format rule describing them with a -strptime-style date parsing pattern - see -https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. -The pattern must parse the CSV date value completely. Some examples: - -# MM/DD/YY -date-format %m/%d/%y - -# D/M/YYYY -# The - makes leading zeros optional. -date-format %-d/%-m/%Y - -# YYYY-Mmm-DD -date-format %Y-%h-%d - -# M/D/YYYY HH:MM AM some other junk -# Note the time and junk must be fully parsed, though only the date is used. -date-format %-m/%-d/%Y %l:%M %p some other junk - - -File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV - -11.5 ‘timezone’ -=============== - -timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone -other than yours, but containing no explicit time zone information, you -can use this rule to declare the CSV’s native time zone, which helps -prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don’t -need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’, -‘%Ez’; see the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware -conversion, localising the CSV date-times to your current system time -zone. If you prefer to localise to some other time zone, eg for -reproducibility, you can (on unix at least) set the output timezone with -the TZ environment variable, eg: - -$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - ‘timezone’ currently does not understand timezone names, except -"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". -For others, use numeric format: +HHMM or -HHMM. - - -File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV - -11.6 ‘newest-first’ -=================== - -hledger tries to ensure that the generated transactions will be ordered -chronologically, including intra-day transactions. Usually it can -auto-detect how the CSV records are ordered. But if it encounters CSV -where all records are on the same date, it assumes that the records are -oldest first. If in fact the CSV’s records are normally newest first, -like: - -2022-10-01, txn 3... -2022-10-01, txn 2... -2022-10-01, txn 1... - - you can add the ‘newest-first’ rule to help hledger generate the -transactions in correct order. - -# same-day CSV records are newest first -newest-first - - -File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV - -11.7 ‘intra-day-reversed’ -========================= - -CSV records for each day are sometimes ordered in reverse compared to -the overall date order. Eg, here dates are newest first, but the -transactions on each date are oldest first: - -2022-10-02, txn 3... -2022-10-02, txn 4... -2022-10-01, txn 1... -2022-10-01, txn 2... - - In this situation, add the ‘intra-day-reversed’ rule, and hledger -will compensate, improving the order of transactions. - -# transactions within each day are reversed with respect to the overall date order -intra-day-reversed - - -File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV - -11.8 ‘decimal-mark’ -=================== - -decimal-mark . - - or: - -decimal-mark , - - hledger automatically accepts either period or comma as a decimal -mark when parsing numbers (cf Amounts). However if any numbers in the -CSV contain digit group marks, such as thousand-separating commas, you -should declare the decimal mark explicitly with this rule, to avoid -misparsed numbers. - - -File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV - -11.9 ‘fields’ list -================== - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word ‘fields’ followed by comma-separated field -names) is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say - ‘%SomeField’ instead of remembering ‘%13’. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger’s fields and - build a transaction. - - Here’s an example that says "use the 1st, 2nd and 4th fields as the -transaction’s date, description and amount; name the last two fields for -later reference; and ignore the others": - -fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to -the CSV file’s separator. Also: - - • There must be least two items in the list (at least one comma). - • Field names may not contain spaces. Spaces before/after field - names are optional. - • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen). - • Fields you don’t care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it’s convenient to use these for -your field names, suitably modified (eg lower-cased with spaces replaced -by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning -to a hledger field with the same name. Eg you could call the CSV’s -"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’ -field (and generating a balance assertion). - - -File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV - -11.10 Field assignment -====================== - -HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to -hledger fields. They can be used instead of or in addition to a fields -list (see above). - - To assign a value to a hledger field, write the field name (any of -the standard hledger field/pseudo-field names, defined below), a space, -followed by a text value on the same line. This text value may -interpolate CSV fields, referenced by their 1-based position in the CSV -record (‘%N’), or by the name they were given in the fields list -(‘%CSVFIELD’). - - Some examples: - -# set the amount to the 4th CSV field, with " USD" appended -amount %4 USD - -# combine three fields to make a comment, containing note: and date: tags -comment note: %somefield - %anotherfield, date: %1 - - Tips: - - • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’ - becomes ‘1’ when interpolated) (#1051). - • Interpolations always refer to a CSV field - you can’t interpolate - a hledger field. (See Referencing other fields below). - - -File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV - -11.11 Field names -================= - -Note the two kinds of field names mentioned here, and used only in -hledger CSV rules files: - - 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally - name the CSV columns for easy reference (since hledger doesn’t yet - automatically recognise column headings in a CSV file), by writing - arbitrary names in a ‘fields’ list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you - must set at least some of these to generate the hledger transaction - from a CSV record, by writing them as the left hand side of a field - assignment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a ‘fields’ list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what -happens when you assign values to them: - -* Menu: - -* date field:: -* date2 field:: -* status field:: -* code field:: -* description field:: -* comment field:: -* account field:: -* amount field:: -* currency field:: -* balance field:: - - -File: hledger.info, Node: date field, Next: date2 field, Up: Field names - -11.11.1 date field ------------------- - -Assigning to ‘date’ sets the transaction date. - - -File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names - -11.11.2 date2 field -------------------- - -‘date2’ sets the transaction’s secondary date, if any. - - -File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names - -11.11.3 status field --------------------- - -‘status’ sets the transaction’s status, if any. - - -File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names - -11.11.4 code field ------------------- - -‘code’ sets the transaction’s code, if any. - - -File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names - -11.11.5 description field -------------------------- - -‘description’ sets the transaction’s description, if any. - - -File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names - -11.11.6 comment field ---------------------- - -‘comment’ sets the transaction’s comment, if any. - - ‘commentN’, where N is a number, sets the Nth posting’s comment. - - You can assign multi-line comments by writing literal ‘\n’ in the -code. A comment starting with ‘\n’ will begin on a new line. - - Comments can contain tags, as usual. - - -File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names - -11.11.7 account field ---------------------- - -Assigning to ‘accountN’, where N is 1 to 99, sets the account name of -the Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you’ll want to set ‘account1’ -and ‘account2’. Typically ‘account1’ is associated with the CSV file, -and is set once with a top-level assignment, while ‘account2’ is set -based on each transaction’s description, in conditional rules. - - If a posting’s account name is left unset but its amount is set (see -below), a default account name will be chosen (like "expenses:unknown" -or "income:unknown"). - - -File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names - -11.11.8 amount field --------------------- - -There are several "amount" field name variants, useful for different -situations: - - • ‘amountN’ sets the amount of the Nth posting, and causes that - posting to be generated. By assigning to ‘amount1’, ‘amount2’, ... - etc. you can generate up to 99 postings. Posting numbers don’t - have to be consecutive; in certain situations using a high number - might be helpful to influence the layout of postings. - - • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair, - when and only when the amount must be obtained from two CSV fields. - Eg when the CSV has separate Debit and Credit fields instead of a - single Amount field. Note: - - • Don’t think "-in is for the first posting and -out is for the - second posting" - that’s not correct. Think: "‘amountN-in’ - and ‘amountN-out’ together detect the amount for posting N, by - inspecting two CSV fields at once." - • hledger assumes both CSV fields are unsigned, and will - automatically negate the -out value. - • It also expects that at least one of the values is empty or - zero, so it knows which one to ignore. If that’s not the case - you’ll need an if rule (see Setting amounts below). - - • ‘amount’, with no posting number (and similarly, ‘amount-in’ and - ‘amount-out’ with no number) are an older syntax. We keep them for - backwards compatibility, and because they have special behaviour - that is sometimes convenient: - - • They set the amount of posting 1 and (negated) the amount of - posting 2. - • Posting 2’s amount will be converted to cost if it has a cost - price. - • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or - ‘amount2-in’ and ‘amount2-out’) will take precedence. This - allows incrementally migrating old rules files to the new - syntax. - - There’s more to say about amount-setting that doesn’t fit here; -please see also "Setting amounts" below. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -11.11.9 currency field ----------------------- - -‘currency’ sets a currency symbol, to be prepended to all postings’ -amounts. You can use this if the CSV amounts do not have a currency -symbol, eg if it is in a separate column. - - ‘currencyN’ prepends a currency symbol to just the Nth posting’s -amount. - - -File: hledger.info, Node: balance field, Prev: currency field, Up: Field names - -11.11.10 balance field ----------------------- - -‘balanceN’ sets a balance assertion amount (or if the posting amount is -left empty, a balance assignment) on posting N. - - ‘balance’ is a compatibility spelling for hledger <1.17; it is -equivalent to ‘balance1’. - - You can adjust the type of assertion/assignment with the -‘balance-type’ rule (see below). - - See Tips below for more about setting amounts and currency. - - -File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV - -11.12 ‘if’ block -================ - -Rules can be applied conditionally, depending on patterns in the CSV -data. This allows flexibility; in particular, it is how you can -categorise transactions, selecting an appropriate account name based on -their description (for example). There are two ways to write -conditional rules: "if blocks", described here, and "if tables", -described below. - - An if block is the word ‘if’ and one or more "matcher" expressions -(can be a word or phrase), one per line, starting either on the same or -next line; followed by one or more indented rules. Eg, - -if MATCHER - RULE - - or - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be -applied. They are usually field assignments, but the following special -rules may also be used within an if block: - - • ‘skip’ - skips the matched CSV record (generating no transaction - from it) - • ‘end’ - skips the rest of the current CSV file. - - Some examples: - -# if the record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the record contains any of these phrases, set account2 and a transaction comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - -# if an empty record is seen (assuming five fields), ignore the rest of the CSV file -if ,,,, - end - - -File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV - -11.13 Matchers -============== - -There are two kinds: - - 1. A record matcher is a word or single-line text fragment or regular - expression (‘REGEX’), which hledger will try to match - case-insensitively anywhere within the CSV record. - Eg: ‘whole foods’ - - 2. A field matcher is preceded with a percent sign and CSV field name - (‘%CSVFIELD REGEX’). hledger will try to match these just within - the named CSV field. - Eg: ‘%date 2023’ - - The regular expression is (as usual in hledger) a POSIX extended -regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’, -‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular -expressions" in the hledger manual -(https://hledger.org/hledger.html#regular-expressions). - - With record matchers, it’s important to know that the record matched -is not the original CSV record, but a modified one: separators will be -converted to commas, and enclosing double quotes (but not enclosing -whitespace) are removed. So for example, when reading an SSV file, if -the original record was: - -2020-01-01; "Acme, Inc."; 1,000 - - the regex would see, and try to match, this modified record text: - -2020-01-01,Acme, Inc., 1,000 - - When an if block has multiple matchers, they are combined as follows: - - • By default they are OR’d (any one of them can match) - • When a matcher is preceded by ampersand (‘&’) it will be AND’ed - with the previous matcher (both of them must match). - - There’s not yet an easy syntax to negate a matcher. - - -File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV - -11.14 ‘if’ table -================ - -"if tables" are an alternative to if blocks; they can express many -matchers and field assignments in a more compact tabular format, like -this: - -if,HLEDGERFIELD1,HLEDGERFIELD2,... -MATCHERA,VALUE1,VALUE2,... -MATCHERB,VALUE1,VALUE2,... -MATCHERC,VALUE1,VALUE2,... - - - The first character after ‘if’ is taken to be the separator for the -rest of the table. It should be a non-alphanumeric character like ‘,’ -or ‘|’ that does not appear anywhere else in the table. (Note: it is -unrelated to the CSV file’s separator.) Whitespace can be used in the -matcher lines for readability, but not in the if line currently. The -table must be terminated by an empty line (or end of file). Each line -must contain the same number of separators; empty values are allowed. - - The above means: try all of the matchers; whenever a matcher -succeeds, assign all of the values on that line to the corresponding -hledger fields; later lines can overrider earlier ones. It is -equivalent to this sequence of if blocks: - -if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERB - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - -if,account2,comment -atm transaction fee,expenses:business:banking,deductible? check it -%description groceries,expenses:groceries, -2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - -File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV - -11.15 ‘balance-type’ -==================== - -Balance assertions generated by assigning to balanceN are of the simple -‘=’ type by default, which is a single-commodity, subaccount-excluding -assertion. You may find the subaccount-including variants more useful, -eg if you have created some virtual subaccounts of checking to help with -budgeting. You can select a different type of assertion with the -‘balance-type’ rule: - -# balance assertions will consider all commodities and all subaccounts -balance-type ==* - - Here are the balance assertion types for quick reference: - -= single commodity, exclude subaccounts -=* single commodity, include subaccounts -== multi commodity, exclude subaccounts -==* multi commodity, include subaccounts - - -File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV - -11.16 ‘include’ -=============== - -include RULESFILE - - This includes the contents of another CSV rules file at this point. -‘RULESFILE’ is an absolute file path or a path relative to the current -file’s directory. This can be useful for sharing common rules between -several rules files, eg: - -# someaccount.csv.rules - -## someaccount-specific rules -fields date,description,amount -account1 assets:someaccount -account2 expenses:misc - -## common rules -include categorisation.rules - - -File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV - -11.17 Working with CSV -====================== - -Some tips: - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading CSV from standard input:: -* Reading multiple CSV files:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Amount signs:: -* Setting currency/commodity:: -* Amount decimal places:: -* Referencing other fields:: -* How CSV rules are evaluated:: -* Well factored rules:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV - -11.17.1 Rapid feedback ----------------------- - -It’s a good idea to get rapid feedback while creating/troubleshooting -CSV rules. Here’s a good way, using entr from eradman.com/entrproject: - -$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - - A desc: query (eg) is used to select just one, or a few, transactions -of interest. "bash -c" is used to run multiple commands, so we can echo -a separator each time the command re-runs, making it easier to read the -output. - - -File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV - -11.17.2 Valid CSV ------------------ - -Note that hledger will only accept valid CSV conforming to RFC 4180, and -equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab -as separators). This means, eg: - - • Values may be enclosed in double quotes, or not. Enclosing in - single quotes is not allowed. (Eg ‘'A','B'’ is rejected.) - • When values are enclosed in double quotes, spaces outside the - quotes are not allowed. (Eg ‘"A", "B"’ is rejected.) - • When values are not enclosed in quotes, they may not contain double - quotes. (Eg ‘A"A, B’ is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you’ll need to -transform it before reading with hledger. Try using sed, or a more -permissive CSV parser like python’s csv lib. - - -File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV - -11.17.3 File Extension ----------------------- - -To help hledger choose the CSV file reader and show the right error -messages (and choose the right field separator character by default), -it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’ -filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV -reader (and the default field separator) by prefixing the file path with -‘csv:’, ‘ssv:’ or ‘tsv:’: Eg: - -$ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator -rule if needed. - - -File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV - -11.17.4 Reading CSV from standard input ---------------------------------------- - -You’ll need the file format prefix when reading CSV from stdin also, -since hledger assumes journal format by default. Eg: - -$ cat foo.dat | hledger -f ssv:- print - - -File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV - -11.17.5 Reading multiple CSV files ----------------------------------- - -If you use multiple ‘-f’ options to read multiple CSV files at once, -hledger will look for a correspondingly-named rules file for each CSV -file. But if you use the ‘--rules-file’ option, that rules file will be -used for all the CSV files. - - -File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV - -11.17.6 Valid transactions --------------------------- - -After reading a CSV file, hledger post-processes and validates the -generated journal entries as it would for a journal file - balancing -them, applying balance assignments, and canonicalising amount styles. -Any errors at this stage will be reported in the usual way, displaying -the problem entry. - - There is one exception: balance assertions, if you have generated -them, will not be checked, since normally these will work only when the -CSV data is part of the main journal. If you do need to check balance -assertions generated from CSV right away, pipe into another hledger: - -$ hledger -f file.csv print | hledger -f- print - - -File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV - -11.17.7 Deduplicating, importing --------------------------------- - -When you download a CSV file periodically, eg to get your latest bank -transactions, the new file may overlap with the old one, containing some -of the same records. - - The import command will (a) detect the new transactions, and (b) -append just those transactions to your main journal. It is idempotent, -so you don’t have to remember how many times you ran it or with which -version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’ -file.) This is the easiest way to import CSV data. Eg: - -# download the latest CSV files, then run this command. -# Note, no -f flags needed here. -$ hledger import *.csv [--dry] - - This method works for most CSV files. (Where records have a stable -chronological order, and new records appear only at the new end.) - - A number of other tools and workflows, hledger-specific and -otherwise, exist for converting, deduplicating, classifying and managing -CSV data. See: - - • https://hledger.org/cookbook.html#setups-and-workflows - • https://plaintextaccounting.org -> data import/conversion - - -File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV - -11.17.8 Setting amounts ------------------------ - -Continuing from amount field above, here are more tips on handling -various amount-setting situations: - - 1. *If the amount is in a single CSV field:* - - a. *If its sign indicates direction of flow:* - Assign it to ‘amountN’, to set the Nth posting’s amount. N is - usually 1 or 2 but can go up to 99. - - b. *If another field indicates direction of flow:* - Use one or more conditional rules to set the appropriate - amount sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. *If the amount is in one of two CSV fields (eg Debit and Credit):* - - a. *If both fields are unsigned:* - Assign the fields to ‘amountN-in’ and ‘amountN-out’. This - sets posting N’s amount to whichever of these has a non-zero - value. If it’s the -out value, the amount will be negated. - - b. *If either field is signed:* - Use a conditional rule to flip the sign when needed. Eg - below, the -out value already has a minus sign so we undo - hledger’s automatic negating by negating once more (but only - if the field is non-empty, so that we don’t leave a minus sign - by itself): - - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields can contain a non-zero value (or both can be - empty):* - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such - as ‘1’ and ‘none’. For such cases, use conditional rules to - help select the amount. Eg, to handle the above you could - select the value containing non-zero digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. *If you want posting 2’s amount converted to cost:* - Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’) - syntax. - - 4. *If the CSV has only balance amounts, not transaction amounts:* - Assign to ‘balanceN’, to set a balance assignment on the Nth - posting, causing the posting’s amount to be calculated - automatically. ‘balance’ with no number is equivalent to - ‘balance1’. In this situation hledger is more likely to guess the - wrong default account name, so you may need to set that explicitly. - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV - -11.17.9 Amount signs --------------------- - -There is some special handling for amount signs, to simplify parsing and -sign-flipping: - - • *If an amount value begins with a plus sign:* - that will be removed: ‘+AMT’ becomes ‘AMT’ - - • *If an amount value is parenthesised:* - it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes - ‘-AMT’ - - • *If an amount value has two minus signs (or two sets of - parentheses, or a minus sign and parentheses):* - they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes - ‘AMT’ - - • *If an amount value contains just a sign (or just a set of - parentheses):* - that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or - ‘"()"’ becomes ‘""’. - - -File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV - -11.17.10 Setting currency/commodity ------------------------------------ - -If the currency/commodity symbol is included in the CSV’s amount -field(s): - -2020-01-01,foo,$123.00 - - you don’t have to do anything special for the commodity symbol, it -will be assigned as part of the amount. Eg: - -fields date,description,amount - -2020-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - -2020-01-01,foo,USD,123.00 - - You can assign that to the ‘currency’ pseudo-field, which has the -special effect of prepending itself to every amount in the transaction -(on the left, with no separating space): - -fields date,description,currency,amount - -2020-01-01 foo - expenses:unknown USD123.00 - income:unknown USD-123.00 - - Or, you can use a field assignment to construct the amount yourself, -with more control. Eg to put the symbol on the right, and separated by -a space: - -fields date,description,cur,amt -amount %amt %cur - -2020-01-01 foo - expenses:unknown 123.00 USD - income:unknown -123.00 USD - - Note we used a temporary field name (‘cur’) that is not ‘currency’ - -that would trigger the prepending effect, which we don’t want here. - - -File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV - -11.17.11 Amount decimal places ------------------------------- - -Like amounts in a journal file, the amounts generated by CSV rules like -‘amount1’ influence commodity display styles, such as the number of -decimal places displayed in reports. - - The original amounts as written in the CSV file do not affect display -style (because we don’t yet reliably know their commodity). - - -File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV - -11.17.12 Referencing other fields ---------------------------------- - -In field assignments, you can interpolate only CSV fields, not hledger -fields. In the example below, there’s both a CSV field and a hledger -field named amount1, but %amount1 always means the CSV field, not the -hledger field: - -# Name the third CSV field "amount1" -fields date,description,amount1 - -# Set hledger's amount1 to the CSV amount1 field followed by USD -amount1 %amount1 USD - -# Set comment to the CSV amount1 (not the amount1 assigned above) -comment %amount1 - - Here, since there’s no CSV amount1 field, %amount1 will produce a -literal "amount1": - -fields date,description,csvamount -amount1 %csvamount USD -# Can't interpolate amount1 here -comment %amount1 - - When there are multiple field assignments to the same hledger field, -only the last one takes effect. Here, comment’s value will be be B, or -C if "something" is matched, but never A: - -comment A -comment B -if something - comment C - - -File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV - -11.17.13 How CSV rules are evaluated ------------------------------------- - -Here’s how to think of CSV rules being evaluated (if you really need -to). First, - - • ‘include’ - all includes are inlined, from top to bottom, depth - first. (At each include point the file is inlined and scanned for - further includes, recursively, before proceeding.) - - Then "global" rules are evaluated, top to bottom. If a rule is -repeated, the last one wins: - - • ‘skip’ (at top level) - • ‘date-format’ - • ‘newest-first’ - • ‘fields’ - names the CSV fields, optionally sets up initial - assignments to hledger fields - - Then for each CSV record in turn: - - • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip - all remaining CSV records. Otherwise if any of them contain a - ‘skip’ rule, skip that many CSV records. If there are multiple - matched ‘skip’ rules, the first one wins. - • collect all field assignments at top level and in matched ‘if’ - blocks. When there are multiple assignments for a field, keep only - the last one. - • compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELD references), or a - default - • generate a hledger transaction (journal entry) from these values. - - This is all part of the CSV reader, one of several readers hledger -can use to parse input files. When all files have been read -successfully, the transactions are passed as input to whichever hledger -command the user specified. - - -File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV - -11.17.14 Well factored rules ----------------------------- - -Some things than can help reduce duplication and complexity in rules -files: - - • Extracting common rules usable with multiple CSV files into a - ‘common.rules’, and adding ‘include common.rules’ to each CSV’s - rules file. - - • Splitting if blocks into smaller if blocks, extracting the - frequently used parts. - - -File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV - -11.18 CSV rules examples -======================== - -* Menu: - -* Bank of Ireland:: -* Coinbase:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples - -11.18.1 Bank of Ireland ------------------------ - -Here’s a CSV with two amount fields (Debit and Credit), and a balance -field, which we can use to add balance assertions, which is not -necessary but provides extra error checking: - -Date,Details,Debit,Credit,Balance -07/12/2012,LODGMENT 529898,,10.0,131.21 -07/12/2012,PAYMENT,5,,126 - -# bankofireland-checking.csv.rules - -# skip the header line -skip - -# name the csv fields, and assign some of them as journal entry fields -fields date, description, amount-out, amount-in, balance - -# We generate balance assertions by assigning to "balance" -# above, but you may sometimes need to remove these because: -# -# - the CSV balance differs from the true balance, -# by up to 0.0000000000005 in my experience -# -# - it is sometimes calculated based on non-chronological ordering, -# eg when multiple transactions clear on the same day - -# date is in UK/Ireland format -date-format %d/%m/%Y - -# set the currency -currency EUR - -# set the base account for all txns -account1 assets:bank:boi:checking - -$ hledger -f bankofireland-checking.csv print -2012-12-07 LODGMENT 529898 - assets:bank:boi:checking EUR10.0 = EUR131.2 - income:unknown EUR-10.0 - -2012-12-07 PAYMENT - assets:bank:boi:checking EUR-5.0 = EUR126.0 - expenses:unknown EUR5.0 - - The balance assertions don’t raise an error above, because we’re -reading directly from CSV, but they will be checked if these entries are -imported into a journal file. - - -File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples - -11.18.2 Coinbase ----------------- - -A simple example with some CSV from Coinbase. The spot price is -recorded using cost notation. The legacy ‘amount’ field name -conveniently sets amount 2 (posting 2’s amount) to the total cost. - -# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes -# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - -# coinbase.csv.rules -skip 1 -fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes -date %Timestamp -date-format %Y-%m-%dT%T%Z -description %Notes -account1 assets:coinbase:cc -amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - -$ hledger print -f coinbase.csv -2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - -File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples - -11.18.3 Amazon --------------- - -Here we convert amazon.com order history, and use an if block to -generate a third posting if there’s a fee. (In practice you’d probably -get this data from your bank instead, but it’s an example.) - -"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" -"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" -"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" - -# amazon-orders.csv.rules - -# skip one header line -skip 1 - -# name the csv fields, and assign the transaction's date, amount and code. -# Avoided the "status" and "amount" hledger field names to prevent confusion. -fields date, _, toorfrom, name, amzstatus, amzamount, fees, code - -# how to parse the date -date-format %b %-d, %Y - -# combine two fields to make the description -description %toorfrom %name - -# save the status as a tag -comment status:%amzstatus - -# set the base account for all transactions -account1 assets:amazon -# leave amount1 blank so it can balance the other(s). -# I'm assuming amzamount excludes the fees, don't remember - -# set a generic account2 -account2 expenses:misc -amount2 %amzamount -# and maybe refine it further: -#include categorisation.rules - -# add a third posting for fees, but only if they are non-zero. -if %fees [1-9] - account3 expenses:fees - amount3 %fees - -$ hledger -f amazon-orders.csv print -2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed - assets:amazon - expenses:misc $20.00 - -2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed - assets:amazon - expenses:misc $25.00 - expenses:fees $1.00 - - -File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples - -11.18.4 Paypal --------------- - -Here’s a real-world rules file for (customised) Paypal CSV, with some -Paypal-specific rules, and a second rules file included: - -"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" -"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" -"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" -"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" -"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" -"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" -"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" -"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" - -# paypal-custom.csv.rules - -# Tips: -# Export from Activity -> Statements -> Custom -> Activity download -# Suggested transaction type: "Balance affecting" -# Paypal's default fields in 2018 were: -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" -# This rules file assumes the following more detailed fields, configured in "Customize report fields": -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" - -fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note - -skip 1 - -date-format %-m/%-d/%Y - -# ignore some paypal events -if -In Progress -Temporary Hold -Update to - skip - -# add more fields to the description -description %description_ %itemtitle - -# save some other fields as tags -comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ - -# convert to short currency symbols -if %currency USD - currency $ -if %currency EUR - currency E -if %currency GBP - currency P - -# generate postings - -# the first posting will be the money leaving/entering my paypal account -# (negative means leaving my account, in all amount fields) -account1 assets:online:paypal -amount1 %netamount - -# the second posting will be money sent to/received from other party -# (account2 is set below) -amount2 -%grossamount - -# if there's a fee, add a third posting for the money taken by paypal. -if %feeamount [1-9] - account3 expenses:banking:paypal - amount3 -%feeamount - comment3 business: - -# choose an account for the second posting - -# override the default account names: -# if the amount is positive, it's income (a debit) -if %grossamount ^[^-] - account2 income:unknown -# if negative, it's an expense (a credit) -if %grossamount ^- - account2 expenses:unknown - -# apply common rules for setting account2 & other tweaks -include common.rules - -# apply some overrides specific to this csv - -# Transfers from/to bank. These are usually marked Pending, -# which can be disregarded in this case. -if -Bank Account -Bank Deposit to PP Account - description %type for %referencetxnid %itemtitle - account2 assets:bank:wf:pchecking - account1 assets:online:paypal - -# Currency conversions -if Currency Conversion - account2 equity:currency conversion - -# common.rules - -if -darcs -noble benefactor - account2 revenues:foss donations:darcshub - comment2 business: - -if -Calm Radio - account2 expenses:online:apps - -if -electronic frontier foundation -Patreon -wikimedia -Advent of Code - account2 expenses:dues - -if Google - account2 expenses:online:apps - description google | music - -$ hledger -f paypal-custom.csv print -2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed - assets:online:paypal $-6.99 = $-6.99 - expenses:online:apps $6.99 - -2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $6.99 = $0.00 - assets:bank:wf:pchecking $-6.99 - -2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed - assets:online:paypal $-7.00 = $-7.00 - expenses:dues $7.00 - -2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $7.00 = $0.00 - assets:bank:wf:pchecking $-7.00 - -2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed - assets:online:paypal $-2.00 = $-2.00 - expenses:dues $2.00 - expenses:banking:paypal ; business: - -2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $2.00 = $0.00 - assets:bank:wf:pchecking $-2.00 - -2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed - assets:online:paypal $9.41 = $9.41 - revenues:foss donations:darcshub $-10.00 ; business: - expenses:banking:paypal $0.59 ; business: - - -File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top - -12 Timeclock -************ - -The time logging format of timeclock.el, as read by hledger. - - hledger can read time logs in timeclock format. As with Ledger, -these are (a subset of) timeclock.el’s format, containing clock-in and -clock-out entries as in the example below. The date is a simple date. -The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are -optional. The timezone, if present, must be four digits and is ignored -(currently the time is always interpreted as a local time). Lines -beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored. - -i 2015/03/30 09:00:00 some:account name optional description after two spaces -o 2015/03/30 09:20:00 -i 2015/03/31 22:21:45 another account -o 2015/04/01 02:00:34 - - hledger treats each clock-in/clock-out pair as a transaction posting -some number of hours to an account. Or if the session spans more than -one day, it is split into several transactions, one for each day. For -the above time log, ‘hledger print’ generates these journal entries: - -$ hledger -f t.timeclock print -2015-03-30 * optional description after two spaces - (some:account name) 0.33h - -2015-03-31 * 22:21-23:59 - (another account) 1.64h - -2015-04-01 * 00:00-02:00 - (another account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - -$ hledger -f sample.timeclock balance # current time balances -$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 -$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - • use emacs and the built-in timeclock.el, or the extended - timeclock-x.el and perhaps the extras in ledgerutils.el - - • at the command line, use these bash aliases: ‘shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’ - - • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository. - These rely on a "timeclock" executable which I think is just the - ledger 2 executable renamed. - - -File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top - -13 Timedot -********** - -‘timedot’ format is hledger’s human-friendly time logging format. -Compared to ‘timeclock’ format, it is - - • convenient for quick, approximate, and retroactive time logging - • readable: you can see at a glance where time was spent. - - A timedot file contains a series of day entries, which might look -like this: - -2021-08-04 -hom:errands .... .... -fos:hledger:timedot .. ; docs -per:admin:finance - - hledger reads this as three time transactions on this day, with each -dot representing a quarter-hour spent: - -$ hledger -f a.timedot print # .timedot file extension activates the timedot reader -2021-08-04 * - (hom:errands) 2.00 - -2021-08-04 * - (fos:hledger:timedot) 0.50 - -2021-08-04 * - (per:admin:finance) 0 - - A day entry begins with a date line: - - • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D). - - Optionally this can be followed on the same line by - - • a common *transaction description* for this day - • a common *transaction comment* for this day, after a semicolon - (‘;’). - - After the date line are zero or more optionally-indented time -transaction lines, consisting of: - - • an *account name* - any word or phrase, usually a hledger-style - account name. - • *two or more spaces* - a field separator, required if there is an - amount (as in journal format). - • a *timedot amount* - dots representing quarter hours, or a number - representing hours. - • an optional *comment* beginning with semicolon. This is ignored. - - In more detail, timedot amounts can be: - - • *dots*: zero or more period characters, each representing one - quarter-hour. Spaces are ignored and can be used for grouping. - Eg: ‘.... ..’ - - • a *number*, representing hours. Eg: ‘1.5’ - - • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’, - ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days - weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following - equivalencies are assumed: - ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ = - ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the - generated transaction amount, which is always in hours.) - - There is some added flexibility to help with keeping time log data in -the same file as your notes, todo lists, etc.: - - • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored. - - • Before the first date line, lines beginning with ‘*’ are ignored. - From the first date line onward, a sequence of ‘*’’s followed by a - space at beginning of lines (ie, the headline prefix used by Emacs - Org mode) is ignored. This means the time log can be kept under an - Org headline, and date lines or time transaction lines can be Org - headlines. - - • Lines not ending with a double-space and amount are parsed as - transactions with zero amount. (Most hledger reports hide these by - default; add -E to see them.) - - More examples: - -# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. -2016/2/1 -inc:client1 .... .... .... .... .... .... -fos:haskell .... .. -biz:research . - -2016/2/2 -inc:client1 .... .... -biz:research . - -2016/2/3 -inc:client1 4 -fos:hledger 3 -biz:research 1 - -* Time log -** 2020-01-01 -*** adm:time . -*** adm:finance . - -* 2020 Work Diary -** Q1 -*** 2020-02-29 -**** DONE -0700 yoga -**** UNPLANNED -**** BEGUN -hom:chores - cleaning ... - water plants - outdoor - one full watering can - indoor - light watering -**** TODO -adm:planning: trip -*** LATER - - Reporting: - -$ hledger -f a.timedot print date:2016/2/2 -2016-02-02 * - (inc:client1) 2.00 - -2016-02-02 * - (biz:research) 0.25 - -$ hledger -f a.timedot bal --daily --tree -Balance changes in 2016-02-01-2016-02-03: - - || 2016-02-01d 2016-02-02d 2016-02-03d -============++======================================== - biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 -------------++---------------------------------------- - || 7.75 2.25 8.00 - - Using period instead of colon as account name separator: - -2016/2/4 -fos.hledger.timedot 4 -fos.ledger .. - -$ hledger -f a.timedot --alias /\\./=: bal --tree - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger --------------------- - 4.50 - - A sample.timedot file. - - -File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top - -14 PART 3: REPORTING CONCEPTS -***************************** - - -File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top - -15 Time periods -*************** - -* Menu: - -* Report start & end date:: -* Smart dates:: -* Report intervals:: -* Date adjustment:: -* Period expressions:: - - -File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods - -15.1 Report start & end date -============================ - -By default, most hledger reports will show the full span of time -represented by the journal. The report start date will be the earliest -transaction or posting date, and the report end date will be the latest -transaction, posting, or market price date. - - 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 (below). - - Some notes: - - • End dates are exclusive, as in Ledger, so you should write the date - _after_ the last day you want to see in the report. - • As noted in reporting options: among start/end dates specified with - _options_, the last (i.e. right-most) option takes precedence. - • The effective report start and end dates are the intersection of - the start/end dates from options and that from ‘date:’ queries. - That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January - 2019, the smallest common time span. - • In some cases a report interval will adjust start/end dates to fall - on interval boundaries (see below). - - Examples: - -‘-b begin on St. Patrick’s day 2016 -2016/3/17’ -‘-e 12/1’ end at the start of december 1st of the current year - (11/30 will be the last date included) -‘-b all transactions on or after the 1st of the current month -thismonth’ -‘-p all transactions in the current month -thismonth’ -‘date:2016/3/17..’the above written as queries instead (‘..’ can also be - replaced with ‘-’) -‘date:..12/1’ -‘date:thismonth..’ -‘date:thismonth’ - - -File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods - -15.2 Smart dates -================ - -hledger’s user interfaces accept a "smart date" syntax for added -convenience. Smart dates optionally can be relative to today’s date, be -written with english words, and have less-significant parts omitted -(missing parts are inferred as 1). Some examples: - -‘2004/10/1’, exact date, several separators allowed. Year -‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31 -‘2004.9.1’ -‘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, -1, 0, 1 days from today -tomorrow’ -‘last/this/next -1, 0, 1 periods from the current period -day/week/month/quarter/year’ -‘in n n periods from the current period -days/weeks/months/quarters/years’ -‘n n periods from the current period -days/weeks/months/quarters/years -ahead’ -‘n -n periods from the current period -days/weeks/months/quarters/years -ago’ -‘20181201’ 8 digit YYYYMMDD with valid year month and - day -‘201812’ 6 digit YYYYMM with valid year and month - - Some 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 - - "Today’s date" can be overridden with the ‘--today’ option, in case -it’s needed for testing or for recreating old reports. (Except for -periodic transaction rules, which are not affected by ‘--today’.) - - -File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods - -15.3 Report intervals -===================== - -A report interval can be specified so that reports like register, -balance or activity become multi-period, showing each subperiod as a -separate row or column. - - The following standard intervals can be enabled with command-line -flags: - - • ‘-D/--daily’ - • ‘-W/--weekly’ - • ‘-M/--monthly’ - • ‘-Q/--quarterly’ - • ‘-Y/--yearly’ - - More complex intervals can be specified using ‘-p/--period’, -described below. - - -File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods - -15.4 Date adjustment -==================== - -With a report interval (other than daily), report start / end dates -which have not been specified explicitly and in full (eg not ‘-b -2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are -considered flexible: - - • A flexible start date will be automatically adjusted earlier if - needed to fall on a natural interval boundary. - • Similarly, a flexible end date will be adjusted later if needed to - make the last period a whole interval (the same length as the - others). - - This is convenient for producing clean periodic reports (this is -traditional hledger behaviour). By contrast, fully-specified exact -dates will not be adjusted (this is new in hledger 1.29). - - An example: with a journal whose first date is 2023-01-10 and last -date is 2023-03-20: - - • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’ - The report periods will begin on the 15th day of each month, - starting from 2023-01-15, and the last period’s last day will be - 2023-03-09. (Exact start and end dates, neither is adjusted.) - - • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’ - The report periods will begin on the 1st of each month, starting - from 2023-01-01, and the last period’s last day will be 2023-03-31. - (Flexible start and end dates, both are adjusted.) - - -File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods - -15.5 Period expressions -======================= - -The ‘-p/--period’ option specifies a period expression, which is a -compact way of expressing a start date, end date, and/or report -interval. - - Here’s a period expression with a start and end date (specifying the -first quarter of 2009): - -‘-p "from 2009/1/1 to 2009/4/1"’ - - Several keywords like "from" and "to" are supported for readability; -these are optional. "to" can also be written as ".." or "-". The -spaces are also optional, as long as you don’t run two dates together. -So the following 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, these are also -equivalent to the above: - -‘-p "1/1 4/1"’ -‘-p "jan-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 date in the journal: - -‘-p "from 2009/1/1"’ everything after january 1, 2009 -‘-p "since 2009/1"’ the same, since is a synonym -‘-p "from 2009"’ the same -‘-p "to 2009"’ everything before january 1, 2009 - - You can also specify a period by writing a single partial or full -date: - -‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1” -‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to - 2009/2/1” -‘-p the first day of 2009; equivalent to “2009/1/1 to -"2009/1/1"’ 2009/1/2” - - or by using the "Q" quarter-year syntax (case insensitive): - -‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to - 2009/4/1” -‘-p "q4"’ fourth quarter of the current year - -* Menu: - -* Period expressions with a report interval:: -* More complex report intervals:: -* Multiple weekday intervals:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -15.5.1 Period expressions with a report interval ------------------------------------------------- - -A period expression can also begin with a report interval, separated -from the start/end dates (if any) by a space or the word ‘in’: - -‘-p "weekly from 2009/1/1 to 2009/4/1"’ -‘-p "monthly in 2008"’ -‘-p "quarterly"’ - - -File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions - -15.5.2 More complex report intervals ------------------------------------- - -Some more complex intervals can be specified within period expressions, -such as: - - • ‘biweekly’ (every two weeks) - • ‘fortnightly’ - • ‘bimonthly’ (every two months) - • ‘every day|week|month|quarter|year’ - • ‘every N days|weeks|months|quarters|years’ - - Weekly on a custom day: - - • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted - after the number) - • ‘every WEEKDAYNAME’ (full or three-letter english weekday name, - case insensitive) - - Monthly on a custom day: - - • ‘every Nth day [of month]’ - • ‘every Nth WEEKDAYNAME [of month]’ - - Yearly on a custom day: - - • ‘every MM/DD [of year]’ (month number and day of month number) - • ‘every MONTHNAME DDth [of year]’ (full or three-letter english - month name, case insensitive, and day of month number) - • ‘every DDth MONTHNAME [of year]’ (equivalent to the above) - - Examples: - -‘-p "bimonthly from -2008"’ -‘-p "every 2 weeks"’ -‘-p "every 5 months from -2009/03"’ -‘-p "every 2nd day of periods will go from Tue to Tue -week"’ -‘-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 - November -‘-p "every 5th November"’ same -‘-p "every Nov 5th"’ same - - Show historical balances at end of the 15th day of each month (N is -an end date, exclusive as always): - -$ hledger balance -H -p "every 16th day" - - Group postings from the start of wednesday to end of the following -tuesday (N is both (inclusive) start date and (exclusive) end date): - -$ hledger register checking -p "every 3rd day of week" - - -File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions - -15.5.3 Multiple weekday intervals ---------------------------------- - -This special form is also supported: - - • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english - weekday names, case insensitive) - - Also, ‘weekday’ and ‘weekendday’ are shorthand for -‘mon,tue,wed,thu,fri’ and ‘sat,sun’. - - This is mainly intended for use with ‘--forecast’, to generate -periodic transactions on arbitrary days of the week. It may be less -useful with ‘-p’, since it divides each week into subperiods of unequal -length, which is unusual. (Related: #1632) - - Examples: - -‘-p "every dates will be Mon, Wed, Fri; periods will be -mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun -‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will -weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun -‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri -weekendday"’ - - -File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top - -16 Depth -******** - -With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show -accounts only to the specified depth, hiding deeper subaccounts. Use -this when you want a summary with less detail. This flag has the same -effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are -equivalent. - - -File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top - -17 Queries -********** - -One of hledger’s strengths is being able to quickly report on a precise -subset of your data. Most hledger commands accept optional query -arguments to restrict their scope. The syntax is as follows: - - • Zero or more space-separated query terms. These are most often - account name substrings: - - ‘utilities food:groceries’ - - • Terms with spaces or other special characters should be enclosed in - quotes: - - ‘"personal care"’ - - • Regular expressions are also supported: - - ‘"^expenses\b" "accounts (payable|receivable)"’ - - • Add a query type prefix to match other parts of the data: - - ‘date:202012- desc:amazon cur:USD amt:">100" status:’ - - • Add a ‘not:’ prefix to negate a term: - - ‘not:cur:USD’ - -* Menu: - -* Query types:: -* Combining query terms:: -* Queries and command options:: -* Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value:: - - -File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries - -17.1 Query types -================ - -Here are the types of query term available. Remember these can also be -prefixed with *‘not:’* to convert them into a negative match. - - *‘acct:REGEX’, ‘REGEX’* -Match account names containing this (case insensitive) regular -expression. This is the default query type when there is no prefix, and -regular expression syntax is typically not needed, so usually we just -write an account name substring, like ‘expenses’ or ‘food’. - - *‘amt:N, amt:N, amt:>=N’* -Match postings with a single-commodity amount equal to, less than, or -greater than N. (Postings with 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 special characters which are -regex-significant, you need to escape them with ‘\’. And for characters -which are significant to your shell you may need one more level of -escaping. So eg to match the dollar sign: -‘hledger print cur:\\$’. - - *‘desc:REGEX’* -Match transaction descriptions. - - *‘date:PERIODEXPR’* -Match dates (or with the ‘--date2’ flag, secondary dates) within the -specified period. PERIODEXPR is a period expression with no report -interval. Examples: -‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’, -‘date:2021-07-27..nextquarter’. - - *‘date2:PERIODEXPR’* -Match secondary dates within the specified period (independent of the -‘--date2’ flag). - - *‘depth:N’* -Match (or display, depending on command) accounts at or above this -depth. - - *‘note:REGEX’* -Match transaction notes (the part of the description right of ‘|’, or -the whole description if there’s no ‘|’). - - *‘payee:REGEX’* -Match transaction payee/payer names (the part of the description left of -‘|’, or the whole description if there’s no ‘|’). - - *‘real:, real:0’* -Match real or virtual postings respectively. - - *‘status:, status:!, status:*’* -Match unmarked, pending, or cleared transactions respectively. - - *‘type:TYPECODES’* -Match by account type (see Declaring accounts > Account types). -‘TYPECODES’ is one or more of the single-letter account type codes -‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match -their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain -kinds of account alias can disrupt account types, see Rewriting accounts -> Aliases and account types. - - *‘tag:REGEX[=REGEX]’* -Match by tag name, and optionally also by tag value. (To match only by -value, use ‘tag:.=REGEX’.) - - When querying by tag, note that: - - • Accounts also inherit the tags of their parent accounts - • Postings also inherit the tags of their account and their - transaction - • Transactions also acquire the tags of their postings. - - (*‘inacct:ACCTNAME’* -A special query term used automatically in hledger-web only: tells -hledger-web to show the transaction register for an account.) - - -File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries - -17.2 Combining query terms -========================== - -When given multiple query terms, most commands select things which -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 is a little different, showing 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. - - Although these fixed rules are enough for many needs, we do not -support full boolean expressions (#203), (and you should not write AND -or OR in your queries). This makes certain queries hard to express, but -here are some tricks that can help: - - 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses - paid with cash: - - $ hledger print food not:not:cash - - 2. Or pre-filter the transactions with ‘print’, piping the result into - a second hledger command (with balance assertions disabled): - - $ hledger print cash | hledger -f- -I balance food - - -File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries - -17.3 Queries and command options -================================ - -Some queries can also be expressed as command-line options: ‘depth:2’ is -equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc. -When you mix command options and query arguments, generally the -resulting query is their intersection. - - -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries - -17.4 Queries and valuation -========================== - -When amounts are converted to other commodities in cost or value -reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old -amount quantity, not the new ones (except in hledger 1.22.0 where it’s -reversed, see #1625). - - -File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries - -17.5 Querying with account aliases -================================== - -When account names are rewritten with ‘--alias’ or ‘alias’, note that -‘acct:’ will match either the old or the new account name. - - -File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries - -17.6 Querying with cost or value -================================ - -When amounts are converted to other commodities in cost or value -reports, note that ‘cur:’ matches the new commodity symbol, and not the -old one, and ‘amt:’ matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, see -the discussion at #1625. - - -File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top - -18 Pivoting -*********** - -Normally, hledger groups and sums amounts within each account. The -‘--pivot FIELD’ option substitutes some other transaction field for -account names, causing amounts to be grouped and summed by that field’s -value instead. FIELD can be any of the transaction fields ‘status’, -‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on -a tag and a posting has multiple values of that tag, only the first -value is displayed. Values containing ‘colon:separated:parts’ will be -displayed hierarchically, like account names. - - Some examples: - -2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues --------------------- - 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): - -$ 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: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top - -19 Generating data -****************** - -Two features for generating transient data (visible only at report time) -are built in to hledger’s journal format: - - • Auto posting rules can generate extra postings on certain - transactions. They are activated by the ‘--auto’ flag. - - • Periodic transaction rules can generate repeating transactions, - usually dated in the future, to help with forecasting or budgeting. - They are activated by the ‘--forecast’ or ‘balance --budget’ - options, described next. - - -File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top - -20 Forecasting -************** - -The ‘--forecast’ flag activates any periodic transaction rules in the -journal. These will generate temporary additional transactions, usually -recurring and in the future, which will appear in all reports. ‘hledger -print --forecast’ is a good way to see them. - - This can be useful for estimating balances into the future, perhaps -experimenting with different scenarios. - - It could also be useful for scripted data entry: you could describe -recurring transactions, and every so often copy the output of ‘print ---forecast’ into the journal. - - The generated transactions will have an extra tag, like -‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule -generated them. There is also a similar, hidden tag, named -‘_generated-transaction:’, which you can use to reliably match -transactions generated "just now" (rather than ‘print’ed in the past). - - The forecast transactions are generated within a _forecast period_, -which is independent of the report period. (Forecast period sets the -bounds for generated transactions, report period controls which -transactions are reported.) The forecast period begins on: - - • the start date provided within ‘--forecast’’s argument, if any - • otherwise, the later of - • the report start date, if specified (with ‘-b’/‘-p’/‘date:’) - • the day after the latest ordinary transaction in the journal, - if any - - • otherwise today. - - It ends on: - - • the end date provided within ‘--forecast’’s argument, if any - • otherwise, the report end date, if specified (with - ‘-e’/‘-p’/‘date:’) - • otherwise 180 days (6 months) from today. - - Note, this means that ordinary transactions will suppress periodic -transactions, by default; the periodic transactions will not start until -after the last ordinary transaction. This is usually convenient, but -you can get around it in two ways: - - • If you need to record some transactions in the future, make them - periodic transactions (with a single occurrence, eg: ‘~ - YYYY-MM-DD’) rather than ordinary transactions. That way they - won’t suppress other periodic transactions. - - • Or give ‘--forecast’ a period expression argument. A forecast - period specified this way can overlap ordinary transactions, and - need not be in the future. Some things to note: - - • You must use ‘=’ between flag and argument; a space won’t - work. - • The period expression can specify the forecast period’s start - date, end date, or both. See also Report start & end date. - • The period expression should not specify a report interval. - (Each periodic transaction rule specifies its own interval.) - - Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’, -‘--forecast=2021’. - - -File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top - -21 Budgeting -************ - -With the balance command’s ‘--budget’ report, each periodic transaction -rule generates recurring budget goals in specified accounts, and goals -and actual performance can be compared. See the balance command’s doc -below. - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top - -22 Cost reporting -***************** - -This section is about recording the cost of things, in transactions -where one commodity is exchanged for another. Eg an exchange of -currency, or a stock purchase or sale. First, a quick glossary: - - • Conversion - an exchange of one currency or commodity for another. - Eg a foreign currency exchange, or a purchase or sale of stock or - cryptocurrency. - - • Conversion transaction - a transaction involving one or more - conversions. - - • Conversion rate - the cost per unit of one commodity in the other, - ie the exchange rate. - - • Cost - how much of one commodity was paid to acquire the other. - And more generally, in hledger docs: the amount exchanged in the - "secondary" commodity (usually your base currency), whether in a - purchase or a sale, and whether expressed per unit or in total. - Also, the "@/@@ PRICE" notation used to represent this. - -* Menu: - -* -B Convert to cost:: -* Equity conversion postings:: -* Inferring equity postings from cost:: -* Inferring cost from equity postings:: -* When to infer cost/equity:: -* How to record conversions:: -* Cost tips:: - - -File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting - -22.1 -B: Convert to cost -======================== - -As discussed in JOURNAL > Costs, when recording a transaction you can -also record the amount’s cost in another commodity, by adding ‘@ -UNITPRICE’ or ‘@@ TOTALPRICE’. - - Then you can see a report with amounts converted to cost, by adding -the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger). -Eg: - -2022-01-01 - assets:dollars $-135 ; 135 dollars is exchanged for.. - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - -$ hledger bal -N - $-135 assets:dollars - €100 assets:euros -$ hledger bal -N -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Notes: - - -B is sensitive to the order of postings when a cost 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: - -2022-01-01 - assets:dollars $-135 ; 135 dollars sold - assets:euros €100 ; for 100 euros - -$ hledger bal -N -B - €-100 assets:dollars # <- the dollars' selling price - €100 assets:euros - - The @/@@ cost notation is convenient, but has some drawbacks: it does -not truly balance the transaction, so it disrupts the accounting -equation and tends to causes a non-zero total in balance reports. - - -File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting - -22.2 Equity conversion postings -=============================== - -By contrast, conventional double entry bookkeeping (DEB) uses a -different notation: an extra pair of equity postings to balance -conversion transactions. In this style, the above entry might be -written: - -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 - - This style is more correct, but it’s also more verbose and makes cost -reporting more difficult for PTA tools. - - Happily, current hledger can read either notation, or convert one to -the other when needed, so you can use the one you prefer. - - You can even use cost notation and equivalent conversion postings at -the same time, for clarity. hledger will ignore the redundancy. But be -sure the cost and conversion posting amounts match, or you’ll see a -not-so-clear transaction balancing error message. - - -File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting - -22.3 Inferring equity postings from cost -======================================== - -With ‘--infer-equity’, hledger detects transactions written with PTA -cost notation and adds equity conversion postings to them: - -2022-01-01 - assets:dollars -$135 - assets:euros €100 @ $1.35 - -$ hledger print --infer-equity -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 - equity:conversion:$-€:€ €-100 ; generated-posting: - equity:conversion:$-€:$ $135.00 ; generated-posting: - - The conversion account names can be changed with the conversion -account type declaration. - - –infer-equity is useful when when transactions have been recorded -using cost notation, to help preserve the accounting equation and -balance reports’ zero total, or to produce more conventional journal -entries for sharing with non-PTA-users. - - -File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting - -22.4 Inferring cost from equity postings -======================================== - -The reverse operation is possible using ‘--infer-costs’, which detects -transactions written with equity conversion postings and adds cost -notation to them: - -2022-01-01 - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 - -$ hledger print --infer-costs -2022-01-01 - assets:dollars $-135 @@ €100 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 - - –infer-costs is useful when combined with -B/–cost, allowing cost -reporting even when transactions have been recorded using equity -postings: - -$ hledger print --infer-costs -B -2009-01-01 - assets:dollars €-100 - assets:euros €100 - - Notes: - - For ‘--infer-costs’ to work, an exchange must consist of four -postings: - - 1. two non-equity postings - 2. two equity postings, next to one another - 3. the equity accounts must be declared, with account type - ‘V’/‘Conversion’ (or if they are not declared, they must be named - ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or - subaccounts of these) - 4. the equity postings’ amounts must exactly match the non-equity - postings’ amounts. - - Multiple such exchanges can coexist within a single transaction. - - When inferring cost, the order of postings matters: the cost is added -to the first of the non-equity postings involved in the exchange, in the -commodity of the last non-equity posting involved in the exchange. If -you don’t want to write your postings in the required order, you can use -explicit cost notation instead. - - –infer-equity and –infer-costs can be used together, if you have a -mixture of both notations in your journal. - - -File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting - -22.5 When to infer cost/equity -============================== - -Inferring equity postings or costs is still fairly new, so not enabled -by default. We’re not sure yet if that should change. Here are two -suggestions to try, experience reports welcome: - - 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal - -B --infer-costs’ - - 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger - --infer-equity --infer-costs"’ - - -File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting - -22.6 How to record conversions -============================== - -Essentially there are four ways to record a conversion transaction in -hledger. Here are all of them, with pros and cons. - -* Menu: - -* Conversion with implicit cost:: -* Conversion with explicit cost:: -* Conversion with equity postings:: -* Conversion with equity postings and explicit cost:: - - -File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions - -22.6.1 Conversion with implicit cost ------------------------------------- - -Let’s assume 100 EUR is converted to 120 USD. You can just record the -outflow (100 EUR) and inflow (120 USD) in the appropriate asset account: - -2021-01-01 - assets:cash -100 EUR - assets:cash 120 USD - - hledger will assume this transaction is balanced, inferring that the -conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate -by using ‘hledger print -x’. - - Pro: - - • Concise, easy - - Con: - - • Less error checking - typos in amounts or commodity symbols may not - be detected - • Conversion rate is not clear - • Disturbs the accounting equation, unless you add the –infer-equity - flag - - You can prevent accidental implicit conversions due to a mistyped -commodity symbol, by using ‘hledger check commodities’. - - You can prevent implicit conversions entirely, by using ‘hledger -check balancednoautoconversion’, or ‘-s/--strict’. - - -File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions - -22.6.2 Conversion with explicit cost ------------------------------------- - -You can add the conversion rate using @ notation: - -2021-01-01 - assets:cash -100 EUR @ 1.20 USD - assets:cash 120 USD - - Now hledger will check that 100 * 1.20 = 120, and would report an -error otherwise. - - Pro: - - • Still concise - • Makes the conversion rate clear - • Provides more error checking - - Con: - - • Disturbs the accounting equation, unless you add the –infer-equity - flag - - -File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions - -22.6.3 Conversion with equity postings --------------------------------------- - -In strict double entry bookkeeping, the above transaction is not -balanced in EUR or in USD, since some EUR disappears, and some USD -appears. This violates the accounting equation (A+L+E=0), and prevents -reports like ‘balancesheetequity’ from showing a zero total. - - The proper way to make it balance is to add a balancing posting for -each commodity, using an equity account: - -2021-01-01 - assets:cash -100 EUR - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - Pro: - - • Preserves the accounting equation - • Keeps track of conversions and related gains/losses in one place - • Standard, works in any double entry accounting system - - Con: - - • More verbose - • Conversion rate is not obvious - • Cost reporting requires adding the –infer-costs flag - - -File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions - -22.6.4 Conversion with equity postings and explicit cost --------------------------------------------------------- - -Here both equity postings and @ notation are used together. - -2021-01-01 - assets:cash -100 EUR @ 1.20 USD - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - Pro: - - • Preserves the accounting equation - • Keeps track of conversions and related gains/losses in one place - • Makes the conversion rate clear - • Provides more error checking - - Con: - - • Most verbose - • Not compatible with ledger - - -File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting - -22.7 Cost tips -============== - - • Recording the cost/conversion rate explicitly is good because it - makes that clear and helps detect errors. - • Recording equity postings is good because it is correct bookkeeping - and preserves the accounting equation. - • Combining these is possible. - • When you want to see the cost (or sale proceeds) of things, use - ‘-B’ (short form of ‘--cost’). - • If you use conversion postings without cost notation, add - ‘--infer-costs’ also. - • If you use cost notation without conversion postings, and you want - to see a balanced balance sheet or print correct journal entries, - use ‘--infer-equity’. - • Conversion to cost is performed before valuation (described next). - - -File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top - -23 Valuation -************ - -Instead of reporting amounts in their original commodity, hledger can -convert them to cost/sale amount (using the conversion rate recorded in -the transaction), and/or to market value (using some market price on a -certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’ -option, which will be described below. We also provide the simpler ‘-V’ -and ‘-X COMMODITY’ options, and often one of these is all you need: - -* Menu: - -* -V Value:: -* -X Value in specified commodity:: -* Valuation date:: -* Finding market price:: -* --infer-market-prices market prices from transactions:: -* Valuation commodity:: -* Simple valuation examples:: -* --value Flexible valuation:: -* More valuation examples:: -* Interaction of valuation and queries:: -* Effect of valuation on reports:: - - -File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation - -23.1 -V: Value -============== - -The ‘-V/--market’ flag converts amounts to market value in their default -_valuation commodity_, using the market prices in effect on the -_valuation date(s)_, if any. More on these in a minute. - - -File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation - -23.2 -X: Value in specified commodity -===================================== - -The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which -currency you want to convert to, and it tries to convert everything to -that. - - -File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation - -23.3 Valuation date -=================== - -Since market prices can change from day to day, market value reports -have a valuation date (or more than one), which determines which market -prices will be used. - - For single period reports, if an explicit report end date is -specified, that will be used as the valuation date; otherwise the -valuation date is the journal’s end date. - - For multiperiod reports, each column/period is valued on the last day -of the period, by default. - - -File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation - -23.4 Finding market price -========================= - -To convert a commodity A to its market value in another commodity B, -hledger looks for a suitable market price (exchange rate) as follows, in -this order of preference : - - 1. A _declared market price_ or _inferred market price_: A’s latest - market price in B on or before the valuation date as declared by a - P directive, or (with the ‘--infer-market-prices’ flag) inferred - from costs. - - 2. A _reverse market price_: the inverse of a declared or inferred - market price from B to A. - - 3. A _forward chain of market prices_: a synthetic price formed by - combining the shortest chain of "forward" (only 1 above) market - prices, leading from A to B. - - 4. _Any chain of market prices_: a chain of any market prices, - including both forward and reverse prices (1 and 2 above), leading - from A to B. - - There is a limit to the length of these price chains; if hledger -reaches that length without finding a complete chain or exhausting all -possibilities, it will give up (with a "gave up" message visible in -‘--debug=2’ output). That limit is currently 1000. - - Amounts for which no suitable market price can be found, are not -converted. - - -File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation - -23.5 –infer-market-prices: market prices from transactions -========================================================== - -Normally, market value in hledger is fully controlled by, and requires, -P directives in your journal. Since adding and updating those can be a -chore, and since transactions usually take place at close to market -value, why not use the recorded costs as additional market prices (as -Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or -‘--value’ enables this. - - So for example, ‘hledger bs -V --infer-market-prices’ will get market -prices both from P directives and from transactions. If both occur on -the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in -confusing/undesired ways by your journal entries. If this happens to -you, read all of this Valuation section carefully, and try adding -‘--debug’ or ‘--debug=2’ to troubleshoot. - - ‘--infer-market-prices’ can infer market prices from: - - • multicommodity transactions with explicit prices (‘@’/‘@@’) - - • multicommodity transactions with implicit prices (no ‘@’, two - commodities, unbalanced). (With these, the order of postings - matters. ‘hledger print -x’ can be useful for troubleshooting.) - - • multicommodity transactions with equity postings, if cost is - inferred with ‘--infer-costs’. - - There is a limitation (bug) currently: when a valuation commodity is -not specified, prices inferred with ‘--infer-market-prices’ do not help -select a default valuation commodity, as ‘P’ prices would. So -conversion might not happen because no valuation commodity was detected -(‘--debug=2’ will show this). To be safe, specify the valuation -commmodity, eg: - - • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’ - • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then - --infer-market-prices’ - - Signed costs and market prices can be confusing. For reference, here -is the current behaviour, since hledger 1.25. (If you think it should -work differently, see #1870.) - -2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - -2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - -2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - -2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - -2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - -2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each -day, the two transactions are considered equivalent). Here are the -market prices inferred for B: - -$ hledger -f- --infer-market-prices prices -P 2022-01-01 B A 1 -P 2022-01-01 B A 1.0 -P 2022-01-02 B A -1 -P 2022-01-02 B A -1.0 -P 2022-01-03 B A -1 -P 2022-01-03 B A -1.0 - - -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation - -23.6 Valuation commodity -======================== - -*When you specify a valuation commodity (‘-X COMM’ or ‘--value -TYPE,COMM’):* -hledger will convert all amounts to COMM, wherever it can find a -suitable market price (including by reversing or chaining prices). - - *When you leave the valuation commodity unspecified (‘-V’ or ‘--value -TYPE’):* -For each commodity A, hledger picks a default valuation commodity as -follows, in this order of preference: - - 1. The price commodity from the latest P-declared market price for A - on or before valuation date. - - 2. The price commodity from the latest P-declared market price for A - on any date. (Allows conversion to proceed when there are inferred - prices before the valuation date.) - - 3. If there are no P directives at all (any commodity or date) and the - ‘--infer-market-prices’ flag is used: the price commodity from the - latest transaction-inferred price for A on or before valuation - date. - - This means: - - • If you have P directives, they determine which commodities ‘-V’ - will convert, and to what. - - • If you have no P directives, and use the ‘--infer-market-prices’ - flag, costs determine it. - - Amounts for which no valuation commodity can be found are not -converted. - - -File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation - -23.7 Simple valuation examples -============================== - -Here are some quick examples of ‘-V’: - -; 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 - - -File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation - -23.8 –value: Flexible valuation -=============================== - -‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option: - - --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. - COMM is an optional commodity symbol. - Shows amounts converted to: - - default valuation commodity (or COMM) using market prices at posting dates - - default valuation commodity (or COMM) using market prices at period end(s) - - default valuation commodity (or COMM) using current market prices - - default valuation commodity (or COMM) using market prices at some date - - The TYPE part selects cost or value and valuation date: - -‘--value=then’ - - Convert amounts to their value in the default valuation commodity, - using market prices on each posting’s date. -‘--value=end’ - - Convert amounts to their value in the default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal’s end date); or in multiperiod reports, - market prices on the last day of each subperiod. -‘--value=now’ - - Convert amounts to their value in the default valuation commodity - using current market prices (as of when report is generated). -‘--value=YYYY-MM-DD’ - - Convert amounts to their value in the default valuation commodity - using market prices on this date. - - To select a different valuation commodity, add the optional ‘,COMM’ -part: a comma, then the target commodity’s symbol. Eg: -*‘--value=now,EUR’*. hledger will do its best to convert amounts to -this commodity, deducing market prices as described above. - - -File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation - -23.9 More valuation examples -============================ - -Here are some examples showing the effect of ‘--value’, as seen with -‘print’: - -P 2000-01-01 A 1 B -P 2000-02-01 A 2 B -P 2000-03-01 A 3 B -P 2000-04-01 A 4 B - -2000-01-01 - (a) 1 A @ 5 B - -2000-02-01 - (a) 1 A @ 6 B - -2000-03-01 - (a) 1 A @ 7 B - - Show the cost of each posting: - -$ hledger -f- print --cost -2000-01-01 - (a) 5 B - -2000-02-01 - (a) 6 B - -2000-03-01 - (a) 7 B - - Show the value as of the last day of the report period (2000-02-29): - -$ hledger -f- print --value=end date:2000/01-2000/03 -2000-01-01 - (a) 2 B - -2000-02-01 - (a) 2 B - - With no report period specified, that shows the value as of the last -day of the journal (2000-03-01): - -$ hledger -f- print --value=end -2000-01-01 - (a) 3 B - -2000-02-01 - (a) 3 B - -2000-03-01 - (a) 3 B - - Show the current value (the 2000-04-01 price is still in effect -today): - -$ hledger -f- print --value=now -2000-01-01 - (a) 4 B - -2000-02-01 - (a) 4 B - -2000-03-01 - (a) 4 B - - Show the value on 2000/01/15: - -$ hledger -f- print --value=2000-01-15 -2000-01-01 - (a) 1 B - -2000-02-01 - (a) 1 B - -2000-03-01 - (a) 1 B - - You may need to explicitly set a commodity’s display style, when -reverse prices are used. Eg this output might be surprising: - -P 2000-01-01 A 2B - -2000-01-01 - a 1B - b - -$ hledger print -x -X A -2000-01-01 - a 0 - b 0 - - Explanation: because there’s no amount or commodity directive -specifying a display style for A, 0.5A gets the default style, which -shows no decimal digits. Because the displayed amount looks like zero, -the commodity symbol and minus sign are not displayed either. Adding a -commodity directive sets a more useful display style for A: - -P 2000-01-01 A 2B -commodity 0.00A - -2000-01-01 - a 1B - b - -$ hledger print -X A -2000-01-01 - a 0.50A - b -0.50A - - -File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation - -23.10 Interaction of valuation and queries -========================================== - -When matching postings based on queries in the presence of valuation, -the following happens. - - 1. The query is separated into two parts: - 1. the currency (‘cur:’) or amount (‘amt:’). - 2. all other parts. - - 2. The postings are matched to the currency and amount queries based - on pre-valued amounts. - 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on - post-valued amounts. - - See: 1625 - - -File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation - -23.11 Effect of valuation on reports -==================================== - -Here is a reference for how valuation is supposed to affect each part of -hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll -sideways.) It may be useful when troubleshooting. If you find -problems, please report them, ideally with a reproducible example. -Related: #329, #1083. - -Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’, -type ‘--cost’ ‘--value=now’ ------------------------------------------------------------------------------- -*print* -posting cost value at value at posting value at value -amounts report end date report or at - or today journal DATE/today - end -balance unchanged unchanged unchanged unchanged unchanged -assertions/assignments -*register* -starting cost value at valued at day value at value -balance report or each historical report or at -(-H) journal posting was made journal DATE/today - end end -starting cost value at valued at day value at value -balance day before each historical day before at -(-H) report or posting was made report or DATE/today -with journal journal -report start start -interval -posting cost value at value at posting value at value -amounts report or date report or at - journal journal DATE/today - end end -summary summarised value at sum of postings value at value -posting cost period in interval, period at -amounts ends valued at ends DATE/today -with interval start -report -interval -running sum/average sum/average sum/average of sum/average sum/average -total/averageof of displayed values of of - displayed displayed displayed displayed - values values values values -*balance -(bs, -bse, cf, -is)* -balance sums of value at value at posting value at value -changes costs report end date report or at - or today journal DATE/today - of sums of end of of - postings sums of sums - postings of - postings -budget like like like balance like like -amounts balance balance changes balances balance -(–budget) changes changes changes -grand sum of sum of sum of displayed sum of sum of -total displayed displayed valued displayed displayed - values values values values -*balance -(bs, -bse, cf, -is) with -report -interval* -starting sums of value at sums of values value at sums -balances costs of report of postings report of -(-H) postings start of before report start of postings - before sums of start at sums of before - report all respective all report - start postings posting dates postings start - before before - report report - start start -balance sums of same as sums of values balance value -changes costs of –value=end of postings in change in at -(bal, postings period at each DATE/today -is, bs in period respective period, of -–change, posting dates valued at sums -cf period of -–change) ends postings -end sums of same as sums of values period end value -balances costs of –value=end of postings from balances, at -(bal -H, postings before period valued at DATE/today -is –H, from start to period period of -bs, cf) before end at ends sums - report respective of - start to posting dates postings - period end -budget like like like balance like like -amounts balance balance changes/end balances balance -(–budget) changes/end changes/end balances changes/end - balances balances balances -row sums, sums, sums, averages sums, sums, -totals, averages averages of displayed averages averages -row of of values of of -averages displayed displayed displayed displayed -(-T, -A) values values values values -column sums of sums of sums of sums of sums -totals displayed displayed displayed values displayed of - values values values displayed - values -grand sum, sum, sum, average of sum, sum, -total, average of average of column totals average of average -grand column column column of -average totals totals totals column - totals - - ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with -a zero starting balance. - - *Glossary:* - -_cost_ - - calculated using price(s) recorded in the transaction(s). -_value_ - - market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. -_report start_ - - the first day of the report period specified with -b or -p or - date:, otherwise today. -_report or journal start_ - - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. -_report end_ - - the last day of the report period specified with -e or -p or date:, - otherwise today. -_report or journal end_ - - the last day of the report period specified with -e or -p or date:, - otherwise the latest transaction date in the journal, otherwise - today. -_report interval_ - - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report’s multi-period mode (whether showing one or many - subperiods). - - -File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top - -24 PART 4: COMMANDS -******************* - -* Menu: - -* Commands overview:: -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* register:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: - - -File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS - -24.1 Commands overview -====================== - -Here are the built-in commands: - -* Menu: - -* DATA ENTRY:: -* DATA CREATION:: -* DATA MANAGEMENT:: -* REPORTS FINANCIAL:: -* REPORTS VERSATILE:: -* REPORTS BASIC:: -* HELP:: -* ADD-ONS:: - - -File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview - -24.1.1 DATA ENTRY ------------------ - -These data entry commands are the only ones which can modify your -journal file. - - • add - add transactions using terminal prompts - • import - add new transactions from other files, eg CSV files - - -File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview - -24.1.2 DATA CREATION --------------------- - - • close - generate balance-zeroing/restoring transactions - • rewrite - generate auto postings, like print –auto - - -File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview - -24.1.3 DATA MANAGEMENT ----------------------- - - • check - check for various kinds of error in the data - • diff - compare account transactions in two journal files - - -File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview - -24.1.4 REPORTS, FINANCIAL -------------------------- - - • aregister (areg) - show transactions in a particular account - • 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 - - -File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview - -24.1.5 REPORTS, VERSATILE -------------------------- - - • balance (bal) - show balance changes, end balances, budgets, - gains.. - • print - show transactions or export journal data - • register (reg) - show postings in one or more accounts & running - total - • roi - show return on investments - - -File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview - -24.1.6 REPORTS, BASIC ---------------------- - - • accounts - show account names - • activity - show bar charts of posting counts per period - • codes - show transaction codes - • commodities - show commodity/currency symbols - • descriptions - show transaction descriptions - • files - show input file paths - • notes - show note parts of transaction descriptions - • payees - show payee parts of transaction descriptions - • prices - show market prices - • stats - show journal statistics - • tags - show tag names - • test - run self tests - - -File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview - -24.1.7 HELP ------------ - - • help - show the hledger manual with info/man/pager - - -File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview - -24.1.8 ADD-ONS --------------- - -And here are some typical add-on commands. Some of these are installed -by the hledger-install script. If installed, they will appear in -hledger’s commands list: - - • ui - run hledger’s terminal UI - • web - run hledger’s web UI - • iadd - add transactions using a TUI (currently hard to build) - • interest - generate interest transactions - • stockquotes - download market prices from AlphaVantage - • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, - pijul, plot, and more.. - - Next, each command is described in detail, in alphabetical order. - - -File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS - -24.2 accounts -============= - -Show account names. - - This command lists account names. By default it shows all known -accounts, either used in transactions or declared with account -directives. - - With query arguments, only matched account names and account names -referenced by matched postings are shown. - - Or it can show just the used accounts (‘--used’/‘-u’), the declared -accounts (‘--declared’/‘-d’), the accounts declared but not used -(‘--unused’), the accounts used but not declared (‘--undeclared’), or -the first account matched by an account name pattern, if any (‘--find’). - - 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’. - - With ‘--types’, it also shows each account’s type, if it’s known. -(See Declaring accounts > Account types.) - - With ‘--positions’, it also shows the file and line number of each -account’s declaration, if any, and the account’s overall declaration -order; these may be useful when troubleshooting account display order. - - With ‘--directives’, it adds the ‘account’ keyword, showing valid -account directives which can be pasted into a journal file. This is -useful together with ‘--undeclared’ when updating your account -declarations to satisfy ‘hledger check accounts’. - - The ‘--find’ flag can be used to look up a single account name, in -the same way that the ‘aregister’ command does. It returns the -alphanumerically-first matched account name, or if none can be found, it -fails with a non-zero exit code. - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - -$ hledger accounts --undeclared --directives >> $LEDGER_FILE -$ hledger check accounts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS - -24.3 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: aregister, Prev: activity, Up: PART 4 COMMANDS - -24.4 add -======== - -Prompt for transactions and add them to the journal. Any arguments will -be used as default inputs for the first N prompts. - - 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 main journal file (which should be -in journal format). Existing transactions are not changed. This is one -of the few hledger commands that writes to the journal file (see also -‘import’). - - 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, - payees/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 go one step - backward. - • Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see https://hledger.org/add.html for a detailed tutorial): - -$ 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 go one step backward. -To end a transaction, enter . when prompted. -To quit, enter . at a date prompt or press control-d or control-c. -Date [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]: $ - - On Microsoft Windows, the add command makes sure that no part of the -file path ends with a period, as that would cause problems (#1056). - - -File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS - -24.5 aregister -============== - -(areg) - - Show the transactions and running historical balance of a single -account, with each transaction displayed as one line. - - ‘aregister’ shows the overall transactions affecting a particular -account (and any subaccounts). Each report line represents one -transaction in this account. Transactions before the report start date -are always included in the running balance (‘--historical’ mode is -always on). - - This is a more "real world", bank-like view than the ‘register’ -command (which shows individual postings, possibly from multiple -accounts, not necessarily in historical mode). As a quick rule of -thumb: - use ‘aregister’ for reviewing and reconciling real-world -asset/liability accounts - use ‘register’ for reviewing detailed -revenues/expenses. - - ‘aregister’ requires one argument: the account to report on. You can -write either the full account name, or a case-insensitive regular -expression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can -be surprising; eg if you have ‘assets:per:checking 1’ and -‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select -‘assets:biz:checking 2’. It’s just a convenience to save typing, so if -in doubt, write the full account name, or a distinctive substring that -matches uniquely. - - Transactions involving subaccounts of this account will also be -shown. ‘aregister’ ignores depth limits, so its final total will always -match a balance report with similar arguments. - - Any additional arguments form a query which will filter the -transactions shown. Note some queries will disturb the running balance, -causing it to be different from the account’s real-world running -balance. - - An example: this shows the transactions and historical running -balance during july, in the first account whose name contains -"checking": - -$ hledger areg checking date:jul - - Each ‘aregister’ line item shows: - - • the transaction’s date (or the relevant posting’s date if - different, see below) - • the names of all the other account(s) involved in this transaction - (probably abbreviated) - • the total change to this account’s balance from this transaction - • the account’s historical running balance after this transaction. - - Transactions making a net change of zero are not shown by default; -add the ‘-E/--empty’ flag to show them. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -‘--align-all’ flag. - - This command also supports the output destination and output format -options. The output formats supported are ‘txt’, ‘csv’, and ‘json’. - -* Menu: - -* aregister and custom posting dates:: - - -File: hledger.info, Node: aregister and custom posting dates, Up: aregister - -24.5.1 aregister and custom posting dates ------------------------------------------ - -Transactions whose date is outside the report period can still be shown, -if they have a posting to this account dated inside the report period. -(And in this case it’s the posting date that is shown.) This ensures -that ‘aregister’ can show an accurate historical running balance, -matching the one shown by ‘register -H’ with the same arguments. - - To filter strictly by transaction date instead, add the ‘--txn-dates’ -flag. If you use this flag and some of your postings have custom dates, -it’s probably best to assume the running balance is wrong. - - -File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS - -24.6 balance -============ - -(bal) - - Show accounts and their balances. - - ‘balance’ is one of hledger’s oldest and most versatile commands, for -listing account balances, balance changes, values, value changes and -more, during one time period or many. Generally it shows a table, with -rows representing accounts, and columns representing periods. - - Note there are some higher-level variants of the ‘balance’ command -with convenient defaults, which can be simpler to use: ‘balancesheet’, -‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need -more control, then use ‘balance’. - -* Menu: - -* balance features:: -* Simple balance report:: -* Balance report line format:: -* Filtered balance report:: -* List or tree mode:: -* Depth limiting:: -* Dropping top-level accounts:: -* Showing declared accounts:: -* Sorting by amount:: -* Percentages:: -* Multi-period balance report:: -* Balance change end balance:: -* Balance report types:: -* Budget report:: -* Data layout:: -* Useful balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -24.6.1 balance features ------------------------ - -Here’s a quick overview of the ‘balance’ command’s features, followed by -more detailed descriptions and examples. Many of these work with the -higher-level commands as well. - - ‘balance’ can show.. - - • accounts as a list (‘-l’) or a tree (‘-t’) - • optionally depth-limited (‘-[1-9]’) - • sorted by declaration order and name, or by amount - - ..and their.. - - • balance changes (the default) - • or actual and planned balance changes (‘--budget’) - • or value of balance changes (‘-V’) - • or change of balance values (‘--valuechange’) - • or unrealised capital gain/loss (‘--gain’) - - ..in.. - - • one time period (the whole journal period by default) - • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’) - - ..either.. - - • per period (the default) - • or accumulated since report start date (‘--cumulative’) - • or accumulated since account creation (‘--historical/-H’) - - ..possibly converted to.. - - • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’) - • or market value, as of transaction dates (‘--value=then[,COMM]’) - • or at period ends (‘--value=end[,COMM]’) - • or now (‘--value=now’) - • or at some other date (‘--value=YYYY-MM-DD’) - - ..with.. - - • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign - (‘--invert’) - • rows and columns swapped (‘--transpose’) - • another field used as account name (‘--pivot’) - • custom-formatted line items (single-period reports only) - (‘--format’) - • commodities displayed on the same line or multiple lines - (‘--layout’) - - This command supports the output destination and output format -options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period -reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal, -negative amounts are shown in red. - - The ‘--related’/‘-r’ flag shows the balance of the _other_ postings -in the transactions of the postings which would normally be shown. - - -File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance - -24.6.2 Simple balance report ----------------------------- - -With no arguments, ‘balance’ shows a list of all accounts and their -change of balance - ie, the sum of posting amounts, both inflows and -outflows - during the entire period of the journal. ("Simple" here -means just one column of numbers, covering a single period. You can -also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end -balance at the end of the journal period; more on this below. - - Accounts are sorted by declaration order if any, and then -alphabetically by account name. For instance (using -examples/sample.journal): - -$ hledger -f examples/sample.journal bal - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - Accounts with a zero balance (and no non-zero subaccounts, in tree -mode - see below) are hidden by default. Use ‘-E/--empty’ to show them -(revealing ‘assets:bank:checking’ here): - -$ hledger -f examples/sample.journal bal -E - 0 assets:bank:checking - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - The total of the amounts displayed is shown as the last line, unless -‘-N’/‘--no-total’ is used. - - -File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance - -24.6.3 Balance report line format ---------------------------------- - -For single-period balance reports displayed in the terminal (only), you -can use ‘--format FMT’ to customise the format and content of each line. -Eg: - -$ hledger -f examples/sample.journal 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 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: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance - -24.6.4 Filtered balance report ------------------------------- - -You can show fewer accounts, a different time period, totals from -cleared transactions only, etc. by using query arguments or options to -limit the postings being matched. Eg: - -$ hledger -f examples/sample.journal bal --cleared assets date:200806 - $-2 assets:cash --------------------- - $-2 - - -File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance - -24.6.5 List or tree mode ------------------------- - -By default, or with ‘-l/--flat’, accounts are shown as a flat list with -their full names visible, as in the examples above. - - With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’ -"leaf" names indented below their parent: - -$ hledger -f examples/sample.journal balance - $-1 assets - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts --------------------- - 0 - - Notes: - - • "Boring" accounts are combined with their subaccount for more - compact output, unless ‘--no-elide’ is used. Boring accounts have - no balance of their own and just one subaccount (eg ‘assets:bank’ - and ‘liabilities’ above). - - • All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, - which requires explanation when sharing reports with - non-plaintextaccounting-users. A tree mode report’s final total is - the sum of the top-level balances shown, not of all the balances - shown. - - • Each group of sibling accounts (ie, under a common parent) is - sorted separately. - - -File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance - -24.6.6 Depth limiting ---------------------- - -With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg: -‘-3’) balance reports will show accounts only to the specified depth, -hiding the deeper subaccounts. This can be useful for getting an -overview without too much detail. - - Account balances at the depth limit always include the balances from -any deeper subaccounts (even in list mode). Eg, limiting to depth 1: - -$ hledger -f examples/sample.journal balance -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities --------------------- - 0 - - -File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance - -24.6.7 Dropping top-level accounts ----------------------------------- - -You can also hide one or more top-level account name parts, using -‘--drop NUM’. This can be useful for hiding repetitive top-level -account names: - -$ hledger -f examples/sample.journal bal expenses --drop 1 - $1 food - $1 supplies --------------------- - $2 - - -File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance - -24.6.8 Showing declared accounts --------------------------------- - -With ‘--declared’, accounts which have been declared with an account -directive will be included in the balance report, even if they have no -transactions. (Since they will have a zero balance, you will also need -‘-E/--empty’ to see them.) - - More precisely, _leaf_ declared accounts (with no subaccounts) will -be included, since those are usually the more useful in reports. - - The idea of this is to be able to see a useful "complete" balance -report, even when you don’t have transactions in all of your declared -accounts yet. - - -File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance - -24.6.9 Sorting by amount ------------------------- - -With ‘-S/--sort-amount’, accounts with the largest (most positive) -balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your -biggest averaged monthly expenses first. When more than one commodity -is present, they will be sorted by the alphabetically earliest commodity -first, and then by subsequent commodities (if an amount is missing a -commodity, it is treated as 0). - - Revenues and liability balances are typically negative, however, so -‘-S’ shows these in reverse order. To work around this, you can add -‘--invert’ to flip the signs. (Or, use one of the higher-level reports, -which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’). - - -File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance - -24.6.10 Percentages -------------------- - -With ‘-%/--percent’, balance reports show each account’s value expressed -as a percentage of the (column) total. - - Note it is not useful to calculate percentages if the amounts in a -column have mixed signs. In this case, make a separate report for each -sign, eg: - -$ hledger bal -% amt:`>0` -$ hledger bal -% amt:`<0` - - Similarly, if the amounts in a column have mixed commodities, convert -them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a -separate report for each commodity: - -$ hledger bal -% cur:\\$ -$ hledger bal -% cur:€ - - -File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance - -24.6.11 Multi-period balance report ------------------------------------ - -With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’, -‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag), -‘balance’ shows a tabular report, with columns representing successive -time periods (and a title): - -$ hledger -f examples/sample.journal bal --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 - - Notes: - - • The report’s start/end dates will be expanded, if necessary, to - fully encompass the displayed subperiods (so that the first and - last subperiods have the same duration as the others). - • Leading and trailing periods (columns) containing all zeroes are - not shown, unless ‘-E/--empty’ is used. - • Accounts (rows) containing all zeroes are not shown, unless - ‘-E/--empty’ is used. - • Amounts with many commodities are shown in abbreviated form, unless - ‘--no-elide’ is used. _(experimental)_ - • Average and/or total columns can be added with the ‘-A/--average’ - and ‘-T/--row-total’ flags. - • The ‘--transpose’ flag can be used to exchange rows and columns. - • The ‘--pivot FIELD’ option causes a different transaction field to - be used as "account name". See PIVOTING. - - Multi-period reports with many periods can be too wide for easy -viewing in the terminal. Here are some ways to handle that: - - • Hide the totals row with ‘-N/--no-total’ - • Convert to a single currency with ‘-V’ - • Maximize the terminal window - • Reduce the terminal’s font size - • View with a pager like less, eg: ‘hledger bal -D --color=yes | less - -RS’ - • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D - -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or - a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’) - • Output as HTML and view with a browser: ‘hledger bal -D -o a.html - && open a.html’ - - -File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance - -24.6.12 Balance change, end balance ------------------------------------ - -It’s important to be clear on the meaning of the numbers shown in -balance reports. Here is some terminology we use: - - A *_balance change_* is the net amount added to, or removed from, an -account during some period. - - An *_end balance_* is the amount accumulated in an account as of some -date (and some time, but hledger doesn’t store that; assume end of day -in your timezone). It is the sum of previous balance changes. - - We call it a *_historical end balance_* if it includes all balance -changes since the account was created. For a real world account, this -means it will match the "historical record", eg the balances reported in -your bank statements or bank web UI. (If they are correct!) - - In general, balance changes are what you want to see when reviewing -revenues and expenses, and historical end balances are what you want to -see when reviewing or reconciling asset, liability and equity accounts. - - ‘balance’ shows balance changes by default. To see accurate -historical end balances: - - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the - journal covers the account’s full lifetime. - - 2. Include all of of the account’s prior postings in the report, by - not specifying a report start date, or by using the - ‘-H/--historical’ flag. (‘-H’ causes report start date to be - ignored when summing postings.) - - -File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance - -24.6.13 Balance report types ----------------------------- - -The balance command is quite flexible; here is the full detail on how to -control what it reports. If the following seems complicated, don’t -worry - this is for advanced reporting, and it does typically take some -time and experimentation to get clear on all these report modes. - - There are three important option groups: - - ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] -...’ - -* Menu: - -* Calculation type:: -* Accumulation type:: -* Valuation type:: -* Combining balance report types:: - - -File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types - -24.6.13.1 Calculation type -.......................... - -The basic calculation to perform for each table cell. It is one of: - - • ‘--sum’ : sum the posting amounts (*default*) - • ‘--budget’ : sum the amounts, but also show the budget goal amount - (for each account/period) - • ‘--valuechange’ : show the change in period-end historical balance - values (caused by deposits, withdrawals, and/or market price - fluctuations) - • ‘--gain’ : show the unrealised capital gain/loss, (the current - valued balance minus each amount’s original cost) - - -File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types - -24.6.13.2 Accumulation type -........................... - -How amounts should accumulate across report periods. Another way to say -it: which time period’s postings should contribute to each cell’s -calculation. It is one of: - - • ‘--change’ : calculate with postings from column start to column - end, ie "just this column". Typically used to see - revenues/expenses. (*default for balance, incomestatement*) - - • ‘--cumulative’ : calculate with postings from report start to - column end, ie "previous columns plus this column". Typically used - to show changes accumulated since the report’s start date. Not - often used. - - • ‘--historical/-H’ : calculate with postings from journal start to - column end, ie "all postings from before report start date until - this column’s end". Typically used to see historical end balances - of assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) - - -File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types - -24.6.13.3 Valuation type -........................ - -Which kind of value or cost conversion should be applied, if any, before -displaying the report. It is one of: - - • no valuation type : don’t convert to cost or value (*default*) - • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to - some other commodity) - • ‘--value=then[,COMM]’ : convert amounts to market value on - transaction dates - • ‘--value=end[,COMM]’ : convert amounts to market value on period - end date(s) - (*default with ‘--valuechange’, ‘--gain’*) - • ‘--value=now[,COMM]’ : convert amounts to market value on today’s - date - • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on - another date - - or one of the equivalent simpler flags: - - • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are - independent options which can both be used at once) - • ‘-V/--market’ : like –value=end - • ‘-X COMM/--exchange COMM’ : like –value=end,COMM - - See Cost reporting and Valuation for more about these. - - -File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types - -24.6.13.4 Combining balance report types -........................................ - -Most combinations of these options should produce reasonable reports, -but if you find any that seem wrong or misleading, let us know. The -following restrictions are applied: - - • ‘--valuechange’ implies ‘--value=end’ - • ‘--valuechange’ makes ‘--change’ the default when used with the - ‘balancesheet’/‘balancesheetequity’ commands - • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’ - - For reference, here is what the combinations of accumulation and -valuation show: - -Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value= -Accumulation:v YYYY-MM-DD - /now’ ------------------------------------------------------------------------------ -‘--change’change in sum of period-end DATE-value - period posting-date value of of change in - market values change in period - in period period -‘--cumulative’change from sum of period-end DATE-value - report start to posting-date value of of change - period end market values change from from report - from report report start start to - start to period to period end period end - end -‘--historicalchange from sum of period-end DATE-value -/-H’ journal start posting-date value of of change - to period end market values change from from journal - (historical end from journal journal start start to - balance) start to period to period end period end - end - - -File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance - -24.6.14 Budget report ---------------------- - -The ‘--budget’ report type activates extra columns showing any budget -goals for each account and period. The budget goals are defined by -periodic transactions. This is useful for comparing planned and actual -income, expenses, time usage, etc. - - 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] - - This is different from a normal balance report in several ways: - - • Only accounts with budget goals during the report period are shown, - by default. - - • In each column, in square brackets after the actual amount, budget - goal amounts are shown, and the actual/goal percentage. (Note: - budget goals should be in the same commodity as the actual amount.) - - • All parent accounts are always shown, even in list mode. Eg - assets, assets:bank, and expenses above. - - • Amounts always include all subaccounts, budgeted or unbudgeted, - even in list mode. - - This means that the numbers displayed will not always add up! Eg -above, the ‘expenses’ actual amount includes the gifts and supplies -transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts -are not shown, as they have no budget amounts declared. - - This can be confusing. When you need to make things clearer, use the -‘-E/--empty’ flag, which will reveal all accounts including unbudgeted -ones, giving the full picture. Eg: - -$ 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] - - It’s common to limit budgets/budget reports to just expenses - -hledger bal -M --budget expenses - - or just revenues and expenses (eg, using account types): - -hledger bal -M --budget type:rx - - It’s also common to limit or convert them to a single currency -(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple -currencies, ‘--layout bare’ or ‘--layout tall’ can help. - - For more examples and notes, see Budgeting. - -* Menu: - -* Budget report start date:: -* Budgets and subaccounts:: -* Selecting budget goals:: -* Budget vs forecast:: - - -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report - -24.6.14.1 Budget report start date -.................................. - -This might be a bug, but for now: when making budget reports, it’s a -good idea to explicitly set the report’s start date to the first day of -a reporting period, because a periodic rule like ‘~ monthly’ generates -its transactions on the 1st of each month, and if your journal has no -regular transactions on the 1st, the default report start date could -exclude that budget goal, which can be a little surprising. Eg here the -default report period is just the day of 2020-01-15: - -~ monthly in 2020 - (expenses:food) $500 - -2020-01-15 - expenses:food $400 - assets:checking - -$ hledger bal expenses --budget -Budget performance in 2020-01-15: - - || 2020-01-15 -==============++============ - || $400 ---------------++------------ - || $400 - - To avoid this, specify the budget report’s period, or at least the -start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the -budget goal transactions (periodic transactions) that you want. Eg, -adding ‘-b 2020/1/1’ to the above: - -$ hledger bal expenses --budget -b 2020/1/1 -Budget performance in 2020-01-01..2020-01-15: - - || 2020-01-01..2020-01-15 -===============++======================== - expenses:food || $400 [80% of $500] ----------------++------------------------ - || $400 [80% of $500] - - -File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report - -24.6.14.2 Budgets and subaccounts -................................. - -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 implicitly -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] - - -File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report - -24.6.14.3 Selecting budget goals -................................ - -The budget report evaluates periodic transaction rules to generate -special "goal transactions", which generate the goal amounts for each -account in each report subperiod. When troubleshooting, you can use -‘print --forecast’ to show these as forecasted transactions: - -$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated - - By default, the budget report uses all available periodic transaction -rules to generate goals. This includes rules with a different report -interval from your report. Eg if you have daily, weekly and monthly -periodic rules, all of these will contribute to the goals in a monthly -budget report. - - You can select a subset of periodic rules by providing an argument to -the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules -whose description contains DESCPAT, a case-insensitive substring (not a -regular expression or query). This means you can give your periodic -rules descriptions (remember that two spaces are needed), and then -select from multiple budgets defined in your journal. - - -File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report - -24.6.14.4 Budget vs forecast -............................ - -‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate -features, though both of them use the periodic transaction rules defined -in the journal, and both of them generate temporary transactions for -reporting purposes ("forecast transactions" and "budget goal -transactions", respectively). You can use both features at the same -time if you want. Here are some differences between them, as of hledger -1.29: - - CLI: - - • –forecast is a general hledger option, usable with any command - • –budget is a ‘balance’ command option, usable only with that - command. - - Visibility of generated transactions: - - • forecast transactions are visible in any report, like ordinary - transactions - • budget goal transactions are invisible except for the goal amounts - they produce in –budget reports. - - Periodic transaction rules: - - • –forecast uses all available periodic transaction rules - • –budget uses all periodic rules (‘--budget’) or a selected subset - (‘--budget=DESCPAT’) - - Period of generated transactions: - - • –forecast generates forecast transactions - • from after the last regular transaction to the end of the - report period (‘--forecast’) - • or, during a specified period (‘--forecast=PERIODEXPR’) - • possibly further restricted by a period specified in the - periodic transaction rule - • and always restricted within the bounds of the report period - - • –budget generates budget goal transactions - • throughout the report period - • possibly restricted by a period specified in the periodic - transaction rule. - - -File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance - -24.6.15 Data layout -------------------- - -The ‘--layout’ option affects how balance reports show multi-commodity -amounts and commodity symbols, which can improve readability. It can -also normalise the data for easy consumption by other programs. It has -four possible values: - - • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line, - optionally elided to WIDTH - • ‘--layout=tall’: each commodity is shown on a separate line - • ‘--layout=bare’: commodity symbols are in their own column, amounts - are bare numbers - • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form, - with one row per data value - - Here are the ‘--layout’ modes supported by each output format; note -only CSV output supports all of them: - -- txt csv html json sql ---------------------------------------- -wide Y Y Y -tall Y Y Y -bare Y Y Y -tidy Y - - Examples: - - • Wide layout. With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - • Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - • Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - • Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - • Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - • Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here’s how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - -File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance - -24.6.16 Useful balance reports ------------------------------- - -Some frequently used ‘balance’ options/reports are: - - • ‘bal -M revenues expenses’ - Show revenues/expenses in each month. Also available as the - ‘incomestatement’ command. - - • ‘bal -M -H assets liabilities’ - Show historical asset/liability balances at each month end. Also - available as the ‘balancesheet’ command. - - • ‘bal -M -H assets liabilities equity’ - Show historical asset/liability/equity balances at each month end. - Also available as the ‘balancesheetequity’ command. - - • ‘bal -M assets not:receivable’ - Show changes to liquid assets in each month. Also available as the - ‘cashflow’ command. - - Also: - - • ‘bal -M expenses -2 -SA’ - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - • ‘bal -M --budget expenses’ - Show monthly expenses and budget goals. - - • ‘bal -M --valuechange investments’ - Show monthly change in market value of investment assets. - - • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert]’ - Show top gainers [or losers] last week - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS - -24.7 balancesheet -================= - -(bs) - - This command displays a balance sheet, showing historical ending -balances of asset and liability accounts. (To see equity as well, use -the balancesheetequity command.) Amounts are shown with normal positive -sign, as in conventional financial statements. - - This report shows accounts declared with the ‘Asset’, ‘Cash’ or -‘Liability’ type (see account types). Or if no such accounts are -declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case -insensitive, plurals allowed) and their subaccounts. - - Example: - -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance -H assets liabilities’, but with -smarter account detection, and liabilities displayed with their sign -flipped. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS - -24.8 balancesheetequity -======================= - -(bse) - - This command displays a balance sheet, showing historical ending -balances of asset, liability and equity accounts. Amounts are shown -with normal positive sign, as in conventional financial statements. - - This report shows accounts declared with the ‘Asset’, ‘Cash’, -‘Liability’ or ‘Equity’ type (see account types). Or if no such -accounts are declared, it shows top-level accounts named ‘asset’, -‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their -subaccounts. - - 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 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance -H assets liabilities equity’, but -with smarter account detection, and liabilities/equity displayed with -their sign flipped. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS - -24.9 cashflow -============= - -(cf) - - This command displays a cashflow statement, showing the inflows and -outflows affecting "cash" (ie, liquid, easily convertible) assets. -Amounts are shown with normal positive sign, as in conventional -financial statements. - - This report shows accounts declared with the ‘Cash’ type (see account -types). Or if no such accounts are declared, it shows accounts - - • under a top-level account named ‘asset’ (case insensitive, plural - allowed) - • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or - ‘saving’. - - More precisely: all accounts matching this case insensitive regular -expression: - - ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’ - - and their subaccounts. - - An example cashflow report: - -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance assets not:fixed not:investment -not:receivable’, but with smarter account detection. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS - -24.10 check -=========== - -Check for various kinds of errors in your data. - - hledger provides a number of built-in error checks to help prevent -problems in your data. Some of these are run automatically; or, you can -use this ‘check’ command to run them on demand, with no output and a -zero exit code if all is well. Specify their names (or a prefix) as -argument(s). - - Some examples: - -hledger check # basic checks -hledger check -s # basic + strict checks -hledger check ordereddates payees # basic + two other checks - - If you are an Emacs user, you can also configure flycheck-hledger to -run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available: - -* Menu: - -* Basic checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: -* More about specific checks:: - - -File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check - -24.10.1 Basic checks --------------------- - -These checks are always run automatically, by (almost) all hledger -commands, including ‘check’: - - • *parseable* - data files are well-formed and can be successfully - parsed - - • *balancedwithautoconversion* - all transactions are balanced, - inferring missing amounts where necessary, and possibly converting - commodities using costs or automatically-inferred costs - - • *assertions* - all balance assertions in the journal are passing. - (This check can be disabled with ‘-I’/‘--ignore-assertions’.) - - -File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check - -24.10.2 Strict checks ---------------------- - -These additional checks are run when the ‘-s’/‘--strict’ (strict mode) -flag is used. Or, they can be run by giving their names as arguments to -‘check’: - - • *accounts* - all account names used by transactions have been - declared - - • *commodities* - all commodity symbols used have been declared - - • *balancednoautoconversion* - transactions are balanced, possibly - using explicit costs but not inferred ones - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -24.10.3 Other checks --------------------- - -These checks can be run only by giving their names as arguments to -‘check’. They are more specialised and not desirable for everyone, -therefore optional: - - • *ordereddates* - transactions are ordered by date within each file - - • *payees* - all payees used by transactions have been declared - - • *recentassertions* - all accounts with balance assertions have a - balance assertion no more than 7 days before their latest posting - - • *tags* - all tags used by transactions have been declared - - • *uniqueleafnames* - all account leaf names are unique - - -File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check - -24.10.4 Custom checks ---------------------- - -A few more checks are are available as separate add-on commands, in -https://github.com/simonmichael/hledger/tree/master/bin: - - • *hledger-check-tagfiles* - all tag values containing / (a forward - slash) exist as file paths - - • *hledger-check-fancyassertions* - more complex balance assertions - are passing - - You could make similar scripts to perform your own custom checks. -See: Cookbook -> Scripting. - - -File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check - -24.10.5 More about specific checks ----------------------------------- - -‘hledger check recentassertions’ will complain if any balance-asserted -account does not have a balance assertion within 7 days before its -latest posting. This aims to prevent the situation where you are -regularly updating your journal, but forgetting to check your balances -against the real world, then one day must dig back through months of -data to find an error. It assumes that adding a balance assertion -requires/reminds you to check the real-world balance. That may not be -true if you auto-generate balance assertions from bank data; in that -case, I recommend to import transactions uncleared, then use the -manual-review-and-mark-cleared phase as a reminder to check the latest -assertions against real-world balances. - - -File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS - -24.11 close -=========== - -‘close [--retain | --migrate | --open] [QUERY]’ - - By default: prints a transaction that zeroes out ("closes") all -accounts, transferring their balances to an equity account. Query -arguments can be added to override the accounts selection. Three other -modes are supported: - - ‘--retain’: prints a transaction closing revenue and expense -balances. This is traditionally done by businesses at the end of each -accounting period; it is less necessary in personal and computer-based -accounting, but it can help balance the accounting equation A=L+E. - - ‘--migrate’: prints a transaction to close asset, liability and most -equity balances, and another transaction to re-open them. This can be -useful when starting a new file (for performance or data protection). -Adding the closing transaction to the old file allows old and new files -to be combined. - - ‘--open’: as above, but prints just the opening transaction. This -can be useful for starting a new file, leaving the old file unchanged. -Similar to Ledger’s equity command. - - You can change the equity account name with ‘--close-acct ACCT’. It -defaults to ‘equity:retained earnings’ with ‘--retain’, or -‘equity:opening/closing balances’ otherwise. - - You can change the transaction description(s) with ‘--close-desc -'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with -‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise. - - Just one posting to the equity account will be used by default, with -an implicit amount. - - With ‘--x/--explicit’ the amount will be shown explicitly, and if it -involves multiple commodities, a separate posting will be generated for -each commodity. - - With ‘--interleaved’, each equity posting is shown next to the -corresponding source/destination posting. - - The default closing date is yesterday or the journal’s end date, -whichever is later. You can change this by specifying a report end -date; the last day of the report period will be the closing date. Eg -‘-e 2022’ means "close on 2022-12-31". - - The default closing date is yesterday, or the journal’s end date, -whichever is later. You can change this by specifying a report end -date; (The report start date does not matter.) The last day of the -report period will be the closing date; eg ‘-e 2022’ means "close on -2022-12-31". The opening date is always the day after the closing date. - -* Menu: - -* close and costs:: -* close and balance assertions:: -* Example retain earnings:: -* Example migrate balances to a new file:: -* Example excluding closing/opening transactions:: - - -File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close - -24.11.1 close and costs ------------------------ - -With ‘--show-costs’, any amount costs are shown, with separate postings -for each cost. (This currently the best way to view investment assets, -showing lots and cost bases.) If you have many currency conversion or -investment transactions, it can generate very large journal entries. - - -File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close - -24.11.2 close and balance assertions ------------------------------------- - -Balance assertions will be generated, verifying that the accounts have -been reset to zero (and then restored to their previous balances, if -there is an opening transaction). - - These provide useful error checking, but you can ignore them -temporarily with ‘-I’, or remove them if you prefer. - - You probably should avoid filtering transactions by status or -realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’), -with this command, since the balance assertions would depend on these. - - Note custom posting dates spanning the file boundary will disrupt the -balance assertions: - -2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve that you can transfer the money to and from a temporary -account, in effect splitting the multi-day transaction into two -single-day transactions: - -; in 2022.journal: -2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - -; in 2023.journal: -2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - -File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close - -24.11.3 Example: retain earnings --------------------------------- - -Record 2022’s revenues/expenses as retained earnings on 2022-12-31, -appending the generated transaction to the journal: - -$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - Now 2022’s income statement will show only zeroes. To see it again, -exclude the retain transaction. Eg: - -$ hledger -f 2022.journal is not:desc:'retain earnings' - - -File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close - -24.11.4 Example: migrate balances to a new file ------------------------------------------------ - -Close assets/liabilities/equity on 2022-12-31 and re-open them on -2023-01-01: - -$ hledger close --migrate -f 2022.journal -p 2022 -# copy/paste the closing transaction to the end of 2022.journal -# copy/paste the opening transaction to the start of 2023.journal - - Now 2022’s balance sheet will show only zeroes, indicating a balanced -accounting equation. (Unless you are using @/@@ notation - in that -case, try adding –infer-equity.) To see it again, exclude the closing -transaction. Eg: - -$ hledger -f 2022.journal bs not:desc:'closing balances' - - -File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close - -24.11.5 Example: excluding closing/opening transactions -------------------------------------------------------- - -When combining many files for multi-year reports, the closing/opening -transactions cause some noise in reports like ‘print’ and ‘register’. -You can exclude them as shown above, but ‘not:desc:...’ could be -fragile, and also you will need to avoid excluding the very first -opening transaction, which can be awkward. Here is a way to do it, -using tags: add ‘clopen:’ tags to all opening/closing balances -transactions except the first, like this: - -; 2021.journal -2021-06-01 first opening balances -... -2021-12-31 closing balances ; clopen:2022 -... - -; 2022.journal -2022-01-01 opening balances ; clopen:2022 -... -2022-12-31 closing balances ; clopen:2023 -... - -; 2023.journal -2023-01-01 opening balances ; clopen:2023 -... - - Now, assuming a combined journal like: - -; all.journal -include 2021.journal -include 2022.journal -include 2023.journal - - The ‘clopen:’ tag can exclude all but the first opening transaction. -To show a clean multi-year checking register: - -$ hledger -f all.journal areg checking not:tag:clopen - - And the year values allow more precision. To show 2022’s year-end -balance sheet: - -$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 - - -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS - -24.12 codes -=========== - -List the codes seen in transactions, in the order parsed. - - This command prints the value of each transaction’s code field, in -the order transactions were parsed. The transaction code is an optional -value written in parentheses between the date and description, often -used to store a cheque number, order number or similar. - - Transactions aren’t required to have a code, and missing or empty -codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they -will be printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - -2022/1/1 (123) Supermarket - Food $5.00 - Checking - -2022/1/2 (124) Post Office - Postage $8.32 - Checking - -2022/1/3 Supermarket - Food $11.23 - Checking - -2022/1/4 (126) Post Office - Postage $3.21 - Checking - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - -126 - - -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS - -24.13 commodities -================= - -List all commodity/currency symbols used or declared in the journal. - - -File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS - -24.14 descriptions -================== - -List the unique descriptions that appear in transactions. - - This command lists the unique descriptions that appear in -transactions, in alphabetic order. You can add a query to select a -subset of transactions. - - Example: - -$ hledger descriptions -Store Name -Gas Station | Petrol -Person A - - -File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS - -24.15 diff -========== - -Compares a particular account’s transactions in two input files. It -shows any transactions to this account which are in one file but not in -the other. - - More precisely, for each posting affecting this account in either -file, it looks for a corresponding posting in the other file which posts -the same amount to the same account (ignoring date, description, etc.) -Since postings not transactions are compared, this also works when -multiple bank transactions have been combined into a single journal -entry. - - This is useful eg if you have downloaded an account’s transactions -from your bank (eg as CSV data). When hledger and your bank disagree -about the account balance, you can compare the bank data with your -journal to find out the cause. - - Examples: - -$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only: - -2014/01/01 Opening Balances - assets:bank:giro EUR ... - ... - equity:opening balances EUR -... - -These transactions are in the second file only: - - -File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS - -24.16 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: PART 4 COMMANDS - -24.17 help -========== - -Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a -pager. With a TOPIC argument, open it at that topic if possible. TOPIC -can be any heading in the manual, or a heading prefix, case insensitive. -Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto -postings"’. - - This command shows the hledger manual built in to your hledger -version. It can be useful when offline, or when you prefer the terminal -to a web browser, or when the appropriate hledger manual or viewing -tools are not installed on your system. - - By default it chooses the best viewer found in $PATH (preferring info -since the hledger manual is large). You can select a particular viewer -with the ‘-i’, ‘-m’, or ‘-p’ flags. - - Examples - -$ hledger help --help # show how the help command works -$ hledger help # show the hledger manual with info, man or $PAGER -$ hledger help journal # show the journal topic in the hledger manual - - -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS - -24.18 import -============ - -Read new transactions added to each FILE since last run, and add them to -the journal. Or with –dry-run, just print the transactions that would -be added. Or with –catchup, just mark all of the FILEs’ transactions as -imported, without actually importing any. - - This command may append new transactions to the main journal file -(which should be in journal format). Existing transactions are not -changed. This is one of the few hledger commands that writes to the -journal file (see also ‘add’). - - Unlike other hledger commands, with ‘import’ the journal file is an -output file, and will be modified, though only by appending (existing -data will not be changed). The input files are specified as arguments, -so to import one or more CSV files to your main journal, you will run -‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’. - - Note you can import from any file format, though CSV files are the -most common import source, and these docs focus on that case. - -* Menu: - -* Deduplication:: -* Import testing:: -* Importing balance assignments:: -* Commodity display styles:: - - -File: hledger.info, Node: Deduplication, Next: Import testing, Up: import - -24.18.1 Deduplication ---------------------- - -As a convenience ‘import’ does _deduplication_ while reading -transactions. This does not mean "ignore transactions that look the -same", but rather "ignore transactions that have been seen before". -This is intended for when you are periodically importing foreign data -which may contain already-imported transactions. So eg, if every day -you download bank CSV files containing redundant data, you can safely -run ‘hledger import bank.csv’ and only new transactions will be -imported. (‘import’ is idempotent.) - - Since the items being read (CSV records, eg) often do not come with -unique identifiers, hledger detects new transactions by date, assuming -that: - - 1. new items always have the newest dates - 2. item dates do not change across reads - 3. and items with the same date remain in the same relative order - across reads. - - These are often true of CSV files representing transactions, or true -enough so that it works pretty well in practice. 1 is important, but -violations of 2 and 3 amongst the old transactions won’t matter (and if -you import often, the new transactions will be few, so less likely to be -the ones affected). - - hledger remembers the latest date processed in each input file by -saving a hidden ".latest" state file in the same directory. Eg when -reading ‘finance/bank.csv’, it will look for and update the -‘finance/.latest.bank.csv’ state file. The format is simple: one or -more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I -have processed transactions up to this date, and this many of them on -that date." Normally you won’t see or manipulate these state files -yourself. But if needed, you can delete them to reset the state (making -all transactions "new"), or you can construct them to "catch up" to a -certain date. - - Note deduplication (and updating of state files) can also be done by -‘print --new’, but this is less often used. - - -File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import - -24.18.2 Import testing ----------------------- - -With ‘--dry-run’, the transactions that will be imported are printed to -the terminal, without updating your journal or state files. The output -is valid journal format, like the print command, so you can re-parse it. -Eg, to see any importable transactions which CSV rules have not -categorised: - -$ hledger import --dry bank.csv | hledger -f- -I print unknown - - or (live updating): - -$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' - - Note: when importing from multiple files at once, it’s currently -possible for some .latest files to be updated successfully, while the -actual import fails because of a problem in one of the files, leaving -them out of sync (and causing some transactions to be missed). To -prevent this, do a –dry-run first and fix any problems before the real -import. - - -File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import - -24.18.3 Importing balance assignments -------------------------------------- - -Entries added by import will have their posting amounts made explicit -(like ‘hledger print -x’). This means that any balance assignments in -imported files must be evaluated; but, imported files don’t get to see -the main file’s account balances. As a result, importing entries with -balance assignments (eg from an institution that provides only balances -and not posting amounts) will probably generate incorrect posting -amounts. To avoid this problem, use print instead of import: - -$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - - (If you think import should leave amounts implicit like print does, -please test it and send a pull request.) - - -File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import - -24.18.4 Commodity display styles --------------------------------- - -Imported amounts will be formatted according to the canonical commodity -styles (declared or inferred) in the main journal file. - - -File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS - -24.19 incomestatement -===================== - -(is) - - This command displays an income statement, showing revenues and -expenses during one or more periods. Amounts are shown with normal -positive sign, as in conventional financial statements. - - This report shows accounts declared with the ‘Revenue’ or ‘Expense’ -type (see account types). Or if no such accounts are declared, it shows -top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case -insensitive, plurals allowed) and their subaccounts. - - Example: - -$ hledger incomestatement -Income Statement - -Revenues: - $-2 income - $-1 gifts - $-1 salary --------------------- - $-2 - -Expenses: - $2 expenses - $1 food - $1 supplies --------------------- - $2 - -Total: --------------------- - 0 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance '(revenues|income)' expenses’, but -with smarter account detection, and revenues/income displayed with their -sign flipped. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS - -24.20 notes -=========== - -List the unique notes that appear in transactions. - - This command lists the unique notes that appear in transactions, in -alphabetic order. You can add a query to select a subset of -transactions. The note is the part of the transaction description after -a | character (or if there is no |, the whole description). - - Example: - -$ hledger notes -Petrol -Snacks - - -File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS - -24.21 payees -============ - -List the unique payee/payer names that appear in transactions. - - This command lists unique payee/payer names which have been declared -with payee directives (–declared), used in transaction descriptions -(–used), or both (the default). - - The payee/payer is the part of the transaction description before a | -character (or if there is no |, the whole description). - - You can add query arguments to select a subset of transactions. This -implies –used. - - Example: - -$ hledger payees -Store Name -Gas Station -Person A - - -File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS - -24.22 prices -============ - -Print market price directives from the journal. With -–infer-market-prices, generate additional market prices from costs. -With –infer-reverse-prices, also generate market prices by inverting -known prices. Prices can be filtered by a query. Price amounts are -displayed with their full precision. - - -File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS - -24.23 print -=========== - -Show transaction journal entries, sorted by date. - - The print command displays full journal entries (transactions) from -the journal file, sorted by date (or with ‘--date2’, by secondary date). - - Amounts are shown mostly normalised to commodity display style, eg -the placement of commodity symbols will be consistent. All of their -decimal places are shown, as in the original journal entry (with one -alteration: in some cases trailing zeroes are added.) - - Amounts are shown right-aligned within each transaction (but not -across all transactions). - - Directives and inter-transaction comments are not shown, currently. -This means the print command is somewhat lossy, and if you are using it -to reformat your journal you should take care to also copy over the -directives and file-level comments. - - Eg: - -$ 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 - - print’s output is usually a valid hledger journal, and you can -process it again with a second hledger command. This can be useful for -certain kinds of search, eg: - -# Show running total of food expenses paid from cash. -# -f- reads from stdin. -I/--ignore-assertions is sometimes needed. -$ hledger print assets:cash | hledger -f- -I reg expenses:food - - There are some situations where print’s output can become -unparseable: - - • Valuation affects posting amounts but not balance assertion or - balance assignment amounts, potentially causing those to fail. - • Auto postings can generate postings with too many missing amounts. - • Account aliases can generate bad account names. - - Normally, the journal entry’s explicit or implicit amount style is -preserved. For example, when an amount is omitted in the journal, it -will not appear in the output. Similarly, when a cost is implied but -not written, it will not appear in the output. You can use the -‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can -be useful for troubleshooting or for making your journal more readable -and robust against data entry errors. ‘-x’ is also implied by using any -of ‘-B’,‘-V’,‘-X’,‘--value’. - - Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity -amount (these can arise when a multi-commodity transaction has an -implicit amount) to be split into multiple single-commodity postings, -keeping the output parseable. - - With ‘-B’/‘--cost’, amounts with costs are converted to cost using -that price. This can be used for troubleshooting. - - With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one -recent transaction whose description is most similar to DESC. DESC -should contain at least two characters. If there is no similar-enough -match, no transaction will be shown and the program exit code will be -non-zero. - - With ‘--new’, hledger prints only transactions it has not seen on a -previous run. This uses the same deduplication system as the ‘import’ -command. (See import’s docs for details.) - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, and -(experimental) ‘json’ and ‘sql’. - - 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: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS - -24.24 register -============== - -(reg) - - Show postings and their running total. - - The register command displays matched postings, across all accounts, -in date order, with their running total or running historical balance. -(See also the ‘aregister’ command, which shows matched transactions in a -specific account.) - - register normally shows line per posting, but note that -multi-commodity amounts will occupy multiple lines (one line per -commodity). - - It 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. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -‘--align-all’ flag. - - 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. - - The ‘--invert’ flag negates all amounts. For example, it can be used -on an income account where amounts are normally displayed as negative -numbers. It’s also useful to show postings on the checking account -together with the related account: - -$ hledger register --related --invert assets:checking - - 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. - - With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one -recent posting whose description is most similar to DESC. DESC should -contain at least two characters. If there is no similar-enough match, -no posting will be shown and the program exit code will be non-zero. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -24.24.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 the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, and -(experimental) ‘json’. - - -File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS - -24.25 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:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -24.25.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. - - -File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite - -24.25.2 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: rewrite - -24.25.3 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: PART 4 COMMANDS - -24.26 roi -========= - -Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on -your investments. - - At a minimum, you need to supply a query (which could be just an -account name) to select your investment(s) with ‘--inv’, and another -query to identify your profit and loss transactions with ‘--pnl’. - - If you do not record changes in the value of your investment -manually, or do not require computation of time-weighted return (TWR), -‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’ -does not match any of your accounts). - - This command 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. - - Price directives will be taken into account if you supply appropriate -‘--cost’ or ‘--value’ flags (see VALUATION). - - Note, in some cases this report can fail, for these reasons: - - • Error (NotBracketed): No solution for Internal Rate of Return - (IRR). Possible causes: IRR is huge (>1000000%), balance of - investment becomes negative at some point in time. - • Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or - converges too slowly. - - Examples: - - • Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger - - • Cookbook > Return on Investment: https://hledger.org/roi.html - -* Menu: - -* Spaces and special characters in --inv and --pnl:: -* Semantics of --inv and --pnl:: -* IRR and TWR explained:: - - -File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi - -24.26.1 Spaces and special characters in ‘--inv’ and ----------------------------------------------------- - -‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries -could have several space-separated terms (see QUERIES). - - To indicate that all search terms form single command-line argument, -you will need to put them in quotes (see Special characters): - -$ hledger roi --inv 'term1 term2 term3 ...' - - If any query terms contain spaces themselves, you will need an extra -level of nested quoting, eg: - -$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" - - -File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi - -24.26.2 Semantics of ‘--inv’ and ‘--pnl’ ----------------------------------------- - -Query supplied to ‘--inv’ has to match all transactions that are related -to your investment. Transactions not matching ‘--inv’ will be ignored. - - In these transactions, ROI will conside postings that match ‘--inv’ -to be "investment postings" and other postings (not matching ‘--inv’) -will be sorted into two categories: "cash flow" and "profit and loss", -as ROI needs to know which part of the investment value is your -contributions and which is due to the return on investment. - - • "Cash flow" is depositing or withdrawing money, buying or selling - assets, or otherwise converting between your investment commodity - and any other commodity. Example: - - 2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil - - 2020-01-01 Selling my Snake Oil - assets:cash $10 - investment:snake oil = 0 - - • "Profit and loss" is change in the value of your investment: - - 2019-06-01 Snake Oil falls in value - investment:snake oil = $57 - equity:unrealized profit or loss - - All non-investment postings are assumed to be "cash flow", unless -they match ‘--pnl’ query. Changes in value of your investment due to -"profit and loss" postings will be considered as part of your investment -return. - - Example: if you use ‘--inv snake --pnl equity:unrealized’, then -postings in the example below would be classifed as: - -2019-01-01 Snake Oil #1 - assets:cash -$100 ; cash flow posting - investment:snake oil ; investment posting - -2019-03-01 Snake Oil #2 - equity:unrealized pnl -$100 ; profit and loss posting - snake oil ; investment posting - -2019-07-01 Snake Oil #3 - equity:unrealized pnl ; profit and loss posting - cash -$100 ; cash flow posting - snake oil $50 ; investment posting - - -File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi - -24.26.3 IRR and TWR explained ------------------------------ - -"ROI" stands for "return on investment". Traditionally this was -computed as a difference between current value of investment and its -initial value, expressed in percentage of the initial value. - - However, this approach is only practical in simple cases, where -investments receives no in-flows or out-flows of money, and where rate -of growth is fixed over time. For more complex scenarios you need -different ways to compute rate of return, and this command implements -two of them: IRR and TWR. - - Internal rate of return, or "IRR" (also called "money-weighted rate -of return") takes into account effects of in-flows and out-flows. -Naively, if you are withdrawing from your investment, your future gains -would be smaller (in absolute numbers), and will be a smaller percentage -of your initial investment, and if you are adding to your investment, -you will receive bigger absolute gains (but probably at the same rate of -return). IRR is a way to compute rate of return for each period between -in-flow or out-flow of money, and then combine them in a way that gives -you a compound annual rate of return that investment is expected to -generate. - - As mentioned before, in-flows and out-flows would be any cash that -you personally put in or withdraw, and for the "roi" command, these are -the postings that match the query in the‘--inv’ argument and NOT match -the query in the‘--pnl’ argument. - - If you manually record changes in the value of your investment as -transactions that balance them against "profit and loss" (or "unrealized -gains") account or use price directives, then in order for IRR to -compute the precise effect of your in-flows and out-flows on the rate of -return, you will need to record the value of your investement on or -close to the days when in- or out-flows occur. - - In technical terms, IRR uses the same approach as computation of net -present value, and tries to find a discount rate that makes net present -value of all the cash flows of your investment to add up to zero. This -could be hard to wrap your head around, especially if you haven’t done -discounted cash flow analysis before. Implementation of IRR in hledger -should produce results that match the ‘XIRR’ formula in Excel. - - Second way to compute rate of return that ‘roi’ command implements is -called "time-weighted rate of return" or "TWR". Like IRR, it will also -break the history of your investment into periods between in-flows, -out-flows and value changes, to compute rate of return per each period -and then a compound rate of return. However, internal workings of TWR -are quite different. - - TWR represents your investment as an imaginary "unit fund" where -in-flows/ out-flows lead to buying or selling "units" of your investment -and changes in its value change the value of "investment unit". Change -in "unit price" over the reporting period gives you rate of return of -your investment. - - References: - - • Explanation of rate of return - • Explanation of IRR - • Explanation of TWR - • Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS - -24.27 stats -=========== - -Show journal and performance 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. - - At the end, it shows (in the terminal) the overall run time and -number of transactions processed per second. Note these are approximate -and will vary based on machine, current load, data size, hledger -version, haskell lib versions, GHC version.. but they may be of -interest. The ‘stats’ command’s run time is similar to that of a -single-column balance report. - - Example: - -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s - - This command supports the -o/–output-file option (but not --O/–output-format selection). - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS - -24.28 tags -========== - -List the tags used in the journal, or their values. - - This command lists the tag names used in the journal, whether on -transactions, postings, or account declarations. - - With a TAGREGEX argument, only tag names matching this regular -expression (case insensitive, infix matched) are shown. - - With QUERY arguments, only transactions and accounts matching this -query are considered. If the query involves transaction fields (date:, -desc:, amt:, ...), the search is restricted to the matched transactions -and their accounts. - - With the –values flag, the tags’ unique non-empty values are listed -instead. With -E/–empty, blank/empty values are also shown. - - With –parsed, tags or values are shown in the order they were parsed, -with duplicates included. (Except, tags from account declarations are -always shown first.) - - Tip: remember, accounts also acquire tags from their parents, -postings also acquire tags from their account and transaction, -transactions also acquire tags from their postings. - - -File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS - -24.29 test -========== - -Run built-in unit tests. - - This command runs the unit tests built in to hledger and hledger-lib, -printing the results on stdout. If any test fails, the exit code will -be non-zero. - - This is mainly used by hledger developers, but you can also use it to -sanity-check the installed hledger executable on your platform. All -tests are expected to pass - if you ever see a failure, please report as -a bug! - - This command also accepts tasty test runner options, written after a -– (double hyphen). Eg to run only the tests in Hledger.Data.Amount, -with ANSI colour codes disabled: - -$ hledger test -- -pData.Amount --color=never - - For help on these, see https://github.com/feuerbach/tasty#options -(‘-- --help’ currently doesn’t show them). - - -File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top - -25 PART 5: COMMON TASKS -*********************** - -Here are some quick examples of how to do some basic tasks with hledger. - -* Menu: - -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: - - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS - -25.1 Getting help -================= - -Here’s how to list commands and view options and command docs: - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version’s manual in several formats by -using the help command. Eg: - -$ hledger help # show the hledger manual with info, man or $PAGER (best available) -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit -https://hledger.org. Chat and mail list support and discussion archives -can be found at https://hledger.org/support. - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS - -25.2 Constructing command lines -=============================== - -hledger has a flexible command line interface. We strive to keep it -simple and ergonomic, but if you run into one of the sharp edges -described in OPTIONS, here are some tips that might help: - - • command-specific options must go after the command (it’s fine to - put common options there too: ‘hledger CMD OPTS ARGS’) - • running add-on executables directly simplifies command line parsing - (‘hledger-ui OPTS ARGS’) - • enclose "problematic" args in single quotes - • if needed, also add a backslash to hide regular expression - metacharacters from the shell - • to see how a misbehaving command line is being parsed, add - ‘--debug=2’. - - -File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS - -25.3 Starting a journal file -============================ - -hledger looks for your accounting data in a journal file, -‘$HOME/.hledger.journal’ by default: - -$ hledger stats -The hledger journal file "/Users/simon/.hledger.journal" was not found. -Please create it first, eg with "hledger add" or a text editor. -Or, specify an existing journal file with -f or LEDGER_FILE. - - You can override this by setting the ‘LEDGER_FILE’ environment -variable. It’s a good practice to keep this important file under -version control, and to start a new file each year. So you could do -something like this: - -$ mkdir ~/finance -$ cd ~/finance -$ git init -Initialized empty Git repository in /Users/simon/finance/.git/ -$ touch 2020.journal -$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc -$ source ~/.bashrc -$ hledger stats -Main file : /Users/simon/finance/2020.journal -Included files : -Transactions span : to (0 days) -Last transaction : none -Transactions : 0 (0.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 0 -Accounts : 0 (depth 0) -Commodities : 0 () -Market prices : 0 () - - -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS - -25.4 Setting opening balances -============================= - -Pick a starting date for which you can look up the balances of some -real-world assets (bank accounts, wallet..) and liabilities (credit -cards..). - - To avoid a lot of data entry, you may want to start with just one or -two accounts, like your checking account or cash wallet; and pick a -recent starting date, like today or the start of the week. You can -always come back later and add more accounts and older transactions, eg -going back to january 1st. - - Add an opening balances transaction to the journal, declaring the -balances on this date. Here are two ways to do it: - - • The first way: open the journal in any text editor and save an - entry like this: - - 2020-01-01 * opening balances - assets:bank:checking $1000 = $1000 - assets:bank:savings $2000 = $2000 - assets:cash $100 = $100 - liabilities:creditcard $-50 = $-50 - equity:opening/closing balances - - These are start-of-day balances, ie whatever was in the account at - the end of the previous day. - - The * after the date is an optional status flag. Here it means - "cleared & confirmed". - - The currency symbols are optional, but usually a good idea as - you’ll be dealing with multiple currencies sooner or later. - - The = amounts are optional balance assertions, providing extra - error checking. - - • The second way: run ‘hledger add’ and follow the prompts to record - a similar transaction: - - $ hledger add - Adding transactions to journal file /Users/simon/finance/2020.journal - 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 go one step backward. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2020-02-07]: 2020-01-01 - Description: * opening balances - Account 1: assets:bank:checking - Amount 1: $1000 - Account 2: assets:bank:savings - Amount 2 [$-1000]: $2000 - Account 3: assets:cash - Amount 3 [$-3000]: $100 - Account 4: liabilities:creditcard - Amount 4 [$-3100]: $-50 - Account 5: equity:opening/closing balances - Amount 5 [$-3050]: - Account 6 (or . or enter to finish this transaction): . - 2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2020-01-01]: . - - If you’re using version control, this could be a good time to commit -the journal. Eg: - -$ git commit -m 'initial balances' 2020.journal - - -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS - -25.5 Recording transactions -=========================== - -As you spend or receive money, you can record these transactions using -one of the methods above (text editor, hledger add) or by using the -hledger-iadd or hledger-web add-ons, or by using the import command to -convert CSV data downloaded from your bank. - - Here are some simple transactions, see the hledger_journal(5) manual -and hledger.org for more ideas: - -2020/1/10 * gift received - assets:cash $20 - income:gifts - -2020.1.12 * farmers market - expenses:food $13 - assets:cash - -2020-01-15 paycheck - income:salary - assets:bank:checking $1000 - - -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS - -25.6 Reconciling -================ - -Periodically you should reconcile - compare your hledger-reported -balances against external sources of truth, like bank statements or your -bank’s website - to be sure that your ledger accurately represents the -real-world balances (and, that the real-world institutions have not made -a mistake!). This gets easy and fast with (1) practice and (2) -frequency. If you do it daily, it can take 2-10 minutes. If you let it -pile up, expect it to take longer as you hunt down errors and -discrepancies. - - A typical workflow: - - 1. Reconcile cash. Count what’s in your wallet. Compare with what - hledger reports (‘hledger bal cash’). If they are different, try - to remember the missing transaction, or look for the error in the - already-recorded transactions. A register report can be helpful - (‘hledger reg cash’). If you can’t find the error, add an - adjustment transaction. Eg if you have $105 after the above, and - can’t explain the missing $2, it could be: - - 2020-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - 2. Reconcile checking. Log in to your bank’s website. Compare - today’s (cleared) balance with hledger’s cleared balance (‘hledger - bal checking -C’). If they are different, track down the error or - record the missing transaction(s) or add an adjustment transaction, - similar to the above. Unlike the cash case, you can usually - compare the transaction history and running balance from your bank - with the one reported by ‘hledger reg checking -C’. This will be - easier if you generally record transaction dates quite similar to - your bank’s clearing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a -live-updating register while you edit the journal: ‘hledger-ui --watch ---register checking -C’ - - After reconciling, it could be a good time to mark the reconciled -transactions’ status as "cleared and confirmed", if you want to track -that, by adding the ‘*’ marker. Eg in the paycheck transaction above, -insert ‘*’ between ‘2020-01-15’ and ‘paycheck’ - - If you’re using version control, this can be another good time to -commit: - -$ git commit -m 'txns' 2020.journal - - -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS - -25.7 Reporting -============== - -Here are some basic reports. - - Show all transactions: - -$ hledger print -2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -2020-01-10 * gift received - assets:cash $20 - income:gifts - -2020-01-12 * farmers market - expenses:food $13 - assets:cash - -2020-01-15 * paycheck - income:salary - assets:bank:checking $1000 - -2020-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - -$ hledger accounts --tree -assets - bank - checking - savings - cash -equity - opening/closing balances -expenses - food - misc -income - gifts - salary -liabilities - creditcard - - Show all account totals: - -$ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard --------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to -depth 2: - -$ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard --------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple -balance sheet: - -$ hledger bs -2 -Balance Sheet 2020-01-16 - - || 2020-01-16 -========================++============ - Assets || -------------------------++------------ - assets:bank || $4000 - assets:cash || $105 -------------------------++------------ - || $4105 -========================++============ - Liabilities || -------------------------++------------ - liabilities:creditcard || $50 -------------------------++------------ - || $50 -========================++============ - Net: || $4055 - - The final total is your "net worth" on the end date. (Or use ‘bse’ -for a full balance sheet with equity.) - - Show income and expense totals, formatted as an income statement: - -hledger is -Income Statement 2020-01-01-2020-01-16 - - || 2020-01-01-2020-01-16 -===============++======================= - Revenues || ----------------++----------------------- - income:gifts || $20 - income:salary || $1000 ----------------++----------------------- - || $1020 -===============++======================= - Expenses || ----------------++----------------------- - expenses:food || $13 - expenses:misc || $2 ----------------++----------------------- - || $15 -===============++======================= - Net: || $1005 - - The final total is your net income during this period. - - Show transactions affecting your wallet, with running total: - -$ hledger register cash -2020-01-01 opening balances assets:cash $100 $100 -2020-01-10 gift received assets:cash $20 $120 -2020-01-12 farmers market assets:cash $-13 $107 -2020-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - -$ hledger activity -W -2019-12-30 ***** -2020-01-06 **** -2020-01-13 **** - - -File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS - -25.8 Migrating to a new file -============================ - -At the end of the year, you may want to continue your journal in a new -file, so that old transactions don’t slow down or clutter your reports, -and to help ensure the integrity of your accounting history. See the -close command. - - If using version control, don’t forget to ‘git add’ the new file. - - -Tag Table: -Node: Top210 -Node: PART 1 USER INTERFACE3944 -Ref: #part-1-user-interface4085 -Node: Options4085 -Ref: #options4204 -Node: General options4346 -Ref: #general-options4471 -Node: Command options8921 -Ref: #command-options9072 -Node: Command arguments9488 -Ref: #command-arguments9646 -Node: Special characters10548 -Ref: #special-characters10711 -Node: Single escaping shell metacharacters10874 -Ref: #single-escaping-shell-metacharacters11115 -Node: Double escaping regular expression metacharacters11750 -Ref: #double-escaping-regular-expression-metacharacters12061 -Node: Triple escaping for add-on commands12631 -Ref: #triple-escaping-for-add-on-commands12891 -Node: Less escaping13559 -Ref: #less-escaping13713 -Node: Unicode characters14051 -Ref: #unicode-characters14216 -Node: Regular expressions15648 -Ref: #regular-expressions15788 -Node: Environment17642 -Ref: #environment17753 -Node: Input19364 -Ref: #input19464 -Node: Data formats20027 -Ref: #data-formats20140 -Node: Multiple files21592 -Ref: #multiple-files21729 -Node: Strict mode22214 -Ref: #strict-mode22324 -Node: Commands23078 -Ref: #commands23179 -Node: Add-on commands23663 -Ref: #add-on-commands23765 -Node: Output24932 -Ref: #output25035 -Node: Output destination25151 -Ref: #output-destination25282 -Node: Output format25711 -Ref: #output-format25857 -Node: CSV output27429 -Ref: #csv-output27545 -Node: HTML output27650 -Ref: #html-output27788 -Node: JSON output27888 -Ref: #json-output28026 -Node: SQL output28958 -Ref: #sql-output29074 -Node: Commodity styles29597 -Ref: #commodity-styles29737 -Node: Colour30344 -Ref: #colour30462 -Node: Box-drawing30896 -Ref: #box-drawing31020 -Node: Debug output31334 -Ref: #debug-output31445 -Node: Limitations32120 -Ref: #limitations32240 -Node: Troubleshooting33015 -Ref: #troubleshooting33156 -Node: PART 2 DATA FORMATS35678 -Ref: #part-2-data-formats35825 -Node: Journal35825 -Ref: #journal35936 -Node: Journal cheatsheet36579 -Ref: #journal-cheatsheet36720 -Node: About journal format40708 -Ref: #about-journal-format40870 -Node: Comments42408 -Ref: #comments42540 -Node: Transactions43394 -Ref: #transactions43519 -Node: Dates44553 -Ref: #dates44662 -Node: Simple dates44707 -Ref: #simple-dates44825 -Node: Posting dates45357 -Ref: #posting-dates45477 -Node: Status46460 -Ref: #status46563 -Node: Code48315 -Ref: #code48420 -Node: Description48652 -Ref: #description48785 -Node: Payee and note49107 -Ref: #payee-and-note49215 -Node: Transaction comments49562 -Ref: #transaction-comments49717 -Node: Postings50088 -Ref: #postings50223 -Node: Account names51232 -Ref: #account-names51364 -Node: Amounts53066 -Ref: #amounts53183 -Node: Decimal marks digit group marks54172 -Ref: #decimal-marks-digit-group-marks54349 -Node: Commodity55373 -Ref: #commodity55562 -Node: Directives influencing number parsing and display56544 -Ref: #directives-influencing-number-parsing-and-display56805 -Node: Commodity display style57267 -Ref: #commodity-display-style57475 -Node: Rounding59686 -Ref: #rounding59806 -Node: Costs60107 -Ref: #costs60225 -Node: Other cost/lot notations62256 -Ref: #other-costlot-notations62390 -Node: Balance assertions65143 -Ref: #balance-assertions65296 -Node: Assertions and ordering66389 -Ref: #assertions-and-ordering66580 -Node: Assertions and multiple included files67282 -Ref: #assertions-and-multiple-included-files67544 -Node: Assertions and multiple -f files68052 -Ref: #assertions-and-multiple--f-files68305 -Node: Assertions and commodities68714 -Ref: #assertions-and-commodities68938 -Node: Assertions and prices70128 -Ref: #assertions-and-prices70336 -Node: Assertions and subaccounts70767 -Ref: #assertions-and-subaccounts70990 -Node: Assertions and virtual postings71332 -Ref: #assertions-and-virtual-postings71572 -Node: Assertions and auto postings71712 -Ref: #assertions-and-auto-postings71944 -Node: Assertions and precision72615 -Ref: #assertions-and-precision72799 -Node: Posting comments73066 -Ref: #posting-comments73214 -Node: Tags73599 -Ref: #tags73715 -Node: Tag values74920 -Ref: #tag-values75011 -Node: Directives75784 -Ref: #directives75913 -Node: Directive effects77781 -Ref: #directive-effects77937 -Node: Directives and multiple files81020 -Ref: #directives-and-multiple-files81200 -Node: account directive81910 -Ref: #account-directive82072 -Node: Account comments83492 -Ref: #account-comments83644 -Node: Account subdirectives84164 -Ref: #account-subdirectives84357 -Node: Account error checking84499 -Ref: #account-error-checking84699 -Node: Account display order85918 -Ref: #account-display-order86108 -Node: Account types87247 -Ref: #account-types87390 -Node: alias directive91125 -Ref: #alias-directive91292 -Node: Basic aliases92352 -Ref: #basic-aliases92485 -Node: Regex aliases93239 -Ref: #regex-aliases93398 -Node: Combining aliases94292 -Ref: #combining-aliases94472 -Node: Aliases and multiple files95766 -Ref: #aliases-and-multiple-files95972 -Node: end aliases directive96557 -Ref: #end-aliases-directive96782 -Node: Aliases can generate bad account names96931 -Ref: #aliases-can-generate-bad-account-names97181 -Node: Aliases and account types97778 -Ref: #aliases-and-account-types97972 -Node: commodity directive98674 -Ref: #commodity-directive98854 -Node: Commodity error checking101458 -Ref: #commodity-error-checking101606 -Node: decimal-mark directive102135 -Ref: #decimal-mark-directive102323 -Node: include directive102724 -Ref: #include-directive102894 -Node: P directive103842 -Ref: #p-directive103993 -Node: payee directive104892 -Ref: #payee-directive105047 -Node: tag directive105367 -Ref: #tag-directive105528 -Node: Periodic transactions106000 -Ref: #periodic-transactions106166 -Node: Periodic rule syntax107904 -Ref: #periodic-rule-syntax108084 -Node: Periodic rules and relative dates108739 -Ref: #periodic-rules-and-relative-dates109007 -Node: Two spaces between period expression and description!109546 -Ref: #two-spaces-between-period-expression-and-description109825 -Node: Other syntax110515 -Ref: #other-syntax110641 -Node: Auto postings111286 -Ref: #auto-postings111422 -Node: Auto postings and multiple files113933 -Ref: #auto-postings-and-multiple-files114135 -Node: Auto postings and dates114352 -Ref: #auto-postings-and-dates114624 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions114799 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115138 -Node: Auto posting tags115645 -Ref: #auto-posting-tags115858 -Node: Balance assignments116520 -Ref: #balance-assignments116700 -Node: Balance assignments and prices118034 -Ref: #balance-assignments-and-prices118204 -Node: Bracketed posting dates118415 -Ref: #bracketed-posting-dates118601 -Node: D directive119145 -Ref: #d-directive119319 -Node: apply account directive120987 -Ref: #apply-account-directive121173 -Node: Y directive121872 -Ref: #y-directive122038 -Node: Secondary dates122882 -Ref: #secondary-dates123038 -Node: Star comments123870 -Ref: #star-comments124032 -Node: Valuation expressions124572 -Ref: #valuation-expressions124751 -Node: Virtual postings124873 -Ref: #virtual-postings125054 -Node: Other Ledger directives126626 -Ref: #other-ledger-directives126791 -Node: CSV127361 -Ref: #csv127454 -Node: CSV rules cheatsheet129557 -Ref: #csv-rules-cheatsheet129689 -Node: separator131457 -Ref: #separator131588 -Node: skip132166 -Ref: #skip132278 -Node: date-format132861 -Ref: #date-format132986 -Node: timezone133732 -Ref: #timezone133859 -Node: newest-first134892 -Ref: #newest-first135034 -Node: intra-day-reversed135618 -Ref: #intra-day-reversed135776 -Node: decimal-mark136273 -Ref: #decimal-mark136418 -Node: fields list136757 -Ref: #fields-list136898 -Node: Field assignment138621 -Ref: #field-assignment138765 -Node: Field names139814 -Ref: #field-names139945 -Node: date field141166 -Ref: #date-field141284 -Node: date2 field141336 -Ref: #date2-field141477 -Node: status field141539 -Ref: #status-field141682 -Node: code field141737 -Ref: #code-field141882 -Node: description field141933 -Ref: #description-field142093 -Node: comment field142158 -Ref: #comment-field142313 -Node: account field142626 -Ref: #account-field142776 -Node: amount field143372 -Ref: #amount-field143521 -Node: currency field145626 -Ref: #currency-field145779 -Node: balance field146048 -Ref: #balance-field146180 -Node: if block146568 -Ref: #if-block146693 -Node: Matchers148117 -Ref: #matchers148231 -Node: if table149761 -Ref: #if-table149887 -Node: balance-type151323 -Ref: #balance-type151456 -Node: include152164 -Ref: #include152295 -Node: Working with CSV152745 -Ref: #working-with-csv152892 -Node: Rapid feedback153263 -Ref: #rapid-feedback153396 -Node: Valid CSV153852 -Ref: #valid-csv153998 -Node: File Extension154752 -Ref: #file-extension154925 -Node: Reading CSV from standard input155515 -Ref: #reading-csv-from-standard-input155739 -Node: Reading multiple CSV files155905 -Ref: #reading-multiple-csv-files156123 -Node: Valid transactions156372 -Ref: #valid-transactions156566 -Node: Deduplicating importing157194 -Ref: #deduplicating-importing157389 -Node: Setting amounts158435 -Ref: #setting-amounts158606 -Node: Amount signs161129 -Ref: #amount-signs161297 -Node: Setting currency/commodity162036 -Ref: #setting-currencycommodity162240 -Node: Amount decimal places163432 -Ref: #amount-decimal-places163638 -Node: Referencing other fields163956 -Ref: #referencing-other-fields164169 -Node: How CSV rules are evaluated165072 -Ref: #how-csv-rules-are-evaluated165289 -Node: Well factored rules166802 -Ref: #well-factored-rules166970 -Node: CSV rules examples167308 -Ref: #csv-rules-examples167443 -Node: Bank of Ireland167508 -Ref: #bank-of-ireland167645 -Node: Coinbase169113 -Ref: #coinbase169251 -Node: Amazon170304 -Ref: #amazon170429 -Node: Paypal172154 -Ref: #paypal172262 -Node: Timeclock179908 -Ref: #timeclock180013 -Node: Timedot182181 -Ref: #timedot182304 -Node: PART 3 REPORTING CONCEPTS187155 -Ref: #part-3-reporting-concepts187319 -Node: Time periods187319 -Ref: #time-periods187453 -Node: Report start & end date187571 -Ref: #report-start-end-date187723 -Node: Smart dates189456 -Ref: #smart-dates189609 -Node: Report intervals191569 -Ref: #report-intervals191724 -Node: Date adjustment192176 -Ref: #date-adjustment192336 -Node: Period expressions193668 -Ref: #period-expressions193809 -Node: Period expressions with a report interval195645 -Ref: #period-expressions-with-a-report-interval195879 -Node: More complex report intervals196109 -Ref: #more-complex-report-intervals196354 -Node: Multiple weekday intervals198283 -Ref: #multiple-weekday-intervals198472 -Node: Depth199336 -Ref: #depth199438 -Node: Queries199758 -Ref: #queries199860 -Node: Query types200805 -Ref: #query-types200926 -Node: Combining query terms204266 -Ref: #combining-query-terms204443 -Node: Queries and command options205541 -Ref: #queries-and-command-options205740 -Node: Queries and valuation206005 -Ref: #queries-and-valuation206200 -Node: Querying with account aliases206439 -Ref: #querying-with-account-aliases206650 -Node: Querying with cost or value206792 -Ref: #querying-with-cost-or-value206969 -Node: Pivoting207278 -Ref: #pivoting207392 -Node: Generating data208880 -Ref: #generating-data209012 -Node: Forecasting209510 -Ref: #forecasting209635 -Node: Budgeting212522 -Ref: #budgeting212642 -Node: Cost reporting212913 -Ref: #cost-reporting213041 -Node: -B Convert to cost214156 -Ref: #b-convert-to-cost214312 -Node: Equity conversion postings215720 -Ref: #equity-conversion-postings215934 -Node: Inferring equity postings from cost216829 -Ref: #inferring-equity-postings-from-cost217078 -Node: Inferring cost from equity postings217897 -Ref: #inferring-cost-from-equity-postings218145 -Node: When to infer cost/equity219954 -Ref: #when-to-infer-costequity220172 -Node: How to record conversions220580 -Ref: #how-to-record-conversions220772 -Node: Conversion with implicit cost221063 -Ref: #conversion-with-implicit-cost221268 -Node: Conversion with explicit cost222173 -Ref: #conversion-with-explicit-cost222418 -Node: Conversion with equity postings222845 -Ref: #conversion-with-equity-postings223114 -Node: Conversion with equity postings and explicit cost223951 -Ref: #conversion-with-equity-postings-and-explicit-cost224218 -Node: Cost tips224692 -Ref: #cost-tips224818 -Node: Valuation225554 -Ref: #valuation225678 -Node: -V Value226464 -Ref: #v-value226590 -Node: -X Value in specified commodity226789 -Ref: #x-value-in-specified-commodity226984 -Node: Valuation date227141 -Ref: #valuation-date227312 -Node: Finding market price227751 -Ref: #finding-market-price227956 -Node: --infer-market-prices market prices from transactions229136 -Ref: #infer-market-prices-market-prices-from-transactions229414 -Node: Valuation commodity232260 -Ref: #valuation-commodity232473 -Node: Simple valuation examples233718 -Ref: #simple-valuation-examples233916 -Node: --value Flexible valuation234579 -Ref: #value-flexible-valuation234785 -Node: More valuation examples236471 -Ref: #more-valuation-examples236680 -Node: Interaction of valuation and queries238691 -Ref: #interaction-of-valuation-and-queries238932 -Node: Effect of valuation on reports239412 -Ref: #effect-of-valuation-on-reports239609 -Node: PART 4 COMMANDS247368 -Ref: #part-4-commands247511 -Node: Commands overview247881 -Ref: #commands-overview248015 -Node: DATA ENTRY248194 -Ref: #data-entry248318 -Node: DATA CREATION248521 -Ref: #data-creation248675 -Node: DATA MANAGEMENT248799 -Ref: #data-management248964 -Node: REPORTS FINANCIAL249089 -Ref: #reports-financial249264 -Node: REPORTS VERSATILE249579 -Ref: #reports-versatile249752 -Node: REPORTS BASIC250013 -Ref: #reports-basic250165 -Node: HELP250698 -Ref: #help250820 -Node: ADD-ONS250879 -Ref: #add-ons250985 -Node: accounts251582 -Ref: #accounts251715 -Node: activity253690 -Ref: #activity253809 -Node: add254183 -Ref: #add254293 -Node: aregister257154 -Ref: #aregister257275 -Node: aregister and custom posting dates260251 -Ref: #aregister-and-custom-posting-dates260417 -Node: balance260985 -Ref: #balance261111 -Node: balance features262116 -Ref: #balance-features262256 -Node: Simple balance report264386 -Ref: #simple-balance-report264571 -Node: Balance report line format266216 -Ref: #balance-report-line-format266418 -Node: Filtered balance report268668 -Ref: #filtered-balance-report268860 -Node: List or tree mode269187 -Ref: #list-or-tree-mode269355 -Node: Depth limiting270730 -Ref: #depth-limiting270896 -Node: Dropping top-level accounts271513 -Ref: #dropping-top-level-accounts271713 -Node: Showing declared accounts272027 -Ref: #showing-declared-accounts272226 -Node: Sorting by amount272767 -Ref: #sorting-by-amount272934 -Node: Percentages273624 -Ref: #percentages273783 -Node: Multi-period balance report274353 -Ref: #multi-period-balance-report274553 -Node: Balance change end balance276946 -Ref: #balance-change-end-balance277155 -Node: Balance report types278603 -Ref: #balance-report-types278784 -Node: Calculation type279300 -Ref: #calculation-type279455 -Node: Accumulation type279986 -Ref: #accumulation-type280166 -Node: Valuation type281094 -Ref: #valuation-type281282 -Node: Combining balance report types282349 -Ref: #combining-balance-report-types282543 -Node: Budget report284447 -Ref: #budget-report284599 -Node: Budget report start date290333 -Ref: #budget-report-start-date290511 -Node: Budgets and subaccounts291873 -Ref: #budgets-and-subaccounts292080 -Node: Selecting budget goals295566 -Ref: #selecting-budget-goals295765 -Node: Budget vs forecast296812 -Ref: #budget-vs-forecast296971 -Node: Data layout298671 -Ref: #data-layout298821 -Node: Useful balance reports306762 -Ref: #useful-balance-reports306912 -Node: balancesheet308065 -Ref: #balancesheet308210 -Node: balancesheetequity309576 -Ref: #balancesheetequity309734 -Node: cashflow311177 -Ref: #cashflow311308 -Node: check312794 -Ref: #check312908 -Node: Basic checks313714 -Ref: #basic-checks313834 -Node: Strict checks314372 -Ref: #strict-checks314515 -Node: Other checks314956 -Ref: #other-checks315098 -Node: Custom checks315675 -Ref: #custom-checks315832 -Node: More about specific checks316253 -Ref: #more-about-specific-checks316415 -Node: close317147 -Ref: #close317258 -Node: close and costs319896 -Ref: #close-and-costs320040 -Node: close and balance assertions320329 -Ref: #close-and-balance-assertions320531 -Node: Example retain earnings321702 -Ref: #example-retain-earnings321919 -Node: Example migrate balances to a new file322277 -Ref: #example-migrate-balances-to-a-new-file322542 -Node: Example excluding closing/opening transactions323095 -Ref: #example-excluding-closingopening-transactions323344 -Node: codes324522 -Ref: #codes324639 -Node: commodities325515 -Ref: #commodities325651 -Node: descriptions325721 -Ref: #descriptions325858 -Node: diff326149 -Ref: #diff326264 -Node: files327310 -Ref: #files327419 -Node: help327560 -Ref: #help-1327669 -Node: import328659 -Ref: #import328782 -Node: Deduplication329890 -Ref: #deduplication330015 -Node: Import testing331937 -Ref: #import-testing332102 -Node: Importing balance assignments332953 -Ref: #importing-balance-assignments333159 -Node: Commodity display styles333816 -Ref: #commodity-display-styles333989 -Node: incomestatement334118 -Ref: #incomestatement334260 -Node: notes335627 -Ref: #notes335749 -Node: payees336111 -Ref: #payees336226 -Node: prices336751 -Ref: #prices336866 -Node: print337168 -Ref: #print337283 -Node: register342729 -Ref: #register342851 -Node: Custom register output347960 -Ref: #custom-register-output348091 -Node: rewrite349466 -Ref: #rewrite349584 -Node: Re-write rules in a file351496 -Ref: #re-write-rules-in-a-file351659 -Node: Diff output format352812 -Ref: #diff-output-format352995 -Node: rewrite vs print --auto354107 -Ref: #rewrite-vs.-print---auto354269 -Node: roi354843 -Ref: #roi354950 -Node: Spaces and special characters in --inv and --pnl356711 -Ref: #spaces-and-special-characters-in---inv-and---pnl356959 -Node: Semantics of --inv and --pnl357457 -Ref: #semantics-of---inv-and---pnl357704 -Node: IRR and TWR explained359582 -Ref: #irr-and-twr-explained359742 -Node: stats362854 -Ref: #stats362962 -Node: tags364359 -Ref: #tags-1364466 -Node: test365483 -Ref: #test365576 -Node: PART 5 COMMON TASKS366326 -Ref: #part-5-common-tasks366459 -Node: Getting help366733 -Ref: #getting-help366874 -Node: Constructing command lines367638 -Ref: #constructing-command-lines367839 -Node: Starting a journal file368520 -Ref: #starting-a-journal-file368727 -Node: Setting opening balances369925 -Ref: #setting-opening-balances370130 -Node: Recording transactions373283 -Ref: #recording-transactions373472 -Node: Reconciling374028 -Ref: #reconciling374180 -Node: Reporting376493 -Ref: #reporting376642 -Node: Migrating to a new file380631 -Ref: #migrating-to-a-new-file380788 + This manual is for hledger’s command line interface, version 1.29.1. +It also describes the common options, file formats and concepts used by +all hledger programs. It might accidentally teach you some +bookkeeping/accounting as well! You don’t need to know everything in +here to use hledger productively, but when you have a question about +functionality, this doc should answer it. It is detailed, so do skip +ahead or skim when needed. You can read it on hledger.org, or as an +info manual or man page on your system. You can also get it from +hledger itself with +‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’. + + The main function of the hledger CLI is to read plain text files +describing financial transactions, crunch the numbers, and print a +useful report on the terminal (or save it as HTML, CSV, JSON or SQL). +Many reports are available, as subcommands. hledger will also detect +other ‘hledger-*’ executables as extra subcommands. + + hledger reads data from one or more files in journal, timeclock, +timedot, or CSV format. The default file is ‘.hledger.journal’ in your +home directory; this can be overridden with one or more ‘-f FILE’ +options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can +also read from stdin with ‘-f-’; more on that below. + + Here is a small but valid hledger journal file describing one +transaction: + +2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more +_accounts_: bank accounts, your wallet, revenue/expense categories, +people, etc. You can choose any account names you wish, using ‘:’ to +indicate subaccounts. There must be at least two spaces between account +name and amount. Positive amounts are inflow to that account (_debit_), +negatives are outflow from it (_credit_). (Some reports show revenue, +liability and equity account balances as negative numbers as a result; +this is normal.) + + hledger’s add command can help you add transactions, or you can +install other data entry UIs like hledger-web or hledger-iadd. For more +extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM ++ vim-ledger, or VS Code + hledger-vscode are some good choices (see +https://hledger.org/editors.html). + + To get started, run ‘hledger add’ and follow the prompts, or save +some entries like the above in ‘$HOME/.hledger.journal’, then try +commands like: +‘hledger print -x’ +‘hledger aregister assets’ +‘hledger balance’ +‘hledger balancesheet’ +‘hledger incomestatement’. +Run ‘hledger’ to list the commands. See also the "Starting a journal +file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +* Menu: + +* PART 1 USER INTERFACE:: +* Options:: +* Environment:: +* Input:: +* Commands:: +* Output:: +* Limitations:: +* Troubleshooting:: +* PART 2 DATA FORMATS:: +* Journal:: +* CSV:: +* Timeclock:: +* Timedot:: +* PART 3 REPORTING CONCEPTS:: +* Time periods:: +* Depth:: +* Queries:: +* Pivoting:: +* Generating data:: +* Forecasting:: +* Budgeting:: +* Cost reporting:: +* Valuation:: +* PART 4 COMMANDS:: +* PART 5 COMMON TASKS:: + + +File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top + +1 PART 1: USER INTERFACE +************************ + + +File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top + +2 Options +********* + +* Menu: + +* General options:: +* Command options:: +* Command arguments:: +* Special characters:: +* Unicode characters:: +* 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 or COMMAND help +‘--man’ + + show general or COMMAND user manual with man +‘--info’ + + show general or COMMAND user manual with info +‘--version’ + + show general or ADDONCMD version +‘--debug[=N]’ + + show debug output (levels 1-9, default: 1) + + General input options: + +‘-f FILE --file=FILE’ + + use a different input file. For stdin, use - (default: + ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’) +‘--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’ + + disable balance assertion checks (note: does not disable balance + assignments) +‘-s --strict’ + + do extra error checking (check that all posted accounts are + declared) + + General reporting options: + +‘-b --begin=DATE’ + + include postings/txns on or after this date (will be adjusted to + preceding subperiod start when using a report interval) +‘-e --end=DATE’ + + include postings/txns before this date (will be adjusted to + following subperiod end when using a report interval) +‘-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 +‘--date2’ + + match the secondary date instead (see command help for other + effects) +‘--today=DATE’ + + override today’s date (affects relative smart dates, for + tests/examples) +‘-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/selling amount at transaction time +‘-V --market’ + + convert amounts to their market value in default valuation + commodities +‘-X --exchange=COMM’ + + convert amounts to their market value in commodity COMM +‘--value’ + + convert amounts to cost or market value, more flexibly than + -B/-V/-X +‘--infer-market-prices’ + + use transaction prices (recorded with @ or @@) as additional market + prices, as if they were P directives +‘--auto’ + + apply automated posting rules to modify transactions. +‘--forecast’ + + generate future transactions from periodic transaction rules, for + the next 6 months or till report end date. In hledger-ui, also + make ordinary future transactions visible. +‘--commodity-style’ + + Override the commodity style in the output for the specified + commodity. For example ’EUR1.000,00’. +‘--color=WHEN (or --colour=WHEN)’ + + Should color-supporting commands use ANSI color codes in text + output. ’auto’ (default): whenever stdout seems to be a + color-supporting terminal. ’always’ or ’yes’: always, useful eg + when piping output into ’less -R’. ’never’ or ’no’: never. A + NO_COLOR environment variable overrides this. +‘--pretty[=WHEN]’ + + Show prettier output, e.g. using unicode box-drawing characters. + Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’ + also work). If you provide an argument you must use ’=’, e.g. + ’–pretty=yes’. + + When a reporting option appears more than once in the command line, +the 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 add-on, you may need to put its +options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can +run the add-on executable directly: ‘hledger-ui --watch’. + + +File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options + +2.3 Command arguments +===================== + +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. + + You can save a set of command line options/arguments in a file, and +then reuse them by writing ‘@FILENAME’ as a command line argument. Eg: +‘hledger bal @foo.args’. (To prevent this, eg if you have an argument +that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal +-- @ARG’). + + Inside the argument file, each line should contain just one option or +argument. Avoid the use of spaces, except inside quotes (or you’ll see +a confusing error). Between a flag and its argument, use = (or +nothing). Bad: + +assets depth:2 +-X USD + + Good: + +assets +depth:2 +-X=USD + + For special characters (see below), use one less level of quoting +than you would at the command prompt. Bad: + +-X"$" + + Good: + +-X$ + + See also: Save frequently used options. + + +File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options + +2.4 Special characters +====================== + +* Menu: + +* Single escaping shell metacharacters:: +* Double escaping regular expression metacharacters:: +* Triple escaping for add-on commands:: +* Less escaping:: + + +File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters + +2.4.1 Single escaping (shell metacharacters) +-------------------------------------------- + +In shell command lines, characters significant to your shell - such as +spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped" +if you want hledger to see them. This is done by enclosing them in +single or double quotes, or by writing a backslash before them. Eg to +match an account name containing a space: + +$ hledger register 'credit card' + + or: + +$ hledger register credit\ card + + Windows users should keep in mind that ‘cmd’ treats single quote as a +regular character, so you should be using double quotes exclusively. +PowerShell treats both single and double quotes as quotes. + + +File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters + +2.4.2 Double escaping (regular expression metacharacters) +--------------------------------------------------------- + +Characters significant in regular expressions (described below) - such +as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be +"regex-escaped" if you don’t want them to be interpreted by hledger’s +regular expression engine. This is done by writing backslashes before +them, but since backslash is typically also a shell metacharacter, both +shell-escaping and regex-escaping will be needed. Eg to match a literal +‘$’ sign while using the bash shell: + +$ hledger balance cur:'\$' + + or: + +$ hledger balance cur:\\$ + + +File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters + +2.4.3 Triple escaping (for add-on commands) +------------------------------------------- + +When you use hledger to run an external add-on command (described +below), one level of shell-escaping is lost from any options or +arguments intended for by the add-on command, so those need an extra +level of shell-escaping. Eg to match a literal ‘$’ sign while using the +bash shell and running an add-on command (‘ui’): + +$ hledger ui cur:'\\$' + + or: + +$ hledger ui cur:\\\\$ + + If you wondered why _four_ backslashes, perhaps this helps: + +unescaped: ‘$’ +escaped: ‘\$’ +double-escaped: ‘\\$’ +triple-escaped: ‘\\\\$’ + + Or, you can avoid the extra escaping by running the add-on executable +directly: + +$ hledger-ui cur:\\$ + + +File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters + +2.4.4 Less escaping +------------------- + +Options and arguments are sometimes used in places other than the shell +command line, where shell-escaping is not needed, so there you should +use one less level of escaping. Those places include: + + • an @argumentfile + • hledger-ui’s filter field + • hledger-web’s search form + • GHCI’s prompt (used by developers). + + +File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options + +2.5 Unicode characters +====================== + +hledger is expected to handle non-ascii characters correctly: + + • they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web’s + search/add/edit forms, etc.) + + • they should be displayed correctly by all hledger tools, and + on-screen alignment should be preserved. + + This requires a well-configured environment. Here are some tips: + + • A system locale must be configured, and it must be one that can + decode the characters being used. In bash, you can set a locale + like this: ‘export LANG=en_US.UTF-8’. There are some more details + in Troubleshooting. This step is essential - without it, hledger + will quit on encountering a non-ascii character (as with all + GHC-compiled programs). + + • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode + + • the terminal must be using a font which includes the required + unicode glyphs + + • the terminal should be configured to display wide characters as + double width (for report alignment) + + • on Windows, for best results you should run hledger in the same + kind of environment in which it was built. Eg hledger built in the + standard CMD.EXE environment (like the binaries on our download + page) might show display problems when run in a cygwin or msys + terminal, and vice versa. (See eg #961). + + +File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options + +2.6 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 directive and ‘--alias’ option: ‘alias /REGEX/ = + REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’ + + hledger’s regular expressions come from the regex-tdfa library. If +they’re not doing what you expect, it’s important to know exactly what +they support: + + 1. they are case insensitive + 2. they are infix matching (they do not need to match the entire thing + being matched) + 3. they are POSIX ERE (extended regular expressions) + 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’) + 5. they do not support backreferences; if you write ‘\1’, it will + match the digit ‘1’. Except when doing text replacement, eg in + account aliases, where backreferences can be used in the + replacement string to reference capturing groups in the search + regexp. + 6. they do not support mode modifiers (‘(?s)’), character classes + (‘\w’, ‘\d’), or anything else not mentioned above. + + 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: Environment, Next: Input, Prev: Options, Up: Top + +3 Environment +************* + +*LEDGER_FILE* The journal file path when not specified with ‘-f’. + + On unix computers, the default value is: ‘~/.hledger.journal’. + + A more typical value is something like ‘~/finance/YYYY.journal’, +where ‘~/finance’ is a version-controlled finance directory and YYYY is +the current year. Or, ‘~/finance/current.journal’, where +current.journal is a symbolic link to YYYY.journal. + + The usual way to set this permanently is to add a command to one of +your shell’s startup files (eg ‘~/.profile’): + +export LEDGER_FILE=~/finance/current.journal` + + On some Mac computers, there is a more thorough way to set +environment variables, that will also affect applications started from +the GUI (eg, Emacs started from a dock icon): In +‘~/.MacOSX/environment.plist’, add an entry like: + +{ + "LEDGER_FILE" : "~/finance/current.journal" +} + + For this to take effect you might need to ‘killall Dock’, or reboot. + + On Windows computers, the default value is probably +‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a +command like this in a powershell window (let us know if you need to be +an Administrator, and if this persists across a reboot): + +> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" + + Or, change it in settings: see +https://www.java.com/en/download/help/path.html. + + *COLUMNS* The screen width used by the register command. Default: +the full terminal width. + + *NO_COLOR* If this variable exists with any value, hledger will not +use ANSI color codes in terminal output. This is overriden by the +–color/–colour option. + + +File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top + +4 Input +******* + +hledger reads transactions from one or more data files. The default +data file is ‘$HOME/.hledger.journal’ (or on Windows, something like +‘C:\Users\YOURNAME\.hledger.journal’). + + You can override this with the ‘$LEDGER_FILE’ environment variable: + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with one or more ‘-f/--file’ options: + +$ hledger -f /some/file -f another_file stats + + The file name ‘-’ means standard input: + +$ cat some.journal | hledger -f- + +* Menu: + +* Data formats:: +* Multiple files:: +* Strict mode:: + + +File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input + +4.1 Data formats +================ + +Usually the data file is in hledger’s journal format, but it can be in +any of the supported file formats, which currently are: + +Reader: Reads: Used for file + extensions: +-------------------------------------------------------------------------- +‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’ + journals, for transactions ‘.hledger’ ‘.ledger’ +‘timeclock’timeclock files, for precise time ‘.timeclock’ + logging +‘timedot’timedot files, for approximate time ‘.timedot’ + logging +‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’ + values, for data import + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions +shown above. If it can’t recognise the file extension, it assumes +‘journal’ format. So for non-journal files, it’s important to use a +recognised file extension, so as to either read successfully or to show +relevant error messages. + + You can also force a specific reader/format by prefixing the file +path with the format and a colon. Eg, to read a .dat file as csv +format: + +$ hledger -f csv:/some/csv-file.dat stats + + Or to read stdin (‘-’) as timeclock format: + +$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- + + +File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input + +4.2 Multiple files +================== + +You can specify multiple ‘-f’ options, to read multiple files as one big +journal. There are some limitations with this: + + • most directives do not affect sibling files + • balance assertions will not see any account balances from previous + files + + If you need either of those things, you can + + • use a single parent file which includes the others + • or concatenate the files into one before reading, eg: ‘cat + a.journal b.journal | hledger -f- CMD’. + + +File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input + +4.3 Strict mode +=============== + +hledger checks input files for valid data. By default, the most +important errors are detected, while still accepting easy journal files +without a lot of declarations: + + • Are the input files parseable, with valid syntax ? + • Are all transactions balanced ? + • Do all balance assertions pass ? + + With the ‘-s’/‘--strict’ flag, additional checks are performed: + + • Are all accounts posted to, declared with an ‘account’ directive ? + (Account error checking) + • Are all commodities declared with a ‘commodity’ directive ? + (Commodity error checking) + • Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks – the ones +listed above and some more. + + +File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top + +5 Commands +********** + +hledger provides a number of built-in subcommands (described below). +Most of these read your data without changing it, and display a report. +A few assist with data entry and management. + + Run ‘hledger’ with no arguments to list the commands available, and +‘hledger CMD’ to run a command. CMD can be the full command name, or +its standard abbreviation shown in the commands list, or any unambiguous +prefix of the name. Eg: ‘hledger bal’. + +* Menu: + +* Add-on commands:: + + +File: hledger.info, Node: Add-on commands, Up: Commands + +5.1 Add-on commands +=================== + +Add-on commands are extra subcommands provided by programs or scripts in +your PATH + + • whose name starts with ‘hledger-’ + • whose name ends with a recognised file extension: + ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’ + or none + • and (on unix, mac) which are executable by the current user. + + Addons can be written in any language, but haskell scripts or +programs have a big advantage: they can use hledger’s library code, for +command-line options, parsing and reporting. + + Several add-on commands are installed by the hledger-install script. +See https://hledger.org/scripts.html for more details. + + Note in a hledger command line, add-on command flags must have a +double dash (‘--’) preceding them. Eg you must write: + +$ hledger web -- --serve + + and not: + +$ hledger web --serve + + (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’). + + The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’. + + If you have any trouble with this, remember you can always run the +add-on program directly, eg: + +$ hledger-web --serve + + +File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top + +6 Output +******** + +* Menu: + +* Output destination:: +* Output format:: +* Commodity styles:: +* Colour:: +* Box-drawing:: +* Debug output:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: Output + +6.1 Output destination +====================== + +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: + +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the ‘-o/--output-file’ option, which does the same thing without +needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) + + +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output + +6.2 Output format +================= + +Some commands offer other kinds of output, not just text on the +terminal. Here are those commands and the formats currently supported: + +- txt csv html json sql +----------------------------------------------------------------------------- +aregister Y Y Y Y +balance Y _1_ Y _1_ Y _1,2_ Y +balancesheet Y _1_ Y _1_ Y _1_ Y +balancesheetequity Y _1_ Y _1_ Y _1_ Y +cashflow Y _1_ Y _1_ Y _1_ Y +incomestatement Y _1_ Y _1_ Y _1_ Y +print Y Y Y Y +register Y Y Y + + • _1 Also affected by the balance commands’ ‘--layout’ option._ + • _2 ‘balance’ does not support html output without a report interval + or with ‘--budget’._ + + The output format is selected by the ‘-O/--output-format=FMT’ option: + +$ hledger print -O csv # print CSV on stdout + + or by the filename extension of an output file specified with the +‘-o/--output-file=FILE.FMT’ option: + +$ hledger balancesheet -o foo.csv # write CSV to foo.csv + + The ‘-O’ option can be combined with ‘-o’ to override the file +extension, if needed: + +$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt + + Some notes about the various output formats: + +* Menu: + +* CSV output:: +* HTML output:: +* JSON output:: +* SQL output:: + + +File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format + +6.2.1 CSV output +---------------- + + • In CSV output, digit group marks (such as thousands separators) are + disabled automatically. + + +File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format + +6.2.2 HTML output +----------------- + + • HTML output can be styled by an optional ‘hledger.css’ file in the + same directory. + + +File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format + +6.2.3 JSON output +----------------- + + • This is not yet much used; real-world feedback is welcome. + + • Our JSON is rather large and verbose, since it is a faithful + representation of hledger’s internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + + • hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction + prices), and would break most JSON consumers. So in JSON, we show + quantities as simple Numbers with at most 10 decimal places. We + don’t limit the number of integer digits, but that part is under + your control. We hope this approach will not cause problems in + practice; if you find otherwise, please let us know. (Cf #1195) + + +File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format + +6.2.4 SQL output +---------------- + + • This is not yet much used; real-world feedback is welcome. + + • SQL output is expected to work with sqlite, MySQL and PostgreSQL + + • SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables + created via SQL output of hledger, you would probably want to + either clear tables of existing data (via ‘delete’ or ‘truncate’ + SQL statements) or drop tables completely as otherwise your + postings will be duped. + + +File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output + +6.3 Commodity styles +==================== + +When displaying amounts, hledger infers a standard display style for +each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a ‘-c/--commodity-style’ option +(except for cost amounts and amounts displayed by the ‘print’ command, +which are always displayed with all decimal digits). For example, the +following will force dollar amounts to be displayed as shown: + +$ hledger print -c '$1.000,0' + + This option can repeated to set the display style for multiple +commodities/currencies. Its argument is as described in the commodity +directive. + + +File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output + +6.4 Colour +========== + +In terminal output, some commands can produce colour when the terminal +supports it: + + • if the ‘--color/--colour’ option is given a value of ‘yes’ or + ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used; + • otherwise, if the ‘NO_COLOR’ environment variable is set, colour + will not be used; + • otherwise, colour will be used if the output (terminal or file) + supports it. + + +File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output + +6.5 Box-drawing +=============== + +In terminal output, you can enable unicode box-drawing characters to +render prettier tables: + + • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or + ‘no’ or ‘never’), unicode characters will (or will not) be used; + • otherwise, unicode characters will not be used. + + +File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output + +6.6 Debug output +================ + +We intend hledger to be relatively easy to troubleshoot, introspect and +develop. You can add ‘--debug[=N]’ to any hledger command line to see +additional debug output. N ranges from 1 (least output, the default) to +9 (maximum output). Typically you would start with 1 and increase until +you are seeing enough. Debug output goes to stderr, and is not affected +by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg: +‘2>&1’). It will be interleaved with normal output, which can help +reveal when parts of the code are evaluated. To capture debug output in +a log file instead, you can usually redirect stderr, eg: + +hledger bal --debug=3 2>hledger.log + + +File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top + +7 Limitations +************* + +The need to precede add-on 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. + + On Windows, non-ascii characters may not display correctly when +running a hledger built in CMD in MSYS/CYGWIN, or vice-versa. + + 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 hledger +and Ledger > Differences > journal format. + + On large data files, hledger is slower and uses more memory than +Ledger. + + +File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top + +8 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. + + *Getting errors like "Illegal byte sequence" or "Invalid or +incomplete multibyte or wide character" or "commitAndReleaseBuffer: +invalid argument (invalid character)"* +Programs compiled with GHC (hledger, haskell build tools, etc.) need to +have a UTF-8-aware locale configured in the environment, otherwise they +will fail with these kinds of errors when they encounter non-ascii +characters. + + To fix it, set the LANG environment variable to some locale which +supports UTF-8. The locale you choose must be installed on your system. + + Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux: + +$ file my.journal +my.journal: UTF-8 Unicode text # the file is UTF8-encoded +$ echo $LANG +C # LANG is set to the default locale, which does not support UTF8 +$ locale -a # which locales are installed ? +C +en_US.utf8 # here's a UTF8-aware one we can use +POSIX +$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command + + If available, ‘C.UTF-8’ will also work. If your preferred locale +isn’t listed by ‘locale -a’, you might need to install it. Eg on +Ubuntu/Debian: + +$ 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 + + Here’s how you could set it permanently, if you use a bash shell: + +$ echo "export LANG=en_US.utf8" >>~/.bash_profile +$ bash --login + + Exact spelling and capitalisation may be important. Note the +difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu) +allow variant spellings, but others (eg macos) require it to be exact: + +$ locale -a | grep -iE en_us.*utf +en_US.UTF-8 +$ LANG=en_US.UTF-8 hledger -f my.journal print + + +File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top + +9 PART 2: DATA FORMATS +********************** + + +File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top + +10 Journal +********** + +hledger’s default file format, representing a General Journal. Here’s a +cheatsheet/mini-tutorial, or you can skip ahead to About journal format. + +* Menu: + +* Journal cheatsheet:: +* About journal format:: +* Comments:: +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Transaction comments:: +* Postings:: +* Account names:: +* Amounts:: +* Costs:: +* Balance assertions:: +* Posting comments:: +* Tags:: +* Directives:: +* account directive:: +* alias directive:: +* commodity directive:: +* decimal-mark directive:: +* include directive:: +* P directive:: +* payee directive:: +* tag directive:: +* Periodic transactions:: +* Other syntax:: + + +File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal + +10.1 Journal cheatsheet +======================= + +# Here is the main syntax of hledger's journal format +# (omitting extra Ledger compatibility syntax). +# hledger journals contain comments, directives, and transactions, in any order: + +############################################################################### +# 1. Comment lines are for notes or temporarily disabling things. +# They begin with #, ;, or a line containing the word "comment". + +# hash comment line +; semicolon comment line +comment +These lines +are commented. +end comment + +# Some but not all hledger entries can have same-line comments attached to them, +# from ; (semicolon) to end of line. + +############################################################################### +# 2. Directives modify parsing or reports in some way. +# They begin with a word or letter (or symbol). + +account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. +account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) +alias chkg = assets:checking +commodity $0.00 +decimal-mark . +include /dev/null +payee Whole Foods +P 2022-01-01 AAAA $1.40 +~ monthly budget goals ; <- 2+ spaces between period expression and description + expenses:food $400 + expenses:home $1000 + budgeted + +############################################################################### +# 3. Transactions are what it's all about; they are dated events, +# usually describing movements of money. +# They begin with a date. + +# DATE DESCRIPTION ; This is a transaction comment. +# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. +# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. +# ; ^^ At least 2 spaces between account and amount. +# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). + +2022-01-01 opening balances are declared this way + assets:checking $1000 ; Account names can be anything. lower case is easy to type. + assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. + assets:cash:wallet $100 ; : indicates subaccounts. + liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. + equity ; One amount can be left blank; $-1900 is inferred here. + +2022-04-15 * (#12345) pay taxes + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a transaction code (text in parentheses) after the date/status. + ; Amounts' sign represents direction of flow, or credit/debit: + assets:checking $-500 ; minus means removed from this account (credit) + expenses:tax:us:2021 $500 ; plus means added to this account (debit) + ; revenue/expense categories are also "accounts" + +Kv +2022-01-01 ; The description is optional. + ; Any currency/commodity symbols are allowed, on either side. + assets:cash:wallet GBP -10 + expenses:clothing GBP 10 + assets:gringotts -10 gold + assets:pouch 10 gold + revenues:gifts -2 "Liquorice Wands" ; Complex symbols + assets:bag 2 "Liquorice Wands" ; must be double-quoted. + +2022-01-01 Cost in another commodity can be noted with @ or @@ + assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments 3.0 AAAA @@ $4 ; @@ means total cost + assets:checking $-7.00 + +2022-01-02 assert balances + ; Balances can be asserted for extra error checking, in any transaction. + assets:investments 0 AAAA = 5.0 AAAA + assets:pouch 0 gold = 10 gold + assets:savings $0 = $1000 + +1999-12-31 Ordering transactions by date is recommended but not required. + ; Postings are not required. + +2022.01.01 These date +2022/1/1 formats are +12/31 also allowed (but consistent YYYY-MM-DD is recommended). + + +File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal + +10.2 About journal format +========================= + +hledger’s usual data source is a plain text file containing journal +entries in hledger journal format. This file represents a standard +accounting general journal. I use file names ending in ‘.journal’, but +that’s not required. The journal file contains a number of transaction +entries, each describing a transfer of money (or any commodity) between +two or more named accounts, in a simple format readable by both hledger +and humans. + + hledger’s journal format is a compatible subset, mostly, of ledger’s +journal format, so hledger can work with compatible ledger journal files +as well. It’s safe, and encouraged, to run both hledger and ledger on +the same journal file, eg to validate the results you’re getting. + + You can use hledger without learning any more about this file; just +use the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and +track changes with a version control system such as git. Editor addons +such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and +hledger-vscode for Visual Studio Code, make this easier, adding colour, +formatting, tab completion, and useful commands. See Editor +configuration at hledger.org for the full list. + + Here’s a description of each part of the file format (and hledger’s +data model). + + A hledger journal file can contain three kinds of thing: file +comments, transactions, and/or directives (counting periodic transaction +rules and auto posting rules as directives). + + +File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal + +10.3 Comments +============= + +Lines in the journal will be ignored if they begin with a hash (‘#’) or +a semicolon (‘;’). (See also Other syntax.) hledger will also ignore +regions beginning with a ‘comment’ line and ending with an ‘end comment’ +line (or file end). Here’s a suggestion for choosing between them: + + • ‘#’ for top-level notes + • ‘;’ for commenting out things temporarily + • ‘comment’ for quickly commenting large regions (remember it’s + there, or you might get confused) + + Eg: + +# a comment line +; another commentline +comment +A multi-line comment block, +continuing until "end comment" directive +or the end of the current file. +end comment + + Some hledger entries can have same-line comments attached to them, +from ; (semicolon) to end of line. See Transaction comments, Posting +comments, and Account comments below. + + +File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal + +10.4 Transactions +================= + +Transactions are the main unit of information in a journal file. They +represent events, typically a movement of some quantity of commodities +between two or more named accounts. + + Each transaction is recorded as a journal entry, beginning with a +simple date in column 0. This can be followed by any of the following +optional fields, separated by spaces: + + • a status character (empty, ‘!’, or ‘*’) + • a code (any short number or text, enclosed in parentheses) + • a description (any remaining text until end of line or a semicolon) + • a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + • 0 or more indented _posting_ lines, describing what was transferred + and the accounts involved (indented comment lines are also allowed, + but not blank lines or non-indented lines). + + Here’s a simple journal file containing one transaction: + +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + +File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal + +10.5 Dates +========== + +* Menu: + +* Simple dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates + +10.5.1 Simple dates +------------------- + +Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or +‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may +be omitted, in which case it will be inferred from the context: the +current transaction, the default year set with a ‘Y’ directive, or the +current date when the command is run. Some examples: ‘2010-01-31’, +‘2010/01/31’, ‘2010.1.31’, ‘1/31’. + + (The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.) + + +File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates + +10.5.2 Posting dates +-------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like ‘date:DATE’. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction’s date. +The ‘date:’ tag must have a valid simple date value if it is present, eg +a ‘date:’ tag with no value is not allowed. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal + +10.6 Status +=========== + +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +‘!’ pending +‘*’ cleared + + When reporting, you can filter by status with the ‘-U/--unmarked’, +‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’, +and ‘status:*’ queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" +state is called "uncleared". As of hledger 1.3 we have renamed it to +unmarked for clarity. + + To replicate Ledger and old hledger’s behaviour of also matching +pending, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here’s one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use ‘-PC’ to see the current balance at +your bank, ‘-U’ to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal + +10.7 Code +========= + +After the status mark, but before the description, you can optionally +write a transaction "code", enclosed in parentheses. This is a good +place to record a check number, or some other important transaction id +or reference number. + + +File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal + +10.8 Description +================ + +A transaction’s description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +10.8.1 Payee and note +--------------------- + +You can optionally include a ‘|’ (pipe) character in descriptions to +subdivide the description into separate fields for payee/payer name on +the left (up to the first ‘|’) and an additional note field on the right +(after the first ‘|’). This may be worthwhile if you need to do more +precise querying and pivoting by payee or by note. + + +File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal + +10.9 Transaction comments +========================= + +Text following ‘;’, after a transaction description, and/or on indented +lines immediately below it, form comments for that transaction. They +are reproduced by ‘print’ but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal + +10.10 Postings +============== + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + • (optional) a status character (empty, ‘!’, or ‘*’), followed by a + space + • (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + • (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, one amount may be left blank; it will be inferred so as to +balance the transaction. + + Be sure to note the unusual two-space delimiter between account name +and amount. This makes it easy to write account names containing +spaces. But if you accidentally leave only one space (or tab) before +the amount, the amount will be considered part of the account name. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal + +10.11 Account names +=================== + +Accounts are the main way of categorising things in hledger. As in +Double Entry Bookkeeping, they can represent real world accounts (such +as a bank account), or more abstract categories such as "money borrowed +from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the +traditional accounting categories, which in english are ‘assets’, +‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these +referred to as A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts +into more detailed subaccounts, by writing a full colon between account +name parts. For example, from the account names ‘assets:bank:checking’ +and ‘expenses:food’, hledger will infer this hierarchy of five accounts: + +assets +assets:bank +assets:bank:checking +expenses +expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + +assets + bank + checking +expenses + food + + hledger reports can summarise the account tree to any depth, so you +can go as deep as you like with subcategories, but keeping your account +names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, +numbers, symbols, or single spaces. Note, when an account name and an +amount are written on the same line, they must be separated by *two or +more spaces* (or tabs). + + Parentheses or brackets enclosing the full account name indicate +virtual postings, described below. Parentheses or brackets internal to +the account name have no special meaning. + + Account names can be altered temporarily or permanently by account +aliases. + + +File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal + +10.12 Amounts +============= + +After the account name, there is usually an amount. (Important: between +account name and amount, there must be *two or more spaces*.) + + hledger’s amount format is flexible, supporting several international +formats. Here are some examples. Amounts have a number (the +"quantity"): + +1 + + ..and usually a currency symbol or commodity name (more on this +below), to the left or right of the quantity, with or without a +separating space: + +$1 +4000 AAPL +3 "green apples" + + Amounts can be preceded by a minus sign (or a plus sign, though plus +is the default), The sign can be written before or after a left-side +commodity symbol: + +-$1 +$-1 + + One or more spaces between the sign and the number are acceptable +when parsing (but they won’t be displayed in output): + ++ $1 +$- 1 + + Scientific E notation is allowed: + +1E-6 +EUR 1E3 + +* Menu: + +* Decimal marks digit group marks:: +* Commodity:: +* Directives influencing number parsing and display:: +* Commodity display style:: +* Rounding:: + + +File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts + +10.12.1 Decimal marks, digit group marks +---------------------------------------- + +A _decimal mark_ can be written as a period or a comma: + +1.23 +1,23456780000009 + + In the integer part of the quantity (left of the decimal mark), +groups of digits can optionally be separated by a _digit group mark_ - a +space, comma, or period (different from the decimal mark): + + $1,000,000.00 + EUR 2.000.000,00 +INR 9,99,99,999.00 + 1 000 000.9455 + + Note, a number containing a single digit group mark and no decimal +mark is ambiguous. Are these digit group marks or decimal marks ? + +1,000 +1.000 + + If you don’t tell it otherwise, hledger will assume both of the above +are decimal marks, parsing both numbers as 1. + + To prevent confusing parsing mistakes and undetected typos, +especially if your data contains digit group marks (eg, thousands +separators), we recommend explicitly declaring the decimal mark +character in each journal file, using a directive at the top of the +file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’ +directives will also work. These are described below. + + +File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts + +10.12.2 Commodity +----------------- + +Amounts in hledger have both a "quantity", which is a signed decimal +number, and a "commodity", which is a currency symbol, stock ticker, or +any word or phrase describing something you are tracking. + + If the commodity name contains non-letters (spaces, numbers, or +punctuation), you must always write it inside double quotes (‘"green +apples"’, ‘"ABC123"’). + + If you write just a bare number, that too will have a commodity, with +name ‘""’; we call that the "no-symbol commodity". + + Actually, hledger combines these single-commodity amounts into more +powerful multi-commodity amounts, which are what it works with most of +the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456 +TSLA’. In practice, you will only see multi-commodity amounts in +hledger’s output; you can’t write them directly in the journal file. + + (If you are writing scripts or working with hledger’s internals, +these are the ‘Amount’ and ‘MixedAmount’ types.) + + +File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts + +10.12.3 Directives influencing number parsing and display +--------------------------------------------------------- + +You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to +declare and control these things more explicitly and precisely. These +are described below, but here’s a quick example: + +# the decimal mark character used by all amounts in this file (all commodities) +decimal-mark . + +# display styles for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 + + +File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts + +10.12.4 Commodity display style +------------------------------- + +For the amounts in each commodity, hledger chooses a consistent display +style to use in most reports. (Exceptions: price amounts, and all +amounts displayed by the ‘print’ command, are displayed with all of +their decimal digits visible.) + + A commodity’s display style is inferred as follows. + + First, if a default commodity is declared with ‘D’, this commodity +and its style is applied to any no-symbol amounts in the journal. + + Then each commodity’s style is inferred from one of the following, in +order of preference: + + • The commodity directive for that commodity (including the no-symbol + commodity), if any. + • The amounts in that commodity seen in the journal’s transactions. + (Posting amounts only; prices and periodic or auto rules are + ignored, currently.) + • The built-in fallback style, which looks like this: ‘$1000.00’. + (Symbol on the left, period decimal mark, two decimal places.) + + A style is inferred from journal amounts as follows: + + • Use the general style (decimal mark, symbol placement) of the first + amount + • Use the first-seen digit group style (digit group mark, digit group + sizes), if any + • Use the maximum number of decimal places of all. + + Cost amounts don’t affect the commodity display style directly, but +occasionally they can do so indirectly (eg when a posting’s amount is +inferred using a cost). If you find this causing problems, use a +commodity directive to fix the display style. + + To summarise: each commodity’s amounts will be normalised to (a) the +style declared by a ‘commodity’ directive, or (b) the style of the first +posting amount in the journal, with the first-seen digit group style and +the maximum-seen number of decimal places. So if your reports are +showing amounts in a way you don’t like, eg with too many decimal +places, use a commodity directive. Some examples: + +# declare euro, dollar, bitcoin and no-symbol commodities and set their +# input number formats and output display styles: +commodity EUR 1.000, +commodity $1000.00 +commodity 1000.00000000 BTC +commodity 1 000. + + The inferred commodity style can be overridden by supplying a command +line option. + + +File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts + +10.12.5 Rounding +---------------- + +Amounts are stored internally as decimal numbers with up to 255 decimal +places, and displayed with the number of decimal places specified by the +commodity display style. Note, hledger uses banker’s rounding: it +rounds to the nearest even number, eg 0.5 displayed with zero decimal +places is "0"). + + +File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal + +10.13 Costs +=========== + +After a posting amount, you can note its cost (when buying) or selling +price (when selling) in another commodity, by writing either ‘@ +UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion +transaction, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, +discussions, or code; that term was directionally neutral and reminded +that it is a price specific to a transaction, but we now just call it +"cost", with the understanding that the transaction could be a purchase +or a sale.) + + Costs are usually written explicitly with ‘@’ or ‘@@’, but can also +be inferred automatically for simple multi-commodity transactions. +Note, if costs are inferred, the order of postings is significant; the +first posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign +currency in hledger, using the cost notation either explicitly or +implicitly: + + 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction. + Note the effect of posting order: the price is added to first + posting, making it ‘€100 @@ $135’, as in example 2: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the ‘-B/--cost’ +flag; this is discussed more in the ˜COST REPORTING section. + +* Menu: + +* Other cost/lot notations:: + + +File: hledger.info, Node: Other cost/lot notations, Up: Costs + +10.13.1 Other cost/lot notations +-------------------------------- + +A slight digression for Ledger and Beancount users. Ledger has a number +of cost/lot-related notations: + + • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ + • expresses a conversion rate, as in hledger + • when buying, also creates a lot than can be selected at + selling time + + • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost) + • like the above, but also means "this cost was exceptional, + don’t use it when inferring market prices". + + Currently, hledger treats the above like ‘@’ and ‘@@’; the +parentheses are ignored. + + • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price) + • when buying, means "this cost is also the fixed price, don’t + let it fluctuate in value reports" + + • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price) + • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’, + also creates a lot + • when selling, combined with ‘@ ...’, specifies an investment + lot by its cost basis; does not check if that lot is present + + • and related: ‘[YYYY/MM/DD]’ (lot date) + • when buying, attaches this acquisition date to the lot + • when selling, selects a lot by its acquisition date + + • ‘(SOME TEXT)’ (lot note) + • when buying, attaches this note to the lot + • when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after +the posting amount, but ignores them. (This can break transaction +balancing.) + + For Beancount users, the notation and behaviour is different: + + • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ + • expresses a cost without creating a lot, as in hledger + • when buying (augmenting) or selling (reducing) a lot, combined + with ‘{...}’: documents the cost/selling price (not used for + transaction balancing) + + • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ + • when buying (augmenting), expresses the cost for transaction + balancing, and also creates a lot with this cost basis + attached + • when selling (reducing), + • selects a lot by its cost basis + • raises an error if that lot is not present or can not be + selected unambiguously (depending on booking method + configured) + • expresses the selling price for transaction balancing + + Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation +but ignores it. + + • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST, + "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc. + + Currently, hledger rejects these. + + +File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal + +10.14 Balance assertions +======================== + +hledger supports Ledger-style balance assertions in journal files. +These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s +amount. Eg here we assert the expected dollar balance in accounts a and +b after each posting: + +2013/1/1 + a $1 =$1 + b =$-1 + +2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the ‘-I/--ignore-assertions’ flag, which can be useful for +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, described below). + +* Menu: + +* Assertions and ordering:: +* Assertions and multiple included files:: +* Assertions and multiple -f files:: +* Assertions and commodities:: +* Assertions and prices:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: +* Assertions and auto postings:: +* Assertions and precision:: + + +File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions + +10.14.1 Assertions and ordering +------------------------------- + +hledger sorts an account’s postings and assertions first by date and +then (for postings on the same day) by parse order. Note this is +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder +differently-dated transactions within the journal. But if you reorder +same-dated transactions or postings, assertions might break and require +updating. This order dependence does bring an advantage: precise +control over the order of postings and assertions within a day, so you +can assert intra-day balances. + + +File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions + +10.14.2 Assertions and multiple included files +---------------------------------------------- + +Multiple files included with the ‘include’ directive are processed as if +concatenated into one file, preserving their order and the posting order +within each file. It means that balance assertions in later files will +see balance from earlier files. + + And if you have multiple postings to an account on the same day, +split across multiple files, and you want to assert the account’s +balance on that day, you’ll need to put the assertion in the right file +- the last one in the sequence, probably. + + +File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions + +10.14.3 Assertions and multiple -f files +---------------------------------------- + +Unlike ‘include’, when multiple files are specified on the command line +with multiple ‘-f/--file’ options, balance assertions will not see +balance from earlier files. This can be useful when you do not want +problems in earlier files to disrupt valid assertions in later files. + + If you do want assertions to see balance from earlier files, use +‘include’, or concatenate the files temporarily. + + +File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions + +10.14.4 Assertions and commodities +---------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity’s balance within the +(possibly multi-commodity) account balance. This is how assertions work +in Ledger also. We could call this a "partial" balance assertion. + + To assert the balance of more than one commodity in an account, you +can write multiple postings, each asserting one commodity’s balance. + + You can make a stronger "total" balance assertion by writing a double +equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no +other commodities in the account besides the asserted one (or at least, +that their balance is 0). + +2013/1/1 + a $1 + a 1€ + b $-1 + c -1€ + +2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1€ + b 0 == $-1 + c 0 == -1€ + +2013/1/3 ; This assertion fails as 'a' also contains 1€ + a 0 == $1 + + It’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: + +2013/1/1 + a:usd $1 + a:euro 1€ + b + +2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1€ + + +File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions + +10.14.5 Assertions and prices +----------------------------- + +Balance assertions ignore costs, 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.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions + +10.14.6 Assertions and subaccounts +---------------------------------- + +The balance assertions above (‘=’ and ‘==’) do not count the balance +from subaccounts; they check the account’s exclusive balance only. You +can assert the balance including subaccounts by writing ‘=*’ or ‘==*’, +eg: + +2019/1/1 + equity:opening balances + checking:a 5 + checking:b 5 + checking 1 ==* 11 + + +File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions + +10.14.7 Assertions and virtual postings +--------------------------------------- + +Balance assertions always consider both real and virtual postings; they +are not affected by the ‘--real/-R’ flag or ‘real:’ query. + + +File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions + +10.14.8 Assertions and auto postings +------------------------------------ + +Balance assertions _are_ affected by the ‘--auto’ flag, which generates +auto postings, which can alter account balances. Because auto postings +are optional in hledger, accounts affected by them effectively have two +balances. But balance assertions can only test one or the other of +these. So to avoid making fragile assertions, either: + + • assert the balance calculated with ‘--auto’, and always use + ‘--auto’ with that file + • or assert the balance calculated without ‘--auto’, and never use + ‘--auto’ with that file + • or avoid balance assertions on accounts affected by auto postings + (or avoid auto postings entirely). + + +File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions + +10.14.9 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.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal + +10.15 Posting comments +====================== + +Text following ‘;’, at the end of a posting line, and/or on indented +lines immediately below it, form comments for that posting. They are +reproduced by ‘print’ but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + +File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal + +10.16 Tags +========== + +Tags are a way to add extra labels or labelled data to transactions, +postings, or accounts, which you can then search or pivot on. + + They are written as a word (optionally hyphenated) immediately +followed by a full colon, in a transaction or posting or account +directive’s comment. (This is an exception to the usual rule that +things in comments are ignored.) Eg, here four different tags are +recorded: one on the checking account, two on the transaction, and one +on the expenses posting: + +account assets:checking ; accounttag: + +2017/1/16 bought groceries ; transactiontag-1: + ; transactiontag-2: + assets:checking $-1 + expenses:food $1 ; postingtag: + + Postings also inherit tags from their transaction and their account. +And transactions also acquire tags from their postings (and postings’ +accounts). So in the example above, the expenses posting effectively +has all four tags (by inheriting from account and transaction), and the +transaction also has all four tags (by acquiring from the expenses +posting). + + You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by +tag name with a ‘tag:NAMEREGEX’ query. + +* Menu: + +* Tag values:: + + +File: hledger.info, Node: Tag values, Up: Tags + +10.16.1 Tag values +------------------ + +Tags can have a value, which is any text after the colon up until a +comma or end of line (with surrounding whitespace removed). Note this +means that hledger tag values can not contain commas. Eg in the +following posting, the three tags’ values are "value 1", "value 2", and +"" (empty) respectively: + + expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz + + Note that tags can be repeated, and are additive rather than +overriding: when the same tag name is seen again with a new value, the +new name:value pair is added to the tags. (It is not possible to +override a tag’s value or remove a tag.) + + You can list a tag’s values with ‘hledger tags TAGNAME --values’, or +match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query. + + +File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal + +10.17 Directives +================ + +A directive is a line in the journal beginning with a special keyword, +that influences how the journal is processed, how things are displayed, +and so on. hledger’s directives are based on (a subset of) Ledger’s, +but there are many differences, and also some differences between +hledger versions. Here are some more definitions: + + • _subdirective_ - Some directives support subdirectives, written + indented below the parent directive. + + • _decimal mark_ - The character to interpret as a decimal mark + (period or comma) when parsing amounts of a commodity. + + • _display style_ - How to display amounts of a commodity in output: + symbol side and spacing, digit groups, decimal mark, and number of + decimal places. + + Directives are not required when starting out with hledger, but you +will probably want to add some as your needs grow. Here some key +directives for particular needs: + +purpose directives +-------------------------------------------------------------------------- +*READING DATA:* +Declare file’s decimal mark to help parse ‘decimal-mark’ +amounts accurately +Rewrite account names ‘alias’ +Comment out sections of the data ‘comment’ +Include extra data files ‘include’ +*GENERATING DATA:* +Generate recurring transactions or budget ‘~’ +goals +Generate extra postings on transactions ‘=’ +*CHECKING FOR ERRORS:* +Define valid entities to provide more ‘account’, ‘commodity’, +error checking ‘payee’ +*REPORTING:* +Declare accounts’ type and display order ‘account’ +Declare commodity display styles ‘commodity’ +Declare market prices ‘P’ + +* Menu: + +* Directive effects:: +* Directives and multiple files:: + + +File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives + +10.17.1 Directive effects +------------------------- + +And here is what each directive does, and which files and journal +entries (transactions) it affects: + +directivewhat it does ends + at + file + end? +--------------------------------------------------------------------------- +*‘account’*Declares an account, for checking all entries in all files; andN + its display order and type. Subdirectives: any text, ignored. +*‘alias’*Rewrites account names, in following entries until end of Y + current file or ‘end aliases’. Command line equivalent: + ‘--alias’ +*‘comment’*Ignores part of the journal file, until end of current file orY + ‘end comment’. +*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N + all amounts in all files 2. the decimal mark for parsing + amounts of this commodity, in the following entries until end of + current file (if there is no ‘decimal-mark’ directive) 3. and + the display style for amounts of this commodity 4. which is + also the precision to use for balanced-transaction checking in + this commodity. Takes precedence over ‘D’. Subdirectives: + ‘format’ (Ledger-compatible syntax). Command line equivalent: + ‘-c/--commodity-style’ +*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y + commodities in following entries until next ‘decimal-mark’ or + end of current file. Included files can override. Takes + precedence over ‘commodity’ and ‘D’. +*‘include’*Includes entries and directives from another file, as if theyN + were written inline. Command line alternative: multiple + ‘-f/--file’ +*‘payee’*Declares a payee name, for checking all entries in all files. N +*‘P’*Declares the market price of a commodity on some date, for value N + reports. +*‘~’*Declares a periodic transaction rule that generates future N +(tilde)transactions with ‘--forecast’ and budget goals with ‘balance + --budget’. +Other +syntax: +*‘applyPrepends a common parent account to all account names, in Y +account’*following entries until end of current file or ‘end apply + account’. +*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no ‘commodity’ directive for this commodity: its + decimal mark, balancing precision, and display style, as above. +*‘Y’*Sets a default year to use for any yearless dates, in following Y + entries until end of current file. +*‘=’*Declares an auto posting rule that generates extra postings on partly +(equals)matched transactions with ‘--auto’, in current, parent, and + child files (but not sibling files, see #1212). +*OtherOther directives from Ledger’s file format are accepted but +Ledgerignored. +directives* + + +File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives + +10.17.2 Directives and multiple files +------------------------------------- + +If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive, +hledger will process multiple input files. But directives which affect +input typically have effect only until the end of the file in which they +occur (and on any included files in that region). + + This may seem inconvenient, but it’s intentional; it makes reports +stable and deterministic, independent of the order of input. Otherwise +you could see different numbers if you happened to write -f options in a +different order, or if you moved includes around while cleaning up your +files. + + It can be surprising though; for example, it means that ‘alias’ +directives do not affect parent or sibling files (see below). + + +File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal + +10.18 ‘account’ directive +========================= + +‘account’ directives can be used to declare accounts (ie, the places +that amounts are transferred from and to). Though not required, these +declarations can provide several benefits: + + • They can document your intended chart of accounts, providing a + reference. + • In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + • They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + • They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + • They can store additional account information as comments, or as + tags which can be used to filter or pivot reports. + • They can help hledger know your accounts’ types (asset, liability, + equity, revenue, expense), affecting reports like balancesheet and + incomestatement. + + They are written as the word ‘account’ followed by a hledger-style +account name, eg: + +account assets:bank:checking + + Note, however, that accounts declared in account directives are not +allowed to have surrounding brackets and parentheses, unlike accounts +used in postings. So the following journal will not parse: + +account (assets:bank:checking) + +* Menu: + +* Account comments:: +* Account subdirectives:: +* Account error checking:: +* Account display order:: +* Account types:: + + +File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive + +10.18.1 Account comments +------------------------ + +Text following *two or more spaces* and ‘;’ at the end of an account +directive line, and/or following ‘;’ on indented lines immediately below +it, form comments for that account. They are ignored except they may +contain tags, which are not ignored. + + The two-space requirement for same-line account comments is because +‘;’ is allowed in account names. + +account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + +File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive + +10.18.2 Account subdirectives +----------------------------- + +Ledger-style indented subdirectives are also accepted, but currently +ignored: + +account assets:bank:checking + format subdirective is ignored + + +File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive + +10.18.3 Account error checking +------------------------------ + +By default, accounts need not be declared; they come into existence when +a posting references them. This is convenient, but it means hledger +can’t warn you when you mis-spell an account name in the journal. +Usually you’ll find that error later, as an extra account in balance +reports, or an incorrect balance when reconciling. + + In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will +report an error if any transaction uses an account name that has not +been declared by an account directive. Some notes: + + • The declaration is case-sensitive; transactions must use the + correct account name capitalisation. + • The account directive’s scope is "whole file and below" (see + directives). This means it affects all of the current file, and + any files it includes, but not parent or sibling files. The + position of account directives within the file does not matter, + though it’s usual to put them at the top. + • Accounts can only be declared in ‘journal’ files, but will affect + included files of all types. + • It’s currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + +File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive + +10.18.4 Account display order +----------------------------- + +The order in which account directives are written influences the order +in which accounts appear in reports, hledger-ui, hledger-web etc. By +default accounts appear in alphabetical order, but if you add these +account directives to the journal file: + +account assets +account liabilities +account equity +account revenues +account expenses + + those accounts will be displayed in declaration order: + +$ hledger accounts -1 +assets +liabilities +equity +revenues +expenses + + Any undeclared accounts are displayed last, in alphabetical order. + + 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 + • sibling accounts stay together (you couldn’t display ‘x:y’ in + between ‘a:b’ and ‘a:c’). + + +File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive + +10.18.5 Account types +--------------------- + +hledger knows that accounts come in several types: assets, liabilities, +expenses and so on. This enables easy reports like balancesheet and +incomestatement, and filtering by account type with the ‘type:’ query. + + As a convenience, hledger will detect these account types +automatically if you are using common english-language top-level account +names (described below). But generally we recommend you declare types +explicitly, by adding a ‘type:’ tag to your top-level account +directives. Subaccounts will inherit the type of their parent. The +tag’s value should be one of the five main account types: + + • ‘A’ or ‘Asset’ (things you own) + • ‘L’ or ‘Liability’ (things you owe) + • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of + assets & liabilities) + • ‘R’ or ‘Revenue’ (what you received money from, AKA income; + technically part of Equity) + • ‘X’ or ‘Expense’ (what you spend money on; technically part of + Equity) + + or, it can be (these are used less often): + + • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the + cashflow report) + • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST + REPORTING).) + + Here is a typical set of account type declarations: + +account assets ; type: A +account liabilities ; type: L +account equity ; type: E +account revenues ; type: R +account expenses ; type: X + +account assets:bank ; type: C +account assets:cash ; type: C + +account equity:conversion ; type: V + + Here are some tips for working with account types. + + • The rules for inferring types from account names are as follows. + These are just a convenience that sometimes help new users get + going; if they don’t work for you, just ignore them and declare + your account types. See also Regular expressions. + + If account's name contains this (CI) regular expression: | its type is: + --------------------------------------------------------------------|------------- + ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash + ^assets?(:|$) | Asset + ^(debts?|liabilit(y|ies))(:|$) | Liability + ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion + ^equity(:|$) | Equity + ^(income|revenue)s?(:|$) | Revenue + ^expenses?(:|$) | Expense + + • If you declare any account types, it’s a good idea to declare an + account for all of the account types, because a mixture of declared + and name-inferred types can disrupt certain reports. + + • Certain uses of account aliases can disrupt account types. See + Rewriting accounts > Aliases and account types. + + • As mentioned above, subaccounts will inherit a type from their + parent account. More precisely, an account’s type is decided by + the first of these that exists: + + 1. A ‘type:’ declaration for this account. + 2. A ‘type:’ declaration in the parent accounts above it, + preferring the nearest. + 3. An account type inferred from this account’s name. + 4. An account type inferred from a parent account’s name, + preferring the nearest parent. + 5. Otherwise, it will have no type. + + • For troubleshooting, you can list accounts and their types with: + + $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] + + +File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal + +10.19 ‘alias’ directive +======================= + +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. This can be useful for: + + • expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + • adapting old journals to your current chart of accounts + • experimenting with new account organisations, like a new hierarchy + • combining two accounts into one, eg to see their sum or difference + on one line + • customising reports + + Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger-web. + + Account aliases are very powerful. They are generally easy to use +correctly, but you can also generate invalid account names with them; +more on this below. + + See also Rewrite account names. + +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Combining aliases:: +* Aliases and multiple files:: +* end aliases directive:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive + +10.19.1 Basic aliases +--------------------- + +To set an account alias, use the ‘alias’ directive in your journal file. +This affects all subsequent journal entries in the current file or its +included files (but note: not sibling or parent files). The spaces +around the = are optional: + +alias OLD = NEW + + Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line. +This affects all entries. It’s useful for trying out aliases +interactively. + + OLD and NEW are case sensitive full account names. hledger will +replace any occurrence of the old account name with the new one. +Subaccounts are also affected. Eg: + +alias checking = assets:bank:wells fargo:checking +; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + +File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive + +10.19.2 Regex aliases +--------------------- + +There is also a more powerful variant that uses a regular expression, +indicated by wrapping the pattern in forward slashes. (This is the only +place where hledger requires forward slashes around a regular +expression.) + + Eg: + +alias /REGEX/ = REPLACEMENT + + or: + +$ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by +REPLACEMENT. REGEX is case-insensitive as usual. + + If you need to match a forward slash, escape it with a backslash, eg +‘/\/=:’. + + If REGEX contains parenthesised match groups, these can be referenced +by the usual backslash and number in REPLACEMENT: + +alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 +; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + REPLACEMENT continues to the end of line (or on command line, to end +of option argument), so it can contain trailing whitespace. + + +File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive + +10.19.3 Combining aliases +------------------------- + +You can define as many aliases as you like, using journal directives +and/or command line options. + + Recursive aliases - where an account name is rewritten by one alias, +then by another alias, and so on - are allowed. Each alias sees the +effect of previously applied aliases. + + In such cases it can be important to understand which aliases will be +applied and in which order. For (each account name in) each journal +entry, we apply: + + 1. ‘alias’ directives preceding the journal entry, most recently + parsed first (ie, reading upward from the journal entry, bottom to + top) + 2. ‘--alias’ options, in the order they appeared on the command line + (left to right). + + In other words, for (an account name in) a given journal entry: + + • the nearest alias declaration before/above the entry is applied + first + • the next alias before/above that will be be applied next, and so on + • aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps +provide semantic stability - aliases will keep working the same way +independent of which files are being read and in which order. + + In case of trouble, adding ‘--debug=6’ to the command line will show +which aliases are being applied when. + + +File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive + +10.19.4 Aliases and multiple files +---------------------------------- + +As explained at Directives and multiple files, ‘alias’ directives do not +affect parent or sibling files. Eg in this command, + +hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn’t work either: + +include a.aliases + +2020-01-01 ; not affected by a.aliases + foo 1 + bar + + This means that account aliases should usually be declared at the +start of your top-most file, like this: + +alias foo=Foo +alias bar=Bar + +2020-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected + + +File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive + +10.19.5 ‘end aliases’ directive +------------------------------- + +You can clear (forget) all currently defined aliases (seen in the +journal so far, or defined on the command line) with this directive: + +end aliases + + +File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive + +10.19.6 Aliases can generate bad account names +---------------------------------------------- + +Be aware that account aliases can produce malformed account names, which +could cause confusing reports or invalid ‘print’ output. For example, +you could erase all account names: + +2021-01-01 + a:aa 1 + b + +$ hledger print --alias '/.*/=' +2021-01-01 + 1 + + The above ‘print’ output is not a valid journal. Or you could insert +an illegal double space, causing ‘print’ output that would give a +different journal when reparsed: + +2021-01-01 + old 1 + other + +$ hledger print --alias old="new USD" | hledger -f- print +2021-01-01 + new USD 1 + other + + +File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive + +10.19.7 Aliases and account types +--------------------------------- + +If an account with a type declaration (see Declaring accounts > Account +types) is renamed by an alias, normally the account type remains in +effect. + + However, renaming in a way that reshapes the account tree (eg +renaming parent accounts but not their children, or vice versa) could +prevent child accounts from inheriting the account type of their +parents. + + Secondly, if an account’s type is being inferred from its name, +renaming it by an alias could prevent or alter that. + + If you are using account aliases and the ‘type:’ query is not +matching accounts as you expect, try troubleshooting with the accounts +command, eg something like: + +$ hledger accounts --alias assets=bassetts type:a + + +File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal + +10.20 ‘commodity’ directive +=========================== + +You can use ‘commodity’ directives to declare your commodities. In fact +the ‘commodity’ directive performs several functions at once: + + 1. It declares commodities which may be used in the journal. This can + optionally be enforced, providing useful error checking. (Cf + Commodity error checking) + + 2. It declares which decimal mark character (period or comma), to + expect when parsing input - useful to disambiguate international + number formats in your data. Without this, hledger will parse both + ‘1,000’ and ‘1.000’ as 1. (Cf Amounts) + + 3. It declares how to render the commodity’s amounts when displaying + output - the decimal mark, any digit group marks, the number of + decimal places, symbol placement and so on. (Cf Commodity display + style) + + You will run into one of the problems solved by commodity directives +sooner or later, so we recommend using them, for robust and predictable +parsing and display. + + Generally you should put them at the top of your journal file (since +for function 2, they affect only following amounts, cf #793). + + A commodity directive is just the word ‘commodity’ followed by a +sample amount, like this: + +;commodity SAMPLEAMOUNT + +commodity $1000.00 +commodity 1,000.0000 AAAA ; optional same-line comment + + It may also be written on multiple lines, and use the ‘format’ +subdirective, as in Ledger. Note in this case the commodity symbol +appears twice; it must be the same in both places: + +;commodity SYMBOL +; format SAMPLEAMOUNT + +; display indian rupees with currency name on the left, +; thousands, lakhs and crores comma-separated, +; period as decimal point, and two decimal places. +commodity INR + format INR 1,00,00,000.00 + + Other indented subdirectives are currently ignored. + + Remember that if the commodity symbol contains spaces, numbers, or +punctuation, it must be enclosed in double quotes (cf Commodity). + + The amount’s quantity does not matter; only the format is +significant. It must include a decimal mark - either a period or a +comma - followed by 0 or more decimal digits. + + A few more examples: + +# number formats for $, EUR, INR and the no-symbol commodity: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.0 +commodity 1 000 000. + + Note hledger normally uses banker’s rounding, so 0.5 displayed with +zero decimal digits is "0". (More at Commodity display style.) + + Even in the presence of commodity directives, the commodity display +style can still be overridden by supplying a command line option. + +* Menu: + +* Commodity error checking:: + + +File: hledger.info, Node: Commodity error checking, Up: commodity directive + +10.20.1 Commodity error checking +-------------------------------- + +In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will +report an error if a commodity symbol is used that has not been declared +by a ‘commodity’ directive. This works similarly to account error +checking, see the notes there for more details. + + Note, this disallows amounts without a commodity symbol, because +currently it’s not possible (?) to declare the "no-symbol" commodity +with a directive. This is one exception for convenience: zero amounts +are always allowed to have no commodity symbol. + + +File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal + +10.21 ‘decimal-mark’ directive +============================== + +You can use a ‘decimal-mark’ directive - usually one per file, at the +top of the file - to declare which character represents a decimal mark +when parsing amounts in this file. It can look like + +decimal-mark . + + or + +decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we +recommend it, especially if the file contains digit group marks (eg +thousands separators). + + +File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal + +10.22 ‘include’ directive +========================= + +You can pull in the content of additional files by writing an include +directive, like this: + +include FILEPATH + + Only journal files can include, and only journal, timeclock or +timedot files can be included (not CSV files, currently). + + If the file path does not begin with a slash, it is relative to the +current file’s folder. + + A tilde means home directory, eg: ‘include ~/main.journal’. + + The path may contain glob patterns to match multiple files, eg: +‘include *.journal’. + + There is limited support for recursive wildcards: ‘**/’ (the slash is +required) matches 0 or more subdirectories. It’s not super convenient +since you have to avoid include cycles and including directories, but +this can be done, eg: ‘include */**/*.journal’. + + The path may also be prefixed to force a specific file format, +overriding the file extension (as described in hledger.1 -> Input +files): ‘include timedot:~/notes/2020*.md’. + + +File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal + +10.23 ‘P’ directive +=================== + +The ‘P’ directive declares a market price, which is a conversion rate +between two commodities on a certain date. This allows value reports to +convert amounts of one commodity to their value in another, on or after +that date. These prices are often obtained from a stock exchange, +cryptocurrency exchange, the or foreign exchange market. + + The format is: + +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the +commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and +quantity) of commodity 2 that one unit of commodity 1 is worth on this +date. Examples: + +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 € $1.35 + +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 € $1.40 + + The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show +amount values in another commodity. See Valuation. + + +File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal + +10.24 ‘payee’ directive +======================= + +‘payee PAYEE NAME’ + + This directive can be used to declare a limited set of payees which +may appear in transaction descriptions. The "payees" check will report +an error if any transaction refers to a payee that has not been +declared. Eg: + +payee Whole Foods + + Any indented subdirectives are currently ignored. + + +File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal + +10.25 ‘tag’ directive +===================== + +‘tag TAGNAME’ + + This directive can be used to declare a limited set of tag names +allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + +tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is +used. It is quite easy to accidentally create a tag through normal use +of colons in comments(#comments]; if you want to prevent this, you can +declare and check your tags . + + +File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal + +10.26 Periodic transactions +=========================== + +The ‘~’ directive declares recurring transactions. Such directives +allow hledger to generate temporary future transactions (visible in +reports, not in the journal file) to help with forecasting or budgeting. + + Periodic transactions can be a little tricky, so before you use them, +read this whole section, or at least these tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + 2. For troubleshooting, show the generated transactions with ‘hledger + print --forecast tag:generated’ or ‘hledger register --forecast + tag:generated’. + 3. Forecasted transactions will begin only after the last + non-forecasted transaction’s date. + 4. Forecasted transactions will end 6 months from today, by default. + See below for the exact start/end rules. + 5. period expressions can be tricky. Their documentation needs + improvement, but is worth studying. + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in ‘weekly from DATE’, DATE + must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give + an error. + 7. Other period expressions with an interval are automatically + expanded to cover a whole number of that interval. (This is done + to improve reports, but it also affects periodic transactions. + Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th + day of month from 2020/01’, which is equivalent to ‘~ every 10th + day of month from 2020/01/01’, will be adjusted to start on + 2019/12/10. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +10.26.1 Periodic rule syntax +---------------------------- + +A periodic transaction rule looks like a normal journal entry, with the +date replaced by a tilde (‘~’) followed by a period expression +(mnemonic: ‘~’ looks like a recurring sine wave.): + +# every first of month +~ monthly + expenses:rent $2000 + assets:bank:checking + +# every 15th of month in 2023's first quarter: +~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying +multi-period reports, just interpreted differently; there, it specifies +report periods; here it specifies recurrence dates (the periods’ start +dates). + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +10.26.2 Periodic rules and relative dates +----------------------------------------- + +Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’, +‘next quarter’) are usually not recommended in periodic rules, since the +results will change as time passes. If used, they will be interpreted +relative to, in order of preference: + + 1. the first day of the default year specified by a recent ‘Y’ + directive + 2. or the date specified with ‘--today’ + 3. or the date on which you are running the report. + + They will not be affected at all by report period or forecast period +dates. + + +File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions + +10.26.3 Two spaces between period expression and description! +------------------------------------------------------------- + +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 + + So, + + • Do write two spaces between your period expression and your + transaction description, if any. + • Don’t accidentally write two spaces in the middle of your period + expression. + + +File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal + +10.27 Other syntax +================== + +hledger journal format supports quite a few other features, mainly to +make interoperating with or converting from Ledger easier. Note some of +the features below are powerful and can be useful in special cases, but +in general, features in this section are considered less important or +even not recommended for most users. Downsides are mentioned to help +you decide if you want to use them. + +* Menu: + +* Auto postings:: +* Balance assignments:: +* Bracketed posting dates:: +* D directive:: +* apply account directive:: +* Y directive:: +* Secondary dates:: +* Star comments:: +* Valuation expressions:: +* Virtual postings:: +* Other Ledger directives:: + + +File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax + +10.27.1 Auto postings +--------------------- + +The ‘=’ directive declares a rule for automatically adding temporary +extra postings (visible in reports, not in the journal file) to all +transactions matched by a certain query, when you use the ‘--auto’ flag. + + Downsides: depending on generated data for your reports makes your +financial data less portable, less future-proof, and less trustworthy in +an audit. Also, because the feature is optional, other features like +balance assertions can break depending on whether it is on or off. + + An auto posting rule looks a bit like a transaction: + += QUERY + ACCOUNT AMOUNT + ... + ACCOUNT [AMOUNT] + + except the first line is an equals sign (mnemonic: ‘=’ suggests +matching), followed by a query (which matches existing postings), and +each "posting" line describes a posting to be generated, and the posting +amounts can be: + + • a normal amount with a commodity symbol, eg ‘$2’. This will be + used as-is. + • a number, eg ‘2’. The commodity symbol (if any) from the matched + posting will be added to this. + • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The + matched posting’s amount (and total price, if any) will be + multiplied by N. + • a multiplier with a commodity symbol, eg ‘*$2’ (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. + + Any query term containing spaces must be enclosed in single or double +quotes, as on the command line. Eg, note the quotes around the second +query term below: + += expenses:groceries 'expenses:dining out' + (budget:funds:dining out) *-1 + + Some examples: + +; every time I buy food, schedule a dollar donation += expenses:food + (liabilities:charity) $-1 + +; when I buy a gift, also deduct that amount from a budget envelope subaccount += expenses:gifts + assets:checking:gifts *-1 + assets:checking *1 + +2017/12/1 + expenses:food $10 + assets:checking + +2017/12/14 + expenses:gifts $20 + assets:checking + +$ hledger print --auto +2017-12-01 + expenses:food $10 + assets:checking + (liabilities:charity) $-1 + +2017-12-14 + expenses:gifts $20 + assets:checking + assets:checking:gifts -$20 + assets:checking $20 + +* Menu: + +* Auto postings and multiple files:: +* Auto postings and dates:: +* Auto postings and transaction balancing / inferred amounts / balance assertions:: +* Auto posting tags:: + + +File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings + +10.27.1.1 Auto postings and multiple files +.......................................... + +An auto posting rule can affect any transaction in the current file, or +in any parent file or child file. Note, currently it will not affect +sibling files (when multiple ‘-f’/‘--file’ are used - see #1212). + + +File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings + +10.27.1.2 Auto postings and dates +................................. + +A posting date (or secondary date) in the matched posting, or (taking +precedence) a posting date in the auto posting rule itself, will also be +used in the generated posting. + + +File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings + +10.27.1.3 Auto postings and transaction balancing / inferred +............................................................ + +amounts / balance assertions Currently, 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. + + This also means that you cannot have more than one auto-posting with +a missing amount applied to a given transaction, as it will be unable to +infer amounts. + + +File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings + +10.27.1.4 Auto posting tags +........................... + +Automated postings will have some extra tags: + + • ‘generated-posting:= QUERY’ - shows this was generated by an auto + posting rule, and the query + • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear + in hledger’s output. This can be used to match postings generated + "just now", rather than generated in the past and saved to the + journal. + + Also, any transaction that has been changed by auto posting rules +will have these tags added: + + • ‘modified:’ - this transaction was modified + • ‘_modified:’ - a hidden tag not appearing in the comment; this + transaction was modified "just now". + + +File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax + +10.27.2 Balance assignments +--------------------------- + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account’s balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). + + Downsides: using balance assignments makes your journal less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. Also balance +assignments’ forcing of balances can hide errors. These things make +your financial data less portable, less future-proof, and less +trustworthy in an audit. + +* Menu: + +* Balance assignments and prices:: + + +File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments + +10.27.2.1 Balance assignments and prices +........................................ + +A cost 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.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax + +10.27.3 Bracketed posting dates +------------------------------- + +For setting posting dates and secondary posting dates, Ledger’s +bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or +‘[=DATE2]’ in posting comments. hledger will attempt to parse any +square-bracketed sequence of the ‘0123456789/-.=’ characters in this +way. With this syntax, DATE infers its year from the transaction and +DATE2 infers its year from DATE. + + Downsides: another syntax to learn, redundant with hledger’s +‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date +syntax. + + +File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax + +10.27.4 ‘D’ directive +--------------------- + +‘D AMOUNT’ + + This directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. This effect lasts until the next ‘D’ directive, or the end +of the journal. + + For compatibility/historical reasons, ‘D’ also acts like a +‘commodity’ directive (setting the commodity’s decimal mark for parsing +and display style for output). So its argument is not just a commodity +symbol, but a full amount demonstrating the style. The amount must +include a decimal mark (either period or comma). Eg: + +; commodity-less amounts should be treated as dollars +; (and displayed with the dollar sign on the left, thousands separators and two decimal places) +D $1,000.00 + +1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity’s display style, a ‘commodity’ directive has +highest priority, then a ‘D’ directive. + + For detecting a commodity’s decimal mark during parsing, +‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’. + + For checking commodity symbols with the check command, a ‘commodity’ +directive is required (‘hledger check commodities’ ignores ‘D’ +directives). + + Downsides: omitting commodity symbols makes your financial data less +explicit, less portable, and less trustworthy in an audit. It is +usually an unsustainable shortcut; sooner or later you will want to +track multiple commodities. D is overloaded with functions redundant +with ‘commodity’ and ‘decimal-mark’. And it works differently from +Ledger’s ‘D’. + + +File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax + +10.27.5 ‘apply account’ directive +--------------------------------- + +This directive sets a default parent account, which will be prepended to +all accounts in following entries, until an ‘end apply account’ +directive or end of current file. Eg: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + ‘account’ directives are also affected, and so is any ‘include’d +content. + + Account names entered via hledger add or hledger-web are not +affected. + + Account aliases, if any, are applied after the parent account is +prepended. + + Downsides: this can make your financial data less explicit, less +portable, and less trustworthy in an audit. + + +File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax + +10.27.6 ‘Y’ directive +--------------------- + +‘Y YEAR’ + + or (deprecated backward-compatible forms): + + ‘year YEAR’ ‘apply year YEAR’ + + The space is optional. This sets a default year to be used for +subsequent dates which don’t specify a year. Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +year 2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at +least) makes your financial data less explicit, less portable, and less +trustworthy in an audit. Such dates can get separated from their +corresponding Y directive, eg when evaluating a region of the journal in +your editor. A missing Y directive makes reports dependent on today’s +date. + + +File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax + +10.27.7 Secondary dates +----------------------- + +A secondary date is written after the primary date, following an equals +sign. If the year is omitted, the primary date’s year is assumed. When +running reports, the primary (left) date is used by default, but with +the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary +(right) date will be used instead. + + The meaning of secondary dates is up to you, but it’s best to follow +a consistent rule. Eg "primary = the bank’s clearing date, secondary = +date the transaction was initiated, if different". + + Downsides: makes your financial data more complicated, less portable, +and less trustworthy in an audit. Keeping the meaning of the two dates +consistent requires discipline, and you have to remember which reporting +mode is appropriate for a given report. Posting dates are simpler and +better. + + +File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax + +10.27.8 Star comments +--------------------- + +Lines beginning with ‘*’ (star/asterisk) are also comment lines. This +feature allows Emacs users to insert org headings in their journal, +allowing them to fold/unfold/navigate it like an outline when viewed +with org mode. + + Downsides: another, unconventional comment syntax to learn. +Decreases your journal’s portability. And switching to Emacs org mode +just for folding/unfolding meant losing the benefits of ledger mode; +nowadays you can add outshine mode to ledger mode to get folding without +losing ledger mode’s features. + + +File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax + +10.27.9 Valuation expressions +----------------------------- + +Ledger allows a valuation function or value to be written in double +parentheses after an amount. hledger ignores these. + + +File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax + +10.27.10 Virtual postings +------------------------- + +A posting with parentheses around the account name is called a _virtual +posting_ or _unbalanced posting_, which means it is exempt from the +usual rule that a transaction’s postings must balance add up to zero. + + This is not part of double entry bookkeeping, so you might choose to +avoid this feature. Or you can use it sparingly for certain special +cases where it can be convenient. Eg, you could set opening balances +without using a balancing equity account: + +2022-01-01 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with brackets around the account name is called a _balanced +virtual posting_. The balanced virtual postings in a transaction must +add up to zero (separately from other postings). Eg: + +2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Postings whose account names are neither parenthesised nor bracketed +are called _real postings_. You can exclude virtual postings from +reports with the ‘-R/--real’ flag or a ‘real:1’ query. + + Downsides: violates double entry bookkeeping, can be used to avoid +figuring out correct entries, makes your financial data less portable +and less trustworthy in an audit. + + +File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax + +10.27.11 Other Ledger directives +-------------------------------- + +These other Ledger directives are currently accepted but ignored. This +allows hledger to read more Ledger files, but be aware that hledger’s +reports may differ from Ledger’s if you use these. + +apply fixed COMM AMT +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR +end apply fixed +end apply tag +end apply year +end tag +eval / expr EXPR +python + PYTHONCODE +tag NAME +value EXPR +--command-line-flags + + See also https://hledger.org/ledger.html for a detailed +hledger/Ledger syntax comparison. + + +File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top + +11 CSV +****** + +hledger can read CSV files (Character Separated Value - usually comma, +semicolon, or tab) containing dated records, automatically converting +each record into a transaction. + + (To learn about _writing_ CSV, see CSV output.) + + For best error messages when reading CSV/TSV/SSV files, make sure +they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use +a hledger file prefix (see File Extension below). + + Each CSV file must be described by a corresponding _rules file_. +This contains rules describing the CSV data (header line, fields layout, +date format etc.), how to construct hledger transactions from it, and +how to categorise transactions based on description or other attributes. + + By default hledger looks for a rules file named like the CSV file +with an extra ‘.rules’ extension, in the same directory. Eg when asked +to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can +specify a different rules file with the ‘--rules-file’ option. If no +rules file is found, hledger will create a sample rules file, which +you’ll need to adjust. + + At minimum, the rules file must identify the date and amount fields, +and often it also specifies the date format and how many header lines +there are. Here’s a simple CSV file and a rules file for it: + +Date, Description, Id, Amount +12/11/2019, Foo, 123, 10.23 + +# basic.csv.rules +skip 1 +fields date, description, , amount +date-format %d/%m/%Y + +$ hledger print -f basic.csv +2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There’s an introductory Importing CSV data tutorial on hledger.org, +and more CSV rules examples below, and a larger collection at +https://github.com/simonmichael/hledger/tree/master/examples/csv. + +* Menu: + +* CSV rules cheatsheet:: +* separator:: +* skip:: +* date-format:: +* timezone:: +* newest-first:: +* intra-day-reversed:: +* decimal-mark:: +* fields list:: +* Field assignment:: +* Field names:: +* if block:: +* Matchers:: +* if table:: +* balance-type:: +* include:: +* Working with CSV:: +* CSV rules examples:: + + +File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV + +11.1 CSV rules cheatsheet +========================= + +The following kinds of rule can appear in the rules file, in any order. +(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.) + +*‘separator’* declare the field separator, instead of + relying on file extension +*‘skip’* skip one or more header lines at start of file +*‘date-format’* declare how to parse CSV dates/date-times +*‘timezone’* declare the time zone of ambiguous CSV + date-times +*‘newest-first’* improve txn order when: there are multiple + records, newest first, all with the same date +*‘intra-day-reversed’* improve txn order when: same-day txns are in + opposite order to the overall file +*‘decimal-mark’* declare the decimal mark used in CSV amounts, + when ambiguous +*‘fields’ list* name CSV fields for easy reference, and + optionally assign their values to hledger + fields +*Field assignment* assign a CSV value or interpolated text value + to a hledger field +*‘if’ block* conditionally assign values to hledger fields, + or ‘skip’ a record or ‘end’ (skip rest of + file) +*‘if’ table* conditionally assign values to hledger fields, + using compact syntax +*‘balance-type’* select which type of balance + assertions/assignments to generate +*‘include’* inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are +evaluated. + + +File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV + +11.2 ‘separator’ +================ + +You can use the ‘separator’ rule to read other kinds of +character-separated data. The argument is any single separator +character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for +comma-separated values (CSV): + +separator , + + or for semicolon-separated values (SSV): + +separator ; + + or for tab-separated values (TSV): + +separator TAB + + If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a +‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be +inferred automatically, and you won’t need this rule. + + +File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV + +11.3 ‘skip’ +=========== + +skip N + + The word ‘skip’ followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines at the start of the input +data. (Empty/blank lines are skipped automatically, so you don’t need +to count those.) You’ll need this whenever your CSV data contains +header lines. Header lines skipped in this way are ignored, and not +parsed as CSV. + + ‘skip’ can also be used inside if blocks (described below), to skip +individual data records. Note records skipped in this way are still +required to be valid CSV, even though otherwise ignored. + + +File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV + +11.4 ‘date-format’ +================== + +date-format DATEFMT + + This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV +dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, +you’ll need to add a date-format rule describing them with a +strptime-style date parsing pattern - see +https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. +The pattern must parse the CSV date value completely. Some examples: + +# MM/DD/YY +date-format %m/%d/%y + +# D/M/YYYY +# The - makes leading zeros optional. +date-format %-d/%-m/%Y + +# YYYY-Mmm-DD +date-format %Y-%h-%d + +# M/D/YYYY HH:MM AM some other junk +# Note the time and junk must be fully parsed, though only the date is used. +date-format %-m/%-d/%Y %l:%M %p some other junk + + +File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV + +11.5 ‘timezone’ +=============== + +timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone +other than yours, but containing no explicit time zone information, you +can use this rule to declare the CSV’s native time zone, which helps +prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don’t +need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’, +‘%Ez’; see the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware +conversion, localising the CSV date-times to your current system time +zone. If you prefer to localise to some other time zone, eg for +reproducibility, you can (on unix at least) set the output timezone with +the TZ environment variable, eg: + +$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + ‘timezone’ currently does not understand timezone names, except +"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". +For others, use numeric format: +HHMM or -HHMM. + + +File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV + +11.6 ‘newest-first’ +=================== + +hledger tries to ensure that the generated transactions will be ordered +chronologically, including intra-day transactions. Usually it can +auto-detect how the CSV records are ordered. But if it encounters CSV +where all records are on the same date, it assumes that the records are +oldest first. If in fact the CSV’s records are normally newest first, +like: + +2022-10-01, txn 3... +2022-10-01, txn 2... +2022-10-01, txn 1... + + you can add the ‘newest-first’ rule to help hledger generate the +transactions in correct order. + +# same-day CSV records are newest first +newest-first + + +File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV + +11.7 ‘intra-day-reversed’ +========================= + +CSV records for each day are sometimes ordered in reverse compared to +the overall date order. Eg, here dates are newest first, but the +transactions on each date are oldest first: + +2022-10-02, txn 3... +2022-10-02, txn 4... +2022-10-01, txn 1... +2022-10-01, txn 2... + + In this situation, add the ‘intra-day-reversed’ rule, and hledger +will compensate, improving the order of transactions. + +# transactions within each day are reversed with respect to the overall date order +intra-day-reversed + + +File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV + +11.8 ‘decimal-mark’ +=================== + +decimal-mark . + + or: + +decimal-mark , + + hledger automatically accepts either period or comma as a decimal +mark when parsing numbers (cf Amounts). However if any numbers in the +CSV contain digit group marks, such as thousand-separating commas, you +should declare the decimal mark explicitly with this rule, to avoid +misparsed numbers. + + +File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV + +11.9 ‘fields’ list +================== + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word ‘fields’ followed by comma-separated field +names) is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say + ‘%SomeField’ instead of remembering ‘%13’. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger’s fields and + build a transaction. + + Here’s an example that says "use the 1st, 2nd and 4th fields as the +transaction’s date, description and amount; name the last two fields for +later reference; and ignore the others": + +fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to +the CSV file’s separator. Also: + + • There must be least two items in the list (at least one comma). + • Field names may not contain spaces. Spaces before/after field + names are optional. + • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen). + • Fields you don’t care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it’s convenient to use these for +your field names, suitably modified (eg lower-cased with spaces replaced +by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning +to a hledger field with the same name. Eg you could call the CSV’s +"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’ +field (and generating a balance assertion). + + +File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV + +11.10 Field assignment +====================== + +HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to +hledger fields. They can be used instead of or in addition to a fields +list (see above). + + To assign a value to a hledger field, write the field name (any of +the standard hledger field/pseudo-field names, defined below), a space, +followed by a text value on the same line. This text value may +interpolate CSV fields, referenced by their 1-based position in the CSV +record (‘%N’), or by the name they were given in the fields list +(‘%CSVFIELD’). + + Some examples: + +# set the amount to the 4th CSV field, with " USD" appended +amount %4 USD + +# combine three fields to make a comment, containing note: and date: tags +comment note: %somefield - %anotherfield, date: %1 + + Tips: + + • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’ + becomes ‘1’ when interpolated) (#1051). + • Interpolations always refer to a CSV field - you can’t interpolate + a hledger field. (See Referencing other fields below). + + +File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV + +11.11 Field names +================= + +Note the two kinds of field names mentioned here, and used only in +hledger CSV rules files: + + 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally + name the CSV columns for easy reference (since hledger doesn’t yet + automatically recognise column headings in a CSV file), by writing + arbitrary names in a ‘fields’ list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you + must set at least some of these to generate the hledger transaction + from a CSV record, by writing them as the left hand side of a field + assignment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a ‘fields’ list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what +happens when you assign values to them: + +* Menu: + +* date field:: +* date2 field:: +* status field:: +* code field:: +* description field:: +* comment field:: +* account field:: +* amount field:: +* currency field:: +* balance field:: + + +File: hledger.info, Node: date field, Next: date2 field, Up: Field names + +11.11.1 date field +------------------ + +Assigning to ‘date’ sets the transaction date. + + +File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names + +11.11.2 date2 field +------------------- + +‘date2’ sets the transaction’s secondary date, if any. + + +File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names + +11.11.3 status field +-------------------- + +‘status’ sets the transaction’s status, if any. + + +File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names + +11.11.4 code field +------------------ + +‘code’ sets the transaction’s code, if any. + + +File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names + +11.11.5 description field +------------------------- + +‘description’ sets the transaction’s description, if any. + + +File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names + +11.11.6 comment field +--------------------- + +‘comment’ sets the transaction’s comment, if any. + + ‘commentN’, where N is a number, sets the Nth posting’s comment. + + You can assign multi-line comments by writing literal ‘\n’ in the +code. A comment starting with ‘\n’ will begin on a new line. + + Comments can contain tags, as usual. + + +File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names + +11.11.7 account field +--------------------- + +Assigning to ‘accountN’, where N is 1 to 99, sets the account name of +the Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you’ll want to set ‘account1’ +and ‘account2’. Typically ‘account1’ is associated with the CSV file, +and is set once with a top-level assignment, while ‘account2’ is set +based on each transaction’s description, in conditional rules. + + If a posting’s account name is left unset but its amount is set (see +below), a default account name will be chosen (like "expenses:unknown" +or "income:unknown"). + + +File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names + +11.11.8 amount field +-------------------- + +There are several "amount" field name variants, useful for different +situations: + + • ‘amountN’ sets the amount of the Nth posting, and causes that + posting to be generated. By assigning to ‘amount1’, ‘amount2’, ... + etc. you can generate up to 99 postings. Posting numbers don’t + have to be consecutive; in certain situations using a high number + might be helpful to influence the layout of postings. + + • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair, + when and only when the amount must be obtained from two CSV fields. + Eg when the CSV has separate Debit and Credit fields instead of a + single Amount field. Note: + + • Don’t think "-in is for the first posting and -out is for the + second posting" - that’s not correct. Think: "‘amountN-in’ + and ‘amountN-out’ together detect the amount for posting N, by + inspecting two CSV fields at once." + • hledger assumes both CSV fields are unsigned, and will + automatically negate the -out value. + • It also expects that at least one of the values is empty or + zero, so it knows which one to ignore. If that’s not the case + you’ll need an if rule (see Setting amounts below). + + • ‘amount’, with no posting number (and similarly, ‘amount-in’ and + ‘amount-out’ with no number) are an older syntax. We keep them for + backwards compatibility, and because they have special behaviour + that is sometimes convenient: + + • They set the amount of posting 1 and (negated) the amount of + posting 2. + • Posting 2’s amount will be converted to cost if it has a cost + price. + • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or + ‘amount2-in’ and ‘amount2-out’) will take precedence. This + allows incrementally migrating old rules files to the new + syntax. + + There’s more to say about amount-setting that doesn’t fit here; +please see also "Setting amounts" below. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +11.11.9 currency field +---------------------- + +‘currency’ sets a currency symbol, to be prepended to all postings’ +amounts. You can use this if the CSV amounts do not have a currency +symbol, eg if it is in a separate column. + + ‘currencyN’ prepends a currency symbol to just the Nth posting’s +amount. + + +File: hledger.info, Node: balance field, Prev: currency field, Up: Field names + +11.11.10 balance field +---------------------- + +‘balanceN’ sets a balance assertion amount (or if the posting amount is +left empty, a balance assignment) on posting N. + + ‘balance’ is a compatibility spelling for hledger <1.17; it is +equivalent to ‘balance1’. + + You can adjust the type of assertion/assignment with the +‘balance-type’ rule (see below). + + See Tips below for more about setting amounts and currency. + + +File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV + +11.12 ‘if’ block +================ + +Rules can be applied conditionally, depending on patterns in the CSV +data. This allows flexibility; in particular, it is how you can +categorise transactions, selecting an appropriate account name based on +their description (for example). There are two ways to write +conditional rules: "if blocks", described here, and "if tables", +described below. + + An if block is the word ‘if’ and one or more "matcher" expressions +(can be a word or phrase), one per line, starting either on the same or +next line; followed by one or more indented rules. Eg, + +if MATCHER + RULE + + or + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be +applied. They are usually field assignments, but the following special +rules may also be used within an if block: + + • ‘skip’ - skips the matched CSV record (generating no transaction + from it) + • ‘end’ - skips the rest of the current CSV file. + + Some examples: + +# if the record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the record contains any of these phrases, set account2 and a transaction comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + +# if an empty record is seen (assuming five fields), ignore the rest of the CSV file +if ,,,, + end + + +File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV + +11.13 Matchers +============== + +There are two kinds: + + 1. A record matcher is a word or single-line text fragment or regular + expression (‘REGEX’), which hledger will try to match + case-insensitively anywhere within the CSV record. + Eg: ‘whole foods’ + + 2. A field matcher is preceded with a percent sign and CSV field name + (‘%CSVFIELD REGEX’). hledger will try to match these just within + the named CSV field. + Eg: ‘%date 2023’ + + The regular expression is (as usual in hledger) a POSIX extended +regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’, +‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular +expressions" in the hledger manual +(https://hledger.org/hledger.html#regular-expressions). + + With record matchers, it’s important to know that the record matched +is not the original CSV record, but a modified one: separators will be +converted to commas, and enclosing double quotes (but not enclosing +whitespace) are removed. So for example, when reading an SSV file, if +the original record was: + +2020-01-01; "Acme, Inc."; 1,000 + + the regex would see, and try to match, this modified record text: + +2020-01-01,Acme, Inc., 1,000 + + When an if block has multiple matchers, they are combined as follows: + + • By default they are OR’d (any one of them can match) + • When a matcher is preceded by ampersand (‘&’) it will be AND’ed + with the previous matcher (both of them must match). + + There’s not yet an easy syntax to negate a matcher. + + +File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV + +11.14 ‘if’ table +================ + +"if tables" are an alternative to if blocks; they can express many +matchers and field assignments in a more compact tabular format, like +this: + +if,HLEDGERFIELD1,HLEDGERFIELD2,... +MATCHERA,VALUE1,VALUE2,... +MATCHERB,VALUE1,VALUE2,... +MATCHERC,VALUE1,VALUE2,... + + + The first character after ‘if’ is taken to be the separator for the +rest of the table. It should be a non-alphanumeric character like ‘,’ +or ‘|’ that does not appear anywhere else in the table. (Note: it is +unrelated to the CSV file’s separator.) Whitespace can be used in the +matcher lines for readability, but not in the if line currently. The +table must be terminated by an empty line (or end of file). Each line +must contain the same number of separators; empty values are allowed. + + The above means: try all of the matchers; whenever a matcher +succeeds, assign all of the values on that line to the corresponding +hledger fields; later lines can overrider earlier ones. It is +equivalent to this sequence of if blocks: + +if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERB + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + +if,account2,comment +atm transaction fee,expenses:business:banking,deductible? check it +%description groceries,expenses:groceries, +2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + +File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV + +11.15 ‘balance-type’ +==================== + +Balance assertions generated by assigning to balanceN are of the simple +‘=’ type by default, which is a single-commodity, subaccount-excluding +assertion. You may find the subaccount-including variants more useful, +eg if you have created some virtual subaccounts of checking to help with +budgeting. You can select a different type of assertion with the +‘balance-type’ rule: + +# balance assertions will consider all commodities and all subaccounts +balance-type ==* + + Here are the balance assertion types for quick reference: + += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts + + +File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV + +11.16 ‘include’ +=============== + +include RULESFILE + + This includes the contents of another CSV rules file at this point. +‘RULESFILE’ is an absolute file path or a path relative to the current +file’s directory. This can be useful for sharing common rules between +several rules files, eg: + +# someaccount.csv.rules + +## someaccount-specific rules +fields date,description,amount +account1 assets:someaccount +account2 expenses:misc + +## common rules +include categorisation.rules + + +File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV + +11.17 Working with CSV +====================== + +Some tips: + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading CSV from standard input:: +* Reading multiple CSV files:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Amount signs:: +* Setting currency/commodity:: +* Amount decimal places:: +* Referencing other fields:: +* How CSV rules are evaluated:: +* Well factored rules:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV + +11.17.1 Rapid feedback +---------------------- + +It’s a good idea to get rapid feedback while creating/troubleshooting +CSV rules. Here’s a good way, using entr from eradman.com/entrproject: + +$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions +of interest. "bash -c" is used to run multiple commands, so we can echo +a separator each time the command re-runs, making it easier to read the +output. + + +File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV + +11.17.2 Valid CSV +----------------- + +Note that hledger will only accept valid CSV conforming to RFC 4180, and +equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab +as separators). This means, eg: + + • Values may be enclosed in double quotes, or not. Enclosing in + single quotes is not allowed. (Eg ‘'A','B'’ is rejected.) + • When values are enclosed in double quotes, spaces outside the + quotes are not allowed. (Eg ‘"A", "B"’ is rejected.) + • When values are not enclosed in quotes, they may not contain double + quotes. (Eg ‘A"A, B’ is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you’ll need to +transform it before reading with hledger. Try using sed, or a more +permissive CSV parser like python’s csv lib. + + +File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV + +11.17.3 File Extension +---------------------- + +To help hledger choose the CSV file reader and show the right error +messages (and choose the right field separator character by default), +it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’ +filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV +reader (and the default field separator) by prefixing the file path with +‘csv:’, ‘ssv:’ or ‘tsv:’: Eg: + +$ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator +rule if needed. + + +File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV + +11.17.4 Reading CSV from standard input +--------------------------------------- + +You’ll need the file format prefix when reading CSV from stdin also, +since hledger assumes journal format by default. Eg: + +$ cat foo.dat | hledger -f ssv:- print + + +File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV + +11.17.5 Reading multiple CSV files +---------------------------------- + +If you use multiple ‘-f’ options to read multiple CSV files at once, +hledger will look for a correspondingly-named rules file for each CSV +file. But if you use the ‘--rules-file’ option, that rules file will be +used for all the CSV files. + + +File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV + +11.17.6 Valid transactions +-------------------------- + +After reading a CSV file, hledger post-processes and validates the +generated journal entries as it would for a journal file - balancing +them, applying balance assignments, and canonicalising amount styles. +Any errors at this stage will be reported in the usual way, displaying +the problem entry. + + There is one exception: balance assertions, if you have generated +them, will not be checked, since normally these will work only when the +CSV data is part of the main journal. If you do need to check balance +assertions generated from CSV right away, pipe into another hledger: + +$ hledger -f file.csv print | hledger -f- print + + +File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV + +11.17.7 Deduplicating, importing +-------------------------------- + +When you download a CSV file periodically, eg to get your latest bank +transactions, the new file may overlap with the old one, containing some +of the same records. + + The import command will (a) detect the new transactions, and (b) +append just those transactions to your main journal. It is idempotent, +so you don’t have to remember how many times you ran it or with which +version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’ +file.) This is the easiest way to import CSV data. Eg: + +# download the latest CSV files, then run this command. +# Note, no -f flags needed here. +$ hledger import *.csv [--dry] + + This method works for most CSV files. (Where records have a stable +chronological order, and new records appear only at the new end.) + + A number of other tools and workflows, hledger-specific and +otherwise, exist for converting, deduplicating, classifying and managing +CSV data. See: + + • https://hledger.org/cookbook.html#setups-and-workflows + • https://plaintextaccounting.org -> data import/conversion + + +File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV + +11.17.8 Setting amounts +----------------------- + +Continuing from amount field above, here are more tips on handling +various amount-setting situations: + + 1. *If the amount is in a single CSV field:* + + a. *If its sign indicates direction of flow:* + Assign it to ‘amountN’, to set the Nth posting’s amount. N is + usually 1 or 2 but can go up to 99. + + b. *If another field indicates direction of flow:* + Use one or more conditional rules to set the appropriate + amount sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. *If the amount is in one of two CSV fields (eg Debit and Credit):* + + a. *If both fields are unsigned:* + Assign the fields to ‘amountN-in’ and ‘amountN-out’. This + sets posting N’s amount to whichever of these has a non-zero + value. If it’s the -out value, the amount will be negated. + + b. *If either field is signed:* + Use a conditional rule to flip the sign when needed. Eg + below, the -out value already has a minus sign so we undo + hledger’s automatic negating by negating once more (but only + if the field is non-empty, so that we don’t leave a minus sign + by itself): + + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields can contain a non-zero value (or both can be + empty):* + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such + as ‘1’ and ‘none’. For such cases, use conditional rules to + help select the amount. Eg, to handle the above you could + select the value containing non-zero digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. *If you want posting 2’s amount converted to cost:* + Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’) + syntax. + + 4. *If the CSV has only balance amounts, not transaction amounts:* + Assign to ‘balanceN’, to set a balance assignment on the Nth + posting, causing the posting’s amount to be calculated + automatically. ‘balance’ with no number is equivalent to + ‘balance1’. In this situation hledger is more likely to guess the + wrong default account name, so you may need to set that explicitly. + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV + +11.17.9 Amount signs +-------------------- + +There is some special handling for amount signs, to simplify parsing and +sign-flipping: + + • *If an amount value begins with a plus sign:* + that will be removed: ‘+AMT’ becomes ‘AMT’ + + • *If an amount value is parenthesised:* + it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes + ‘-AMT’ + + • *If an amount value has two minus signs (or two sets of + parentheses, or a minus sign and parentheses):* + they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes + ‘AMT’ + + • *If an amount value contains just a sign (or just a set of + parentheses):* + that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or + ‘"()"’ becomes ‘""’. + + +File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV + +11.17.10 Setting currency/commodity +----------------------------------- + +If the currency/commodity symbol is included in the CSV’s amount +field(s): + +2020-01-01,foo,$123.00 + + you don’t have to do anything special for the commodity symbol, it +will be assigned as part of the amount. Eg: + +fields date,description,amount + +2020-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + +2020-01-01,foo,USD,123.00 + + You can assign that to the ‘currency’ pseudo-field, which has the +special effect of prepending itself to every amount in the transaction +(on the left, with no separating space): + +fields date,description,currency,amount + +2020-01-01 foo + expenses:unknown USD123.00 + income:unknown USD-123.00 + + Or, you can use a field assignment to construct the amount yourself, +with more control. Eg to put the symbol on the right, and separated by +a space: + +fields date,description,cur,amt +amount %amt %cur + +2020-01-01 foo + expenses:unknown 123.00 USD + income:unknown -123.00 USD + + Note we used a temporary field name (‘cur’) that is not ‘currency’ - +that would trigger the prepending effect, which we don’t want here. + + +File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV + +11.17.11 Amount decimal places +------------------------------ + +Like amounts in a journal file, the amounts generated by CSV rules like +‘amount1’ influence commodity display styles, such as the number of +decimal places displayed in reports. + + The original amounts as written in the CSV file do not affect display +style (because we don’t yet reliably know their commodity). + + +File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV + +11.17.12 Referencing other fields +--------------------------------- + +In field assignments, you can interpolate only CSV fields, not hledger +fields. In the example below, there’s both a CSV field and a hledger +field named amount1, but %amount1 always means the CSV field, not the +hledger field: + +# Name the third CSV field "amount1" +fields date,description,amount1 + +# Set hledger's amount1 to the CSV amount1 field followed by USD +amount1 %amount1 USD + +# Set comment to the CSV amount1 (not the amount1 assigned above) +comment %amount1 + + Here, since there’s no CSV amount1 field, %amount1 will produce a +literal "amount1": + +fields date,description,csvamount +amount1 %csvamount USD +# Can't interpolate amount1 here +comment %amount1 + + When there are multiple field assignments to the same hledger field, +only the last one takes effect. Here, comment’s value will be be B, or +C if "something" is matched, but never A: + +comment A +comment B +if something + comment C + + +File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV + +11.17.13 How CSV rules are evaluated +------------------------------------ + +Here’s how to think of CSV rules being evaluated (if you really need +to). First, + + • ‘include’ - all includes are inlined, from top to bottom, depth + first. (At each include point the file is inlined and scanned for + further includes, recursively, before proceeding.) + + Then "global" rules are evaluated, top to bottom. If a rule is +repeated, the last one wins: + + • ‘skip’ (at top level) + • ‘date-format’ + • ‘newest-first’ + • ‘fields’ - names the CSV fields, optionally sets up initial + assignments to hledger fields + + Then for each CSV record in turn: + + • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip + all remaining CSV records. Otherwise if any of them contain a + ‘skip’ rule, skip that many CSV records. If there are multiple + matched ‘skip’ rules, the first one wins. + • collect all field assignments at top level and in matched ‘if’ + blocks. When there are multiple assignments for a field, keep only + the last one. + • compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELD references), or a + default + • generate a hledger transaction (journal entry) from these values. + + This is all part of the CSV reader, one of several readers hledger +can use to parse input files. When all files have been read +successfully, the transactions are passed as input to whichever hledger +command the user specified. + + +File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV + +11.17.14 Well factored rules +---------------------------- + +Some things than can help reduce duplication and complexity in rules +files: + + • Extracting common rules usable with multiple CSV files into a + ‘common.rules’, and adding ‘include common.rules’ to each CSV’s + rules file. + + • Splitting if blocks into smaller if blocks, extracting the + frequently used parts. + + +File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV + +11.18 CSV rules examples +======================== + +* Menu: + +* Bank of Ireland:: +* Coinbase:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples + +11.18.1 Bank of Ireland +----------------------- + +Here’s a CSV with two amount fields (Debit and Credit), and a balance +field, which we can use to add balance assertions, which is not +necessary but provides extra error checking: + +Date,Details,Debit,Credit,Balance +07/12/2012,LODGMENT 529898,,10.0,131.21 +07/12/2012,PAYMENT,5,,126 + +# bankofireland-checking.csv.rules + +# skip the header line +skip + +# name the csv fields, and assign some of them as journal entry fields +fields date, description, amount-out, amount-in, balance + +# We generate balance assertions by assigning to "balance" +# above, but you may sometimes need to remove these because: +# +# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience +# +# - it is sometimes calculated based on non-chronological ordering, +# eg when multiple transactions clear on the same day + +# date is in UK/Ireland format +date-format %d/%m/%Y + +# set the currency +currency EUR + +# set the base account for all txns +account1 assets:bank:boi:checking + +$ hledger -f bankofireland-checking.csv print +2012-12-07 LODGMENT 529898 + assets:bank:boi:checking EUR10.0 = EUR131.2 + income:unknown EUR-10.0 + +2012-12-07 PAYMENT + assets:bank:boi:checking EUR-5.0 = EUR126.0 + expenses:unknown EUR5.0 + + The balance assertions don’t raise an error above, because we’re +reading directly from CSV, but they will be checked if these entries are +imported into a journal file. + + +File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples + +11.18.2 Coinbase +---------------- + +A simple example with some CSV from Coinbase. The spot price is +recorded using cost notation. The legacy ‘amount’ field name +conveniently sets amount 2 (posting 2’s amount) to the total cost. + +# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes +# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + +# coinbase.csv.rules +skip 1 +fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes +date %Timestamp +date-format %Y-%m-%dT%T%Z +description %Notes +account1 assets:coinbase:cc +amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + +$ hledger print -f coinbase.csv +2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + +File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples + +11.18.3 Amazon +-------------- + +Here we convert amazon.com order history, and use an if block to +generate a third posting if there’s a fee. (In practice you’d probably +get this data from your bank instead, but it’s an example.) + +"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" +"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" +"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" + +# amazon-orders.csv.rules + +# skip one header line +skip 1 + +# name the csv fields, and assign the transaction's date, amount and code. +# Avoided the "status" and "amount" hledger field names to prevent confusion. +fields date, _, toorfrom, name, amzstatus, amzamount, fees, code + +# how to parse the date +date-format %b %-d, %Y + +# combine two fields to make the description +description %toorfrom %name + +# save the status as a tag +comment status:%amzstatus + +# set the base account for all transactions +account1 assets:amazon +# leave amount1 blank so it can balance the other(s). +# I'm assuming amzamount excludes the fees, don't remember + +# set a generic account2 +account2 expenses:misc +amount2 %amzamount +# and maybe refine it further: +#include categorisation.rules + +# add a third posting for fees, but only if they are non-zero. +if %fees [1-9] + account3 expenses:fees + amount3 %fees + +$ hledger -f amazon-orders.csv print +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed + assets:amazon + expenses:misc $20.00 + +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed + assets:amazon + expenses:misc $25.00 + expenses:fees $1.00 + + +File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples + +11.18.4 Paypal +-------------- + +Here’s a real-world rules file for (customised) Paypal CSV, with some +Paypal-specific rules, and a second rules file included: + +"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" +"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" +"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" +"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" +"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" +"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" +"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" +"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" + +# paypal-custom.csv.rules + +# Tips: +# Export from Activity -> Statements -> Custom -> Activity download +# Suggested transaction type: "Balance affecting" +# Paypal's default fields in 2018 were: +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" +# This rules file assumes the following more detailed fields, configured in "Customize report fields": +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" + +fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note + +skip 1 + +date-format %-m/%-d/%Y + +# ignore some paypal events +if +In Progress +Temporary Hold +Update to + skip + +# add more fields to the description +description %description_ %itemtitle + +# save some other fields as tags +comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ + +# convert to short currency symbols +if %currency USD + currency $ +if %currency EUR + currency E +if %currency GBP + currency P + +# generate postings + +# the first posting will be the money leaving/entering my paypal account +# (negative means leaving my account, in all amount fields) +account1 assets:online:paypal +amount1 %netamount + +# the second posting will be money sent to/received from other party +# (account2 is set below) +amount2 -%grossamount + +# if there's a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] + account3 expenses:banking:paypal + amount3 -%feeamount + comment3 business: + +# choose an account for the second posting + +# override the default account names: +# if the amount is positive, it's income (a debit) +if %grossamount ^[^-] + account2 income:unknown +# if negative, it's an expense (a credit) +if %grossamount ^- + account2 expenses:unknown + +# apply common rules for setting account2 & other tweaks +include common.rules + +# apply some overrides specific to this csv + +# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case. +if +Bank Account +Bank Deposit to PP Account + description %type for %referencetxnid %itemtitle + account2 assets:bank:wf:pchecking + account1 assets:online:paypal + +# Currency conversions +if Currency Conversion + account2 equity:currency conversion + +# common.rules + +if +darcs +noble benefactor + account2 revenues:foss donations:darcshub + comment2 business: + +if +Calm Radio + account2 expenses:online:apps + +if +electronic frontier foundation +Patreon +wikimedia +Advent of Code + account2 expenses:dues + +if Google + account2 expenses:online:apps + description google | music + +$ hledger -f paypal-custom.csv print +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed + assets:online:paypal $-6.99 = $-6.99 + expenses:online:apps $6.99 + +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $6.99 = $0.00 + assets:bank:wf:pchecking $-6.99 + +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed + assets:online:paypal $-7.00 = $-7.00 + expenses:dues $7.00 + +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $7.00 = $0.00 + assets:bank:wf:pchecking $-7.00 + +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed + assets:online:paypal $-2.00 = $-2.00 + expenses:dues $2.00 + expenses:banking:paypal ; business: + +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $2.00 = $0.00 + assets:bank:wf:pchecking $-2.00 + +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed + assets:online:paypal $9.41 = $9.41 + revenues:foss donations:darcshub $-10.00 ; business: + expenses:banking:paypal $0.59 ; business: + + +File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top + +12 Timeclock +************ + +The time logging format of timeclock.el, as read by hledger. + + hledger can read time logs in timeclock format. As with Ledger, +these are (a subset of) timeclock.el’s format, containing clock-in and +clock-out entries as in the example below. The date is a simple date. +The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are +optional. The timezone, if present, must be four digits and is ignored +(currently the time is always interpreted as a local time). Lines +beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored. + +i 2015/03/30 09:00:00 some:account name optional description after two spaces +o 2015/03/30 09:20:00 +i 2015/03/31 22:21:45 another account +o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting +some number of hours to an account. Or if the session spans more than +one day, it is split into several transactions, one for each day. For +the above time log, ‘hledger print’ generates these journal entries: + +$ hledger -f t.timeclock print +2015-03-30 * optional description after two spaces + (some:account name) 0.33h + +2015-03-31 * 22:21-23:59 + (another account) 1.64h + +2015-04-01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + +$ hledger -f sample.timeclock balance # current time balances +$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + • use emacs and the built-in timeclock.el, or the extended + timeclock-x.el and perhaps the extras in ledgerutils.el + + • at the command line, use these bash aliases: ‘shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’ + + • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository. + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + +File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top + +13 Timedot +********** + +‘timedot’ format is hledger’s human-friendly time logging format. +Compared to ‘timeclock’ format, it is + + • convenient for quick, approximate, and retroactive time logging + • readable: you can see at a glance where time was spent. + + A timedot file contains a series of day entries, which might look +like this: + +2021-08-04 +hom:errands .... .... +fos:hledger:timedot .. ; docs +per:admin:finance + + hledger reads this as three time transactions on this day, with each +dot representing a quarter-hour spent: + +$ hledger -f a.timedot print # .timedot file extension activates the timedot reader +2021-08-04 * + (hom:errands) 2.00 + +2021-08-04 * + (fos:hledger:timedot) 0.50 + +2021-08-04 * + (per:admin:finance) 0 + + A day entry begins with a date line: + + • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D). + + Optionally this can be followed on the same line by + + • a common *transaction description* for this day + • a common *transaction comment* for this day, after a semicolon + (‘;’). + + After the date line are zero or more optionally-indented time +transaction lines, consisting of: + + • an *account name* - any word or phrase, usually a hledger-style + account name. + • *two or more spaces* - a field separator, required if there is an + amount (as in journal format). + • a *timedot amount* - dots representing quarter hours, or a number + representing hours. + • an optional *comment* beginning with semicolon. This is ignored. + + In more detail, timedot amounts can be: + + • *dots*: zero or more period characters, each representing one + quarter-hour. Spaces are ignored and can be used for grouping. + Eg: ‘.... ..’ + + • a *number*, representing hours. Eg: ‘1.5’ + + • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’, + ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days + weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following + equivalencies are assumed: + ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ = + ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the + generated transaction amount, which is always in hours.) + + There is some added flexibility to help with keeping time log data in +the same file as your notes, todo lists, etc.: + + • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored. + + • Before the first date line, lines beginning with ‘*’ are ignored. + From the first date line onward, a sequence of ‘*’’s followed by a + space at beginning of lines (ie, the headline prefix used by Emacs + Org mode) is ignored. This means the time log can be kept under an + Org headline, and date lines or time transaction lines can be Org + headlines. + + • Lines not ending with a double-space and amount are parsed as + transactions with zero amount. (Most hledger reports hide these by + default; add -E to see them.) + + More examples: + +# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. +2016/2/1 +inc:client1 .... .... .... .... .... .... +fos:haskell .... .. +biz:research . + +2016/2/2 +inc:client1 .... .... +biz:research . + +2016/2/3 +inc:client1 4 +fos:hledger 3 +biz:research 1 + +* Time log +** 2020-01-01 +*** adm:time . +*** adm:finance . + +* 2020 Work Diary +** Q1 +*** 2020-02-29 +**** DONE +0700 yoga +**** UNPLANNED +**** BEGUN +hom:chores + cleaning ... + water plants + outdoor - one full watering can + indoor - light watering +**** TODO +adm:planning: trip +*** LATER + + Reporting: + +$ hledger -f a.timedot print date:2016/2/2 +2016-02-02 * + (inc:client1) 2.00 + +2016-02-02 * + (biz:research) 0.25 + +$ hledger -f a.timedot bal --daily --tree +Balance changes in 2016-02-01-2016-02-03: + + || 2016-02-01d 2016-02-02d 2016-02-03d +============++======================================== + biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 +------------++---------------------------------------- + || 7.75 2.25 8.00 + + Using period instead of colon as account name separator: + +2016/2/4 +fos.hledger.timedot 4 +fos.ledger .. + +$ hledger -f a.timedot --alias /\\./=: bal --tree + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +-------------------- + 4.50 + + A sample.timedot file. + + +File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top + +14 PART 3: REPORTING CONCEPTS +***************************** + + +File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top + +15 Time periods +*************** + +* Menu: + +* Report start & end date:: +* Smart dates:: +* Report intervals:: +* Date adjustment:: +* Period expressions:: + + +File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods + +15.1 Report start & end date +============================ + +By default, most hledger reports will show the full span of time +represented by the journal. The report start date will be the earliest +transaction or posting date, and the report end date will be the latest +transaction, posting, or market price date. + + 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 (below). + + Some notes: + + • End dates are exclusive, as in Ledger, so you should write the date + _after_ the last day you want to see in the report. + • As noted in reporting options: among start/end dates specified with + _options_, the last (i.e. right-most) option takes precedence. + • The effective report start and end dates are the intersection of + the start/end dates from options and that from ‘date:’ queries. + That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January + 2019, the smallest common time span. + • In some cases a report interval will adjust start/end dates to fall + on interval boundaries (see below). + + Examples: + +‘-b begin on St. Patrick’s day 2016 +2016/3/17’ +‘-e 12/1’ end at the start of december 1st of the current year + (11/30 will be the last date included) +‘-b all transactions on or after the 1st of the current month +thismonth’ +‘-p all transactions in the current month +thismonth’ +‘date:2016/3/17..’the above written as queries instead (‘..’ can also be + replaced with ‘-’) +‘date:..12/1’ +‘date:thismonth..’ +‘date:thismonth’ + + +File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods + +15.2 Smart dates +================ + +hledger’s user interfaces accept a "smart date" syntax for added +convenience. Smart dates optionally can be relative to today’s date, be +written with english words, and have less-significant parts omitted +(missing parts are inferred as 1). Some examples: + +‘2004/10/1’, exact date, several separators allowed. Year +‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31 +‘2004.9.1’ +‘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, -1, 0, 1 days from today +tomorrow’ +‘last/this/next -1, 0, 1 periods from the current period +day/week/month/quarter/year’ +‘in n n periods from the current period +days/weeks/months/quarters/years’ +‘n n periods from the current period +days/weeks/months/quarters/years +ahead’ +‘n -n periods from the current period +days/weeks/months/quarters/years +ago’ +‘20181201’ 8 digit YYYYMMDD with valid year month and + day +‘201812’ 6 digit YYYYMM with valid year and month + + Some 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 + + "Today’s date" can be overridden with the ‘--today’ option, in case +it’s needed for testing or for recreating old reports. (Except for +periodic transaction rules, which are not affected by ‘--today’.) + + +File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods + +15.3 Report intervals +===================== + +A report interval can be specified so that reports like register, +balance or activity become multi-period, showing each subperiod as a +separate row or column. + + The following standard intervals can be enabled with command-line +flags: + + • ‘-D/--daily’ + • ‘-W/--weekly’ + • ‘-M/--monthly’ + • ‘-Q/--quarterly’ + • ‘-Y/--yearly’ + + More complex intervals can be specified using ‘-p/--period’, +described below. + + +File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods + +15.4 Date adjustment +==================== + +With a report interval (other than daily), report start / end dates +which have not been specified explicitly and in full (eg not ‘-b +2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are +considered flexible: + + • A flexible start date will be automatically adjusted earlier if + needed to fall on a natural interval boundary. + • Similarly, a flexible end date will be adjusted later if needed to + make the last period a whole interval (the same length as the + others). + + This is convenient for producing clean periodic reports (this is +traditional hledger behaviour). By contrast, fully-specified exact +dates will not be adjusted (this is new in hledger 1.29). + + An example: with a journal whose first date is 2023-01-10 and last +date is 2023-03-20: + + • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’ + The report periods will begin on the 15th day of each month, + starting from 2023-01-15, and the last period’s last day will be + 2023-03-09. (Exact start and end dates, neither is adjusted.) + + • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’ + The report periods will begin on the 1st of each month, starting + from 2023-01-01, and the last period’s last day will be 2023-03-31. + (Flexible start and end dates, both are adjusted.) + + +File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods + +15.5 Period expressions +======================= + +The ‘-p/--period’ option specifies a period expression, which is a +compact way of expressing a start date, end date, and/or report +interval. + + Here’s a period expression with a start and end date (specifying the +first quarter of 2009): + +‘-p "from 2009/1/1 to 2009/4/1"’ + + Several keywords like "from" and "to" are supported for readability; +these are optional. "to" can also be written as ".." or "-". The +spaces are also optional, as long as you don’t run two dates together. +So the following 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, these are also +equivalent to the above: + +‘-p "1/1 4/1"’ +‘-p "jan-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 date in the journal: + +‘-p "from 2009/1/1"’ everything after january 1, 2009 +‘-p "since 2009/1"’ the same, since is a synonym +‘-p "from 2009"’ the same +‘-p "to 2009"’ everything before january 1, 2009 + + You can also specify a period by writing a single partial or full +date: + +‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1” +‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to + 2009/2/1” +‘-p the first day of 2009; equivalent to “2009/1/1 to +"2009/1/1"’ 2009/1/2” + + or by using the "Q" quarter-year syntax (case insensitive): + +‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to + 2009/4/1” +‘-p "q4"’ fourth quarter of the current year + +* Menu: + +* Period expressions with a report interval:: +* More complex report intervals:: +* Multiple weekday intervals:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +15.5.1 Period expressions with a report interval +------------------------------------------------ + +A period expression can also begin with a report interval, separated +from the start/end dates (if any) by a space or the word ‘in’: + +‘-p "weekly from 2009/1/1 to 2009/4/1"’ +‘-p "monthly in 2008"’ +‘-p "quarterly"’ + + +File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions + +15.5.2 More complex report intervals +------------------------------------ + +Some more complex intervals can be specified within period expressions, +such as: + + • ‘biweekly’ (every two weeks) + • ‘fortnightly’ + • ‘bimonthly’ (every two months) + • ‘every day|week|month|quarter|year’ + • ‘every N days|weeks|months|quarters|years’ + + Weekly on a custom day: + + • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted + after the number) + • ‘every WEEKDAYNAME’ (full or three-letter english weekday name, + case insensitive) + + Monthly on a custom day: + + • ‘every Nth day [of month]’ + • ‘every Nth WEEKDAYNAME [of month]’ + + Yearly on a custom day: + + • ‘every MM/DD [of year]’ (month number and day of month number) + • ‘every MONTHNAME DDth [of year]’ (full or three-letter english + month name, case insensitive, and day of month number) + • ‘every DDth MONTHNAME [of year]’ (equivalent to the above) + + Examples: + +‘-p "bimonthly from +2008"’ +‘-p "every 2 weeks"’ +‘-p "every 5 months from +2009/03"’ +‘-p "every 2nd day of periods will go from Tue to Tue +week"’ +‘-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 + November +‘-p "every 5th November"’ same +‘-p "every Nov 5th"’ same + + Show historical balances at end of the 15th day of each month (N is +an end date, exclusive as always): + +$ hledger balance -H -p "every 16th day" + + Group postings from the start of wednesday to end of the following +tuesday (N is both (inclusive) start date and (exclusive) end date): + +$ hledger register checking -p "every 3rd day of week" + + +File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions + +15.5.3 Multiple weekday intervals +--------------------------------- + +This special form is also supported: + + • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english + weekday names, case insensitive) + + Also, ‘weekday’ and ‘weekendday’ are shorthand for +‘mon,tue,wed,thu,fri’ and ‘sat,sun’. + + This is mainly intended for use with ‘--forecast’, to generate +periodic transactions on arbitrary days of the week. It may be less +useful with ‘-p’, since it divides each week into subperiods of unequal +length, which is unusual. (Related: #1632) + + Examples: + +‘-p "every dates will be Mon, Wed, Fri; periods will be +mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun +‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will +weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun +‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri +weekendday"’ + + +File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top + +16 Depth +******** + +With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show +accounts only to the specified depth, hiding deeper subaccounts. Use +this when you want a summary with less detail. This flag has the same +effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are +equivalent. + + +File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top + +17 Queries +********** + +One of hledger’s strengths is being able to quickly report on a precise +subset of your data. Most hledger commands accept optional query +arguments to restrict their scope. The syntax is as follows: + + • Zero or more space-separated query terms. These are most often + account name substrings: + + ‘utilities food:groceries’ + + • Terms with spaces or other special characters should be enclosed in + quotes: + + ‘"personal care"’ + + • Regular expressions are also supported: + + ‘"^expenses\b" "accounts (payable|receivable)"’ + + • Add a query type prefix to match other parts of the data: + + ‘date:202012- desc:amazon cur:USD amt:">100" status:’ + + • Add a ‘not:’ prefix to negate a term: + + ‘not:cur:USD’ + +* Menu: + +* Query types:: +* Combining query terms:: +* Queries and command options:: +* Queries and valuation:: +* Querying with account aliases:: +* Querying with cost or value:: + + +File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries + +17.1 Query types +================ + +Here are the types of query term available. Remember these can also be +prefixed with *‘not:’* to convert them into a negative match. + + *‘acct:REGEX’, ‘REGEX’* +Match account names containing this (case insensitive) regular +expression. This is the default query type when there is no prefix, and +regular expression syntax is typically not needed, so usually we just +write an account name substring, like ‘expenses’ or ‘food’. + + *‘amt:N, amt:N, amt:>=N’* +Match postings with a single-commodity amount equal to, less than, or +greater than N. (Postings with 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 special characters which are +regex-significant, you need to escape them with ‘\’. And for characters +which are significant to your shell you may need one more level of +escaping. So eg to match the dollar sign: +‘hledger print cur:\\$’. + + *‘desc:REGEX’* +Match transaction descriptions. + + *‘date:PERIODEXPR’* +Match dates (or with the ‘--date2’ flag, secondary dates) within the +specified period. PERIODEXPR is a period expression with no report +interval. Examples: +‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’, +‘date:2021-07-27..nextquarter’. + + *‘date2:PERIODEXPR’* +Match secondary dates within the specified period (independent of the +‘--date2’ flag). + + *‘depth:N’* +Match (or display, depending on command) accounts at or above this +depth. + + *‘note:REGEX’* +Match transaction notes (the part of the description right of ‘|’, or +the whole description if there’s no ‘|’). + + *‘payee:REGEX’* +Match transaction payee/payer names (the part of the description left of +‘|’, or the whole description if there’s no ‘|’). + + *‘real:, real:0’* +Match real or virtual postings respectively. + + *‘status:, status:!, status:*’* +Match unmarked, pending, or cleared transactions respectively. + + *‘type:TYPECODES’* +Match by account type (see Declaring accounts > Account types). +‘TYPECODES’ is one or more of the single-letter account type codes +‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match +their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain +kinds of account alias can disrupt account types, see Rewriting accounts +> Aliases and account types. + + *‘tag:REGEX[=REGEX]’* +Match by tag name, and optionally also by tag value. (To match only by +value, use ‘tag:.=REGEX’.) + + When querying by tag, note that: + + • Accounts also inherit the tags of their parent accounts + • Postings also inherit the tags of their account and their + transaction + • Transactions also acquire the tags of their postings. + + (*‘inacct:ACCTNAME’* +A special query term used automatically in hledger-web only: tells +hledger-web to show the transaction register for an account.) + + +File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries + +17.2 Combining query terms +========================== + +When given multiple query terms, most commands select things which +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 is a little different, showing 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. + + Although these fixed rules are enough for many needs, we do not +support full boolean expressions (#203), (and you should not write AND +or OR in your queries). This makes certain queries hard to express, but +here are some tricks that can help: + + 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses + paid with cash: + + $ hledger print food not:not:cash + + 2. Or pre-filter the transactions with ‘print’, piping the result into + a second hledger command (with balance assertions disabled): + + $ hledger print cash | hledger -f- -I balance food + + +File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries + +17.3 Queries and command options +================================ + +Some queries can also be expressed as command-line options: ‘depth:2’ is +equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc. +When you mix command options and query arguments, generally the +resulting query is their intersection. + + +File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries + +17.4 Queries and valuation +========================== + +When amounts are converted to other commodities in cost or value +reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old +amount quantity, not the new ones (except in hledger 1.22.0 where it’s +reversed, see #1625). + + +File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries + +17.5 Querying with account aliases +================================== + +When account names are rewritten with ‘--alias’ or ‘alias’, note that +‘acct:’ will match either the old or the new account name. + + +File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries + +17.6 Querying with cost or value +================================ + +When amounts are converted to other commodities in cost or value +reports, note that ‘cur:’ matches the new commodity symbol, and not the +old one, and ‘amt:’ matches the new quantity, and not the old one. +Note: this changed in hledger 1.22, previously it was the reverse, see +the discussion at #1625. + + +File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top + +18 Pivoting +*********** + +Normally, hledger groups and sums amounts within each account. The +‘--pivot FIELD’ option substitutes some other transaction field for +account names, causing amounts to be grouped and summed by that field’s +value instead. FIELD can be any of the transaction fields ‘status’, +‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on +a tag and a posting has multiple values of that tag, only the first +value is displayed. Values containing ‘colon:separated:parts’ will be +displayed hierarchically, like account names. + + Some examples: + +2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues +-------------------- + 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): + +$ 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: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top + +19 Generating data +****************** + +Two features for generating transient data (visible only at report time) +are built in to hledger’s journal format: + + • Auto posting rules can generate extra postings on certain + transactions. They are activated by the ‘--auto’ flag. + + • Periodic transaction rules can generate repeating transactions, + usually dated in the future, to help with forecasting or budgeting. + They are activated by the ‘--forecast’ or ‘balance --budget’ + options, described next. + + +File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top + +20 Forecasting +************** + +The ‘--forecast’ flag activates any periodic transaction rules in the +journal. These will generate temporary additional transactions, usually +recurring and in the future, which will appear in all reports. ‘hledger +print --forecast’ is a good way to see them. + + This can be useful for estimating balances into the future, perhaps +experimenting with different scenarios. + + It could also be useful for scripted data entry: you could describe +recurring transactions, and every so often copy the output of ‘print +--forecast’ into the journal. + + The generated transactions will have an extra tag, like +‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule +generated them. There is also a similar, hidden tag, named +‘_generated-transaction:’, which you can use to reliably match +transactions generated "just now" (rather than ‘print’ed in the past). + + The forecast transactions are generated within a _forecast period_, +which is independent of the report period. (Forecast period sets the +bounds for generated transactions, report period controls which +transactions are reported.) The forecast period begins on: + + • the start date provided within ‘--forecast’’s argument, if any + • otherwise, the later of + • the report start date, if specified (with ‘-b’/‘-p’/‘date:’) + • the day after the latest ordinary transaction in the journal, + if any + + • otherwise today. + + It ends on: + + • the end date provided within ‘--forecast’’s argument, if any + • otherwise, the report end date, if specified (with + ‘-e’/‘-p’/‘date:’) + • otherwise 180 days (6 months) from today. + + Note, this means that ordinary transactions will suppress periodic +transactions, by default; the periodic transactions will not start until +after the last ordinary transaction. This is usually convenient, but +you can get around it in two ways: + + • If you need to record some transactions in the future, make them + periodic transactions (with a single occurrence, eg: ‘~ + YYYY-MM-DD’) rather than ordinary transactions. That way they + won’t suppress other periodic transactions. + + • Or give ‘--forecast’ a period expression argument. A forecast + period specified this way can overlap ordinary transactions, and + need not be in the future. Some things to note: + + • You must use ‘=’ between flag and argument; a space won’t + work. + • The period expression can specify the forecast period’s start + date, end date, or both. See also Report start & end date. + • The period expression should not specify a report interval. + (Each periodic transaction rule specifies its own interval.) + + Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’, +‘--forecast=2021’. + + +File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top + +21 Budgeting +************ + +With the balance command’s ‘--budget’ report, each periodic transaction +rule generates recurring budget goals in specified accounts, and goals +and actual performance can be compared. See the balance command’s doc +below. + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top + +22 Cost reporting +***************** + +This section is about recording the cost of things, in transactions +where one commodity is exchanged for another. Eg an exchange of +currency, or a stock purchase or sale. First, a quick glossary: + + • Conversion - an exchange of one currency or commodity for another. + Eg a foreign currency exchange, or a purchase or sale of stock or + cryptocurrency. + + • Conversion transaction - a transaction involving one or more + conversions. + + • Conversion rate - the cost per unit of one commodity in the other, + ie the exchange rate. + + • Cost - how much of one commodity was paid to acquire the other. + And more generally, in hledger docs: the amount exchanged in the + "secondary" commodity (usually your base currency), whether in a + purchase or a sale, and whether expressed per unit or in total. + Also, the "@/@@ PRICE" notation used to represent this. + +* Menu: + +* -B Convert to cost:: +* Equity conversion postings:: +* Inferring equity postings from cost:: +* Inferring cost from equity postings:: +* When to infer cost/equity:: +* How to record conversions:: +* Cost tips:: + + +File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting + +22.1 -B: Convert to cost +======================== + +As discussed in JOURNAL > Costs, when recording a transaction you can +also record the amount’s cost in another commodity, by adding ‘@ +UNITPRICE’ or ‘@@ TOTALPRICE’. + + Then you can see a report with amounts converted to cost, by adding +the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger). +Eg: + +2022-01-01 + assets:dollars $-135 ; 135 dollars is exchanged for.. + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + +$ hledger bal -N + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Notes: + + -B is sensitive to the order of postings when a cost 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: + +2022-01-01 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros + + The @/@@ cost notation is convenient, but has some drawbacks: it does +not truly balance the transaction, so it disrupts the accounting +equation and tends to causes a non-zero total in balance reports. + + +File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting + +22.2 Equity conversion postings +=============================== + +By contrast, conventional double entry bookkeeping (DEB) uses a +different notation: an extra pair of equity postings to balance +conversion transactions. In this style, the above entry might be +written: + +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 + + This style is more correct, but it’s also more verbose and makes cost +reporting more difficult for PTA tools. + + Happily, current hledger can read either notation, or convert one to +the other when needed, so you can use the one you prefer. + + You can even use cost notation and equivalent conversion postings at +the same time, for clarity. hledger will ignore the redundancy. But be +sure the cost and conversion posting amounts match, or you’ll see a +not-so-clear transaction balancing error message. + + +File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting + +22.3 Inferring equity postings from cost +======================================== + +With ‘--infer-equity’, hledger detects transactions written with PTA +cost notation and adds equity conversion postings to them: + +2022-01-01 + assets:dollars -$135 + assets:euros €100 @ $1.35 + +$ hledger print --infer-equity +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 + equity:conversion:$-€:€ €-100 ; generated-posting: + equity:conversion:$-€:$ $135.00 ; generated-posting: + + The conversion account names can be changed with the conversion +account type declaration. + + –infer-equity is useful when when transactions have been recorded +using cost notation, to help preserve the accounting equation and +balance reports’ zero total, or to produce more conventional journal +entries for sharing with non-PTA-users. + + +File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting + +22.4 Inferring cost from equity postings +======================================== + +The reverse operation is possible using ‘--infer-costs’, which detects +transactions written with equity conversion postings and adds cost +notation to them: + +2022-01-01 + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 + +$ hledger print --infer-costs +2022-01-01 + assets:dollars $-135 @@ €100 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 + + –infer-costs is useful when combined with -B/–cost, allowing cost +reporting even when transactions have been recorded using equity +postings: + +$ hledger print --infer-costs -B +2009-01-01 + assets:dollars €-100 + assets:euros €100 + + Notes: + + For ‘--infer-costs’ to work, an exchange must consist of four +postings: + + 1. two non-equity postings + 2. two equity postings, next to one another + 3. the equity accounts must be declared, with account type + ‘V’/‘Conversion’ (or if they are not declared, they must be named + ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or + subaccounts of these) + 4. the equity postings’ amounts must exactly match the non-equity + postings’ amounts. + + Multiple such exchanges can coexist within a single transaction. + + When inferring cost, the order of postings matters: the cost is added +to the first of the non-equity postings involved in the exchange, in the +commodity of the last non-equity posting involved in the exchange. If +you don’t want to write your postings in the required order, you can use +explicit cost notation instead. + + –infer-equity and –infer-costs can be used together, if you have a +mixture of both notations in your journal. + + +File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting + +22.5 When to infer cost/equity +============================== + +Inferring equity postings or costs is still fairly new, so not enabled +by default. We’re not sure yet if that should change. Here are two +suggestions to try, experience reports welcome: + + 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal + -B --infer-costs’ + + 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger + --infer-equity --infer-costs"’ + + +File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting + +22.6 How to record conversions +============================== + +Essentially there are four ways to record a conversion transaction in +hledger. Here are all of them, with pros and cons. + +* Menu: + +* Conversion with implicit cost:: +* Conversion with explicit cost:: +* Conversion with equity postings:: +* Conversion with equity postings and explicit cost:: + + +File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions + +22.6.1 Conversion with implicit cost +------------------------------------ + +Let’s assume 100 EUR is converted to 120 USD. You can just record the +outflow (100 EUR) and inflow (120 USD) in the appropriate asset account: + +2021-01-01 + assets:cash -100 EUR + assets:cash 120 USD + + hledger will assume this transaction is balanced, inferring that the +conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate +by using ‘hledger print -x’. + + Pro: + + • Concise, easy + + Con: + + • Less error checking - typos in amounts or commodity symbols may not + be detected + • Conversion rate is not clear + • Disturbs the accounting equation, unless you add the –infer-equity + flag + + You can prevent accidental implicit conversions due to a mistyped +commodity symbol, by using ‘hledger check commodities’. + + You can prevent implicit conversions entirely, by using ‘hledger +check balancednoautoconversion’, or ‘-s/--strict’. + + +File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions + +22.6.2 Conversion with explicit cost +------------------------------------ + +You can add the conversion rate using @ notation: + +2021-01-01 + assets:cash -100 EUR @ 1.20 USD + assets:cash 120 USD + + Now hledger will check that 100 * 1.20 = 120, and would report an +error otherwise. + + Pro: + + • Still concise + • Makes the conversion rate clear + • Provides more error checking + + Con: + + • Disturbs the accounting equation, unless you add the –infer-equity + flag + + +File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions + +22.6.3 Conversion with equity postings +-------------------------------------- + +In strict double entry bookkeeping, the above transaction is not +balanced in EUR or in USD, since some EUR disappears, and some USD +appears. This violates the accounting equation (A+L+E=0), and prevents +reports like ‘balancesheetequity’ from showing a zero total. + + The proper way to make it balance is to add a balancing posting for +each commodity, using an equity account: + +2021-01-01 + assets:cash -100 EUR + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + Pro: + + • Preserves the accounting equation + • Keeps track of conversions and related gains/losses in one place + • Standard, works in any double entry accounting system + + Con: + + • More verbose + • Conversion rate is not obvious + • Cost reporting requires adding the –infer-costs flag + + +File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions + +22.6.4 Conversion with equity postings and explicit cost +-------------------------------------------------------- + +Here both equity postings and @ notation are used together. + +2021-01-01 + assets:cash -100 EUR @ 1.20 USD + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + Pro: + + • Preserves the accounting equation + • Keeps track of conversions and related gains/losses in one place + • Makes the conversion rate clear + • Provides more error checking + + Con: + + • Most verbose + • Not compatible with ledger + + +File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting + +22.7 Cost tips +============== + + • Recording the cost/conversion rate explicitly is good because it + makes that clear and helps detect errors. + • Recording equity postings is good because it is correct bookkeeping + and preserves the accounting equation. + • Combining these is possible. + • When you want to see the cost (or sale proceeds) of things, use + ‘-B’ (short form of ‘--cost’). + • If you use conversion postings without cost notation, add + ‘--infer-costs’ also. + • If you use cost notation without conversion postings, and you want + to see a balanced balance sheet or print correct journal entries, + use ‘--infer-equity’. + • Conversion to cost is performed before valuation (described next). + + +File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top + +23 Valuation +************ + +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), and/or to market value (using some market price on a +certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’ +option, which will be described below. We also provide the simpler ‘-V’ +and ‘-X COMMODITY’ options, and often one of these is all you need: + +* Menu: + +* -V Value:: +* -X Value in specified commodity:: +* Valuation date:: +* Finding market price:: +* --infer-market-prices market prices from transactions:: +* Valuation commodity:: +* Simple valuation examples:: +* --value Flexible valuation:: +* More valuation examples:: +* Interaction of valuation and queries:: +* Effect of valuation on reports:: + + +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation + +23.1 -V: Value +============== + +The ‘-V/--market’ flag converts amounts to market value in their default +_valuation commodity_, using the market prices in effect on the +_valuation date(s)_, if any. More on these in a minute. + + +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation + +23.2 -X: Value in specified commodity +===================================== + +The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which +currency you want to convert to, and it tries to convert everything to +that. + + +File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation + +23.3 Valuation date +=================== + +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which market +prices will be used. + + For single period reports, if an explicit report end date is +specified, that will be used as the valuation date; otherwise the +valuation date is the journal’s end date. + + For multiperiod reports, each column/period is valued on the last day +of the period, by default. + + +File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation + +23.4 Finding market price +========================= + +To convert a commodity A to its market value in another commodity B, +hledger looks for a suitable market price (exchange rate) as follows, in +this order of preference : + + 1. A _declared market price_ or _inferred market price_: A’s latest + market price in B on or before the valuation date as declared by a + P directive, or (with the ‘--infer-market-prices’ flag) inferred + from costs. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 3. A _forward chain of market prices_: a synthetic price formed by + combining the shortest chain of "forward" (only 1 above) market + prices, leading from A to B. + + 4. _Any chain of market prices_: a chain of any market prices, + including both forward and reverse prices (1 and 2 above), leading + from A to B. + + There is a limit to the length of these price chains; if hledger +reaches that length without finding a complete chain or exhausting all +possibilities, it will give up (with a "gave up" message visible in +‘--debug=2’ output). That limit is currently 1000. + + Amounts for which no suitable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation + +23.5 –infer-market-prices: market prices from transactions +========================================================== + +Normally, market value in hledger is fully controlled by, and requires, +P directives in your journal. Since adding and updating those can be a +chore, and since transactions usually take place at close to market +value, why not use the recorded costs as additional market prices (as +Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or +‘--value’ enables this. + + So for example, ‘hledger bs -V --infer-market-prices’ will get market +prices both from P directives and from transactions. If both occur on +the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Valuation section carefully, and try adding +‘--debug’ or ‘--debug=2’ to troubleshoot. + + ‘--infer-market-prices’ can infer market prices from: + + • multicommodity transactions with explicit prices (‘@’/‘@@’) + + • multicommodity transactions with implicit prices (no ‘@’, two + commodities, unbalanced). (With these, the order of postings + matters. ‘hledger print -x’ can be useful for troubleshooting.) + + • multicommodity transactions with equity postings, if cost is + inferred with ‘--infer-costs’. + + There is a limitation (bug) currently: when a valuation commodity is +not specified, prices inferred with ‘--infer-market-prices’ do not help +select a default valuation commodity, as ‘P’ prices would. So +conversion might not happen because no valuation commodity was detected +(‘--debug=2’ will show this). To be safe, specify the valuation +commmodity, eg: + + • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’ + • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then + --infer-market-prices’ + + Signed costs and market prices can be confusing. For reference, here +is the current behaviour, since hledger 1.25. (If you think it should +work differently, see #1870.) + +2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + +2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + +2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + +2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + +2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + +2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each +day, the two transactions are considered equivalent). Here are the +market prices inferred for B: + +$ hledger -f- --infer-market-prices prices +P 2022-01-01 B A 1 +P 2022-01-01 B A 1.0 +P 2022-01-02 B A -1 +P 2022-01-02 B A -1.0 +P 2022-01-03 B A -1 +P 2022-01-03 B A -1.0 + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation + +23.6 Valuation commodity +======================== + +*When you specify a valuation commodity (‘-X COMM’ or ‘--value +TYPE,COMM’):* +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). + + *When you leave the valuation commodity unspecified (‘-V’ or ‘--value +TYPE’):* +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: + + 1. The price commodity from the latest P-declared market price for A + on or before valuation date. + + 2. The price commodity from the latest P-declared market price for A + on any date. (Allows conversion to proceed when there are inferred + prices before the valuation date.) + + 3. If there are no P directives at all (any commodity or date) and the + ‘--infer-market-prices’ flag is used: the price commodity from the + latest transaction-inferred price for A on or before valuation + date. + + This means: + + • If you have P directives, they determine which commodities ‘-V’ + will convert, and to what. + + • If you have no P directives, and use the ‘--infer-market-prices’ + flag, costs determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation + +23.7 Simple valuation examples +============================== + +Here are some quick examples of ‘-V’: + +; 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 + + +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation + +23.8 –value: Flexible valuation +=============================== + +‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option: + + --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. + COMM is an optional commodity symbol. + Shows amounts converted to: + - default valuation commodity (or COMM) using market prices at posting dates + - default valuation commodity (or COMM) using market prices at period end(s) + - default valuation commodity (or COMM) using current market prices + - default valuation commodity (or COMM) using market prices at some date + + The TYPE part selects cost or value and valuation date: + +‘--value=then’ + + Convert amounts to their value in the default valuation commodity, + using market prices on each posting’s date. +‘--value=end’ + + Convert amounts to their value in the default valuation commodity, + using market prices on the last day of the report period (or if + unspecified, the journal’s end date); or in multiperiod reports, + market prices on the last day of each subperiod. +‘--value=now’ + + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). +‘--value=YYYY-MM-DD’ + + Convert amounts to their value in the default valuation commodity + using market prices on this date. + + To select a different valuation commodity, add the optional ‘,COMM’ +part: a comma, then the target commodity’s symbol. Eg: +*‘--value=now,EUR’*. hledger will do its best to convert amounts to +this commodity, deducing market prices as described above. + + +File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation + +23.9 More valuation examples +============================ + +Here are some examples showing the effect of ‘--value’, as seen with +‘print’: + +P 2000-01-01 A 1 B +P 2000-02-01 A 2 B +P 2000-03-01 A 3 B +P 2000-04-01 A 4 B + +2000-01-01 + (a) 1 A @ 5 B + +2000-02-01 + (a) 1 A @ 6 B + +2000-03-01 + (a) 1 A @ 7 B + + Show the cost of each posting: + +$ hledger -f- print --cost +2000-01-01 + (a) 5 B + +2000-02-01 + (a) 6 B + +2000-03-01 + (a) 7 B + + Show the value as of the last day of the report period (2000-02-29): + +$ hledger -f- print --value=end date:2000/01-2000/03 +2000-01-01 + (a) 2 B + +2000-02-01 + (a) 2 B + + With no report period specified, that shows the value as of the last +day of the journal (2000-03-01): + +$ hledger -f- print --value=end +2000-01-01 + (a) 3 B + +2000-02-01 + (a) 3 B + +2000-03-01 + (a) 3 B + + Show the current value (the 2000-04-01 price is still in effect +today): + +$ hledger -f- print --value=now +2000-01-01 + (a) 4 B + +2000-02-01 + (a) 4 B + +2000-03-01 + (a) 4 B + + Show the value on 2000/01/15: + +$ hledger -f- print --value=2000-01-15 +2000-01-01 + (a) 1 B + +2000-02-01 + (a) 1 B + +2000-03-01 + (a) 1 B + + You may need to explicitly set a commodity’s display style, when +reverse prices are used. Eg this output might be surprising: + +P 2000-01-01 A 2B + +2000-01-01 + a 1B + b + +$ hledger print -x -X A +2000-01-01 + a 0 + b 0 + + Explanation: because there’s no amount or commodity directive +specifying a display style for A, 0.5A gets the default style, which +shows no decimal digits. Because the displayed amount looks like zero, +the commodity symbol and minus sign are not displayed either. Adding a +commodity directive sets a more useful display style for A: + +P 2000-01-01 A 2B +commodity 0.00A + +2000-01-01 + a 1B + b + +$ hledger print -X A +2000-01-01 + a 0.50A + b -0.50A + + +File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation + +23.10 Interaction of valuation and queries +========================================== + +When matching postings based on queries in the presence of valuation, +the following happens. + + 1. The query is separated into two parts: + 1. the currency (‘cur:’) or amount (‘amt:’). + 2. all other parts. + + 2. The postings are matched to the currency and amount queries based + on pre-valued amounts. + 3. Valuation is applied to the postings. + 4. The postings are matched to the other parts of the query based on + post-valued amounts. + + See: 1625 + + +File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation + +23.11 Effect of valuation on reports +==================================== + +Here is a reference for how valuation is supposed to affect each part of +hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll +sideways.) It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. + +Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’, +type ‘--cost’ ‘--value=now’ +------------------------------------------------------------------------------ +*print* +posting cost value at value at posting value at value +amounts report end date report or at + or today journal DATE/today + end +balance unchanged unchanged unchanged unchanged unchanged +assertions/assignments +*register* +starting cost value at valued at day value at value +balance report or each historical report or at +(-H) journal posting was made journal DATE/today + end end +starting cost value at valued at day value at value +balance day before each historical day before at +(-H) report or posting was made report or DATE/today +with journal journal +report start start +interval +posting cost value at value at posting value at value +amounts report or date report or at + journal journal DATE/today + end end +summary summarised value at sum of postings value at value +posting cost period in interval, period at +amounts ends valued at ends DATE/today +with interval start +report +interval +running sum/average sum/average sum/average of sum/average sum/average +total/averageof of displayed values of of + displayed displayed displayed displayed + values values values values +*balance +(bs, +bse, cf, +is)* +balance sums of value at value at posting value at value +changes costs report end date report or at + or today journal DATE/today + of sums of end of of + postings sums of sums + postings of + postings +budget like like like balance like like +amounts balance balance changes balances balance +(–budget) changes changes changes +grand sum of sum of sum of displayed sum of sum of +total displayed displayed valued displayed displayed + values values values values +*balance +(bs, +bse, cf, +is) with +report +interval* +starting sums of value at sums of values value at sums +balances costs of report of postings report of +(-H) postings start of before report start of postings + before sums of start at sums of before + report all respective all report + start postings posting dates postings start + before before + report report + start start +balance sums of same as sums of values balance value +changes costs of –value=end of postings in change in at +(bal, postings period at each DATE/today +is, bs in period respective period, of +–change, posting dates valued at sums +cf period of +–change) ends postings +end sums of same as sums of values period end value +balances costs of –value=end of postings from balances, at +(bal -H, postings before period valued at DATE/today +is –H, from start to period period of +bs, cf) before end at ends sums + report respective of + start to posting dates postings + period end +budget like like like balance like like +amounts balance balance changes/end balances balance +(–budget) changes/end changes/end balances changes/end + balances balances balances +row sums, sums, sums, averages sums, sums, +totals, averages averages of displayed averages averages +row of of values of of +averages displayed displayed displayed displayed +(-T, -A) values values values values +column sums of sums of sums of sums of sums +totals displayed displayed displayed values displayed of + values values values displayed + values +grand sum, sum, sum, average of sum, sum, +total, average of average of column totals average of average +grand column column column of +average totals totals totals column + totals + + ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with +a zero starting balance. + + *Glossary:* + +_cost_ + + calculated using price(s) recorded in the transaction(s). +_value_ + + market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. +_report start_ + + the first day of the report period specified with -b or -p or + date:, otherwise today. +_report or journal start_ + + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. +_report end_ + + the last day of the report period specified with -e or -p or date:, + otherwise today. +_report or journal end_ + + the last day of the report period specified with -e or -p or date:, + otherwise the latest transaction date in the journal, otherwise + today. +_report interval_ + + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report’s multi-period mode (whether showing one or many + subperiods). + + +File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top + +24 PART 4: COMMANDS +******************* + +* Menu: + +* Commands overview:: +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* payees:: +* prices:: +* print:: +* register:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS + +24.1 Commands overview +====================== + +Here are the built-in commands: + +* Menu: + +* DATA ENTRY:: +* DATA CREATION:: +* DATA MANAGEMENT:: +* REPORTS FINANCIAL:: +* REPORTS VERSATILE:: +* REPORTS BASIC:: +* HELP:: +* ADD-ONS:: + + +File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview + +24.1.1 DATA ENTRY +----------------- + +These data entry commands are the only ones which can modify your +journal file. + + • add - add transactions using terminal prompts + • import - add new transactions from other files, eg CSV files + + +File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview + +24.1.2 DATA CREATION +-------------------- + + • close - generate balance-zeroing/restoring transactions + • rewrite - generate auto postings, like print –auto + + +File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview + +24.1.3 DATA MANAGEMENT +---------------------- + + • check - check for various kinds of error in the data + • diff - compare account transactions in two journal files + + +File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview + +24.1.4 REPORTS, FINANCIAL +------------------------- + + • aregister (areg) - show transactions in a particular account + • 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 + + +File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview + +24.1.5 REPORTS, VERSATILE +------------------------- + + • balance (bal) - show balance changes, end balances, budgets, + gains.. + • print - show transactions or export journal data + • register (reg) - show postings in one or more accounts & running + total + • roi - show return on investments + + +File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview + +24.1.6 REPORTS, BASIC +--------------------- + + • accounts - show account names + • activity - show bar charts of posting counts per period + • codes - show transaction codes + • commodities - show commodity/currency symbols + • descriptions - show transaction descriptions + • files - show input file paths + • notes - show note parts of transaction descriptions + • payees - show payee parts of transaction descriptions + • prices - show market prices + • stats - show journal statistics + • tags - show tag names + • test - run self tests + + +File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview + +24.1.7 HELP +----------- + + • help - show the hledger manual with info/man/pager + + +File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview + +24.1.8 ADD-ONS +-------------- + +And here are some typical add-on commands. Some of these are installed +by the hledger-install script. If installed, they will appear in +hledger’s commands list: + + • ui - run hledger’s terminal UI + • web - run hledger’s web UI + • iadd - add transactions using a TUI (currently hard to build) + • interest - generate interest transactions + • stockquotes - download market prices from AlphaVantage + • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + pijul, plot, and more.. + + Next, each command is described in detail, in alphabetical order. + + +File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS + +24.2 accounts +============= + +Show account names. + + This command lists account names. By default it shows all known +accounts, either used in transactions or declared with account +directives. + + With query arguments, only matched account names and account names +referenced by matched postings are shown. + + Or it can show just the used accounts (‘--used’/‘-u’), the declared +accounts (‘--declared’/‘-d’), the accounts declared but not used +(‘--unused’), the accounts used but not declared (‘--undeclared’), or +the first account matched by an account name pattern, if any (‘--find’). + + 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’. + + With ‘--types’, it also shows each account’s type, if it’s known. +(See Declaring accounts > Account types.) + + With ‘--positions’, it also shows the file and line number of each +account’s declaration, if any, and the account’s overall declaration +order; these may be useful when troubleshooting account display order. + + With ‘--directives’, it adds the ‘account’ keyword, showing valid +account directives which can be pasted into a journal file. This is +useful together with ‘--undeclared’ when updating your account +declarations to satisfy ‘hledger check accounts’. + + The ‘--find’ flag can be used to look up a single account name, in +the same way that the ‘aregister’ command does. It returns the +alphanumerically-first matched account name, or if none can be found, it +fails with a non-zero exit code. + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + +$ hledger accounts --undeclared --directives >> $LEDGER_FILE +$ hledger check accounts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS + +24.3 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: aregister, Prev: activity, Up: PART 4 COMMANDS + +24.4 add +======== + +Prompt for transactions and add them to the journal. Any arguments will +be used as default inputs for the first N prompts. + + 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 main journal file (which should be +in journal format). Existing transactions are not changed. This is one +of the few hledger commands that writes to the journal file (see also +‘import’). + + 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, + payees/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 go one step + backward. + • Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see https://hledger.org/add.html for a detailed tutorial): + +$ 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 go one step backward. +To end a transaction, enter . when prompted. +To quit, enter . at a date prompt or press control-d or control-c. +Date [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]: $ + + On Microsoft Windows, the add command makes sure that no part of the +file path ends with a period, as that would cause problems (#1056). + + +File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS + +24.5 aregister +============== + +(areg) + + Show the transactions and running historical balance of a single +account, with each transaction displayed as one line. + + ‘aregister’ shows the overall transactions affecting a particular +account (and any subaccounts). Each report line represents one +transaction in this account. Transactions before the report start date +are always included in the running balance (‘--historical’ mode is +always on). + + This is a more "real world", bank-like view than the ‘register’ +command (which shows individual postings, possibly from multiple +accounts, not necessarily in historical mode). As a quick rule of +thumb: - use ‘aregister’ for reviewing and reconciling real-world +asset/liability accounts - use ‘register’ for reviewing detailed +revenues/expenses. + + ‘aregister’ requires one argument: the account to report on. You can +write either the full account name, or a case-insensitive regular +expression which will select the alphabetically first matched account. + + When there are multiple matches, the alphabetically-first choice can +be surprising; eg if you have ‘assets:per:checking 1’ and +‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select +‘assets:biz:checking 2’. It’s just a convenience to save typing, so if +in doubt, write the full account name, or a distinctive substring that +matches uniquely. + + Transactions involving subaccounts of this account will also be +shown. ‘aregister’ ignores depth limits, so its final total will always +match a balance report with similar arguments. + + Any additional arguments form a query which will filter the +transactions shown. Note some queries will disturb the running balance, +causing it to be different from the account’s real-world running +balance. + + An example: this shows the transactions and historical running +balance during july, in the first account whose name contains +"checking": + +$ hledger areg checking date:jul + + Each ‘aregister’ line item shows: + + • the transaction’s date (or the relevant posting’s date if + different, see below) + • the names of all the other account(s) involved in this transaction + (probably abbreviated) + • the total change to this account’s balance from this transaction + • the account’s historical running balance after this transaction. + + Transactions making a net change of zero are not shown by default; +add the ‘-E/--empty’ flag to show them. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +‘--align-all’ flag. + + This command also supports the output destination and output format +options. The output formats supported are ‘txt’, ‘csv’, and ‘json’. + +* Menu: + +* aregister and custom posting dates:: + + +File: hledger.info, Node: aregister and custom posting dates, Up: aregister + +24.5.1 aregister and custom posting dates +----------------------------------------- + +Transactions whose date is outside the report period can still be shown, +if they have a posting to this account dated inside the report period. +(And in this case it’s the posting date that is shown.) This ensures +that ‘aregister’ can show an accurate historical running balance, +matching the one shown by ‘register -H’ with the same arguments. + + To filter strictly by transaction date instead, add the ‘--txn-dates’ +flag. If you use this flag and some of your postings have custom dates, +it’s probably best to assume the running balance is wrong. + + +File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS + +24.6 balance +============ + +(bal) + + Show accounts and their balances. + + ‘balance’ is one of hledger’s oldest and most versatile commands, for +listing account balances, balance changes, values, value changes and +more, during one time period or many. Generally it shows a table, with +rows representing accounts, and columns representing periods. + + Note there are some higher-level variants of the ‘balance’ command +with convenient defaults, which can be simpler to use: ‘balancesheet’, +‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need +more control, then use ‘balance’. + +* Menu: + +* balance features:: +* Simple balance report:: +* Balance report line format:: +* Filtered balance report:: +* List or tree mode:: +* Depth limiting:: +* Dropping top-level accounts:: +* Showing declared accounts:: +* Sorting by amount:: +* Percentages:: +* Multi-period balance report:: +* Balance change end balance:: +* Balance report types:: +* Budget report:: +* Data layout:: +* Useful balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +24.6.1 balance features +----------------------- + +Here’s a quick overview of the ‘balance’ command’s features, followed by +more detailed descriptions and examples. Many of these work with the +higher-level commands as well. + + ‘balance’ can show.. + + • accounts as a list (‘-l’) or a tree (‘-t’) + • optionally depth-limited (‘-[1-9]’) + • sorted by declaration order and name, or by amount + + ..and their.. + + • balance changes (the default) + • or actual and planned balance changes (‘--budget’) + • or value of balance changes (‘-V’) + • or change of balance values (‘--valuechange’) + • or unrealised capital gain/loss (‘--gain’) + + ..in.. + + • one time period (the whole journal period by default) + • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’) + + ..either.. + + • per period (the default) + • or accumulated since report start date (‘--cumulative’) + • or accumulated since account creation (‘--historical/-H’) + + ..possibly converted to.. + + • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’) + • or market value, as of transaction dates (‘--value=then[,COMM]’) + • or at period ends (‘--value=end[,COMM]’) + • or now (‘--value=now’) + • or at some other date (‘--value=YYYY-MM-DD’) + + ..with.. + + • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign + (‘--invert’) + • rows and columns swapped (‘--transpose’) + • another field used as account name (‘--pivot’) + • custom-formatted line items (single-period reports only) + (‘--format’) + • commodities displayed on the same line or multiple lines + (‘--layout’) + + This command supports the output destination and output format +options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period +reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal, +negative amounts are shown in red. + + The ‘--related’/‘-r’ flag shows the balance of the _other_ postings +in the transactions of the postings which would normally be shown. + + +File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance + +24.6.2 Simple balance report +---------------------------- + +With no arguments, ‘balance’ shows a list of all accounts and their +change of balance - ie, the sum of posting amounts, both inflows and +outflows - during the entire period of the journal. ("Simple" here +means just one column of numbers, covering a single period. You can +also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end +balance at the end of the journal period; more on this below. + + Accounts are sorted by declaration order if any, and then +alphabetically by account name. For instance (using +examples/sample.journal): + +$ hledger -f examples/sample.journal bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + Accounts with a zero balance (and no non-zero subaccounts, in tree +mode - see below) are hidden by default. Use ‘-E/--empty’ to show them +(revealing ‘assets:bank:checking’ here): + +$ hledger -f examples/sample.journal bal -E + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + The total of the amounts displayed is shown as the last line, unless +‘-N’/‘--no-total’ is used. + + +File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance + +24.6.3 Balance report line format +--------------------------------- + +For single-period balance reports displayed in the terminal (only), you +can use ‘--format FMT’ to customise the format and content of each line. +Eg: + +$ hledger -f examples/sample.journal 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 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: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance + +24.6.4 Filtered balance report +------------------------------ + +You can show fewer accounts, a different time period, totals from +cleared transactions only, etc. by using query arguments or options to +limit the postings being matched. Eg: + +$ hledger -f examples/sample.journal bal --cleared assets date:200806 + $-2 assets:cash +-------------------- + $-2 + + +File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance + +24.6.5 List or tree mode +------------------------ + +By default, or with ‘-l/--flat’, accounts are shown as a flat list with +their full names visible, as in the examples above. + + With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’ +"leaf" names indented below their parent: + +$ hledger -f examples/sample.journal balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts +-------------------- + 0 + + Notes: + + • "Boring" accounts are combined with their subaccount for more + compact output, unless ‘--no-elide’ is used. Boring accounts have + no balance of their own and just one subaccount (eg ‘assets:bank’ + and ‘liabilities’ above). + + • All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, + which requires explanation when sharing reports with + non-plaintextaccounting-users. A tree mode report’s final total is + the sum of the top-level balances shown, not of all the balances + shown. + + • Each group of sibling accounts (ie, under a common parent) is + sorted separately. + + +File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance + +24.6.6 Depth limiting +--------------------- + +With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg: +‘-3’) balance reports will show accounts only to the specified depth, +hiding the deeper subaccounts. This can be useful for getting an +overview without too much detail. + + Account balances at the depth limit always include the balances from +any deeper subaccounts (even in list mode). Eg, limiting to depth 1: + +$ hledger -f examples/sample.journal balance -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities +-------------------- + 0 + + +File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance + +24.6.7 Dropping top-level accounts +---------------------------------- + +You can also hide one or more top-level account name parts, using +‘--drop NUM’. This can be useful for hiding repetitive top-level +account names: + +$ hledger -f examples/sample.journal bal expenses --drop 1 + $1 food + $1 supplies +-------------------- + $2 + + +File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance + +24.6.8 Showing declared accounts +-------------------------------- + +With ‘--declared’, accounts which have been declared with an account +directive will be included in the balance report, even if they have no +transactions. (Since they will have a zero balance, you will also need +‘-E/--empty’ to see them.) + + More precisely, _leaf_ declared accounts (with no subaccounts) will +be included, since those are usually the more useful in reports. + + The idea of this is to be able to see a useful "complete" balance +report, even when you don’t have transactions in all of your declared +accounts yet. + + +File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance + +24.6.9 Sorting by amount +------------------------ + +With ‘-S/--sort-amount’, accounts with the largest (most positive) +balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your +biggest averaged monthly expenses first. When more than one commodity +is present, they will be sorted by the alphabetically earliest commodity +first, and then by subsequent commodities (if an amount is missing a +commodity, it is treated as 0). + + Revenues and liability balances are typically negative, however, so +‘-S’ shows these in reverse order. To work around this, you can add +‘--invert’ to flip the signs. (Or, use one of the higher-level reports, +which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’). + + +File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance + +24.6.10 Percentages +------------------- + +With ‘-%/--percent’, balance reports show each account’s value expressed +as a percentage of the (column) total. + + Note it is not useful to calculate percentages if the amounts in a +column have mixed signs. In this case, make a separate report for each +sign, eg: + +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` + + Similarly, if the amounts in a column have mixed commodities, convert +them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a +separate report for each commodity: + +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ + + +File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance + +24.6.11 Multi-period balance report +----------------------------------- + +With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’, +‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag), +‘balance’ shows a tabular report, with columns representing successive +time periods (and a title): + +$ hledger -f examples/sample.journal bal --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 + + Notes: + + • The report’s start/end dates will be expanded, if necessary, to + fully encompass the displayed subperiods (so that the first and + last subperiods have the same duration as the others). + • Leading and trailing periods (columns) containing all zeroes are + not shown, unless ‘-E/--empty’ is used. + • Accounts (rows) containing all zeroes are not shown, unless + ‘-E/--empty’ is used. + • Amounts with many commodities are shown in abbreviated form, unless + ‘--no-elide’ is used. _(experimental)_ + • Average and/or total columns can be added with the ‘-A/--average’ + and ‘-T/--row-total’ flags. + • The ‘--transpose’ flag can be used to exchange rows and columns. + • The ‘--pivot FIELD’ option causes a different transaction field to + be used as "account name". See PIVOTING. + + Multi-period reports with many periods can be too wide for easy +viewing in the terminal. Here are some ways to handle that: + + • Hide the totals row with ‘-N/--no-total’ + • Convert to a single currency with ‘-V’ + • Maximize the terminal window + • Reduce the terminal’s font size + • View with a pager like less, eg: ‘hledger bal -D --color=yes | less + -RS’ + • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D + -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or + a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’) + • Output as HTML and view with a browser: ‘hledger bal -D -o a.html + && open a.html’ + + +File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance + +24.6.12 Balance change, end balance +----------------------------------- + +It’s important to be clear on the meaning of the numbers shown in +balance reports. Here is some terminology we use: + + A *_balance change_* is the net amount added to, or removed from, an +account during some period. + + An *_end balance_* is the amount accumulated in an account as of some +date (and some time, but hledger doesn’t store that; assume end of day +in your timezone). It is the sum of previous balance changes. + + We call it a *_historical end balance_* if it includes all balance +changes since the account was created. For a real world account, this +means it will match the "historical record", eg the balances reported in +your bank statements or bank web UI. (If they are correct!) + + In general, balance changes are what you want to see when reviewing +revenues and expenses, and historical end balances are what you want to +see when reviewing or reconciling asset, liability and equity accounts. + + ‘balance’ shows balance changes by default. To see accurate +historical end balances: + + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the + journal covers the account’s full lifetime. + + 2. Include all of of the account’s prior postings in the report, by + not specifying a report start date, or by using the + ‘-H/--historical’ flag. (‘-H’ causes report start date to be + ignored when summing postings.) + + +File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance + +24.6.13 Balance report types +---------------------------- + +The balance command is quite flexible; here is the full detail on how to +control what it reports. If the following seems complicated, don’t +worry - this is for advanced reporting, and it does typically take some +time and experimentation to get clear on all these report modes. + + There are three important option groups: + + ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] +...’ + +* Menu: + +* Calculation type:: +* Accumulation type:: +* Valuation type:: +* Combining balance report types:: + + +File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types + +24.6.13.1 Calculation type +.......................... + +The basic calculation to perform for each table cell. It is one of: + + • ‘--sum’ : sum the posting amounts (*default*) + • ‘--budget’ : sum the amounts, but also show the budget goal amount + (for each account/period) + • ‘--valuechange’ : show the change in period-end historical balance + values (caused by deposits, withdrawals, and/or market price + fluctuations) + • ‘--gain’ : show the unrealised capital gain/loss, (the current + valued balance minus each amount’s original cost) + + +File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types + +24.6.13.2 Accumulation type +........................... + +How amounts should accumulate across report periods. Another way to say +it: which time period’s postings should contribute to each cell’s +calculation. It is one of: + + • ‘--change’ : calculate with postings from column start to column + end, ie "just this column". Typically used to see + revenues/expenses. (*default for balance, incomestatement*) + + • ‘--cumulative’ : calculate with postings from report start to + column end, ie "previous columns plus this column". Typically used + to show changes accumulated since the report’s start date. Not + often used. + + • ‘--historical/-H’ : calculate with postings from journal start to + column end, ie "all postings from before report start date until + this column’s end". Typically used to see historical end balances + of assets/liabilities/equity. (*default for balancesheet, + balancesheetequity, cashflow*) + + +File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types + +24.6.13.3 Valuation type +........................ + +Which kind of value or cost conversion should be applied, if any, before +displaying the report. It is one of: + + • no valuation type : don’t convert to cost or value (*default*) + • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to + some other commodity) + • ‘--value=then[,COMM]’ : convert amounts to market value on + transaction dates + • ‘--value=end[,COMM]’ : convert amounts to market value on period + end date(s) + (*default with ‘--valuechange’, ‘--gain’*) + • ‘--value=now[,COMM]’ : convert amounts to market value on today’s + date + • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on + another date + + or one of the equivalent simpler flags: + + • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are + independent options which can both be used at once) + • ‘-V/--market’ : like –value=end + • ‘-X COMM/--exchange COMM’ : like –value=end,COMM + + See Cost reporting and Valuation for more about these. + + +File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types + +24.6.13.4 Combining balance report types +........................................ + +Most combinations of these options should produce reasonable reports, +but if you find any that seem wrong or misleading, let us know. The +following restrictions are applied: + + • ‘--valuechange’ implies ‘--value=end’ + • ‘--valuechange’ makes ‘--change’ the default when used with the + ‘balancesheet’/‘balancesheetequity’ commands + • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’ + + For reference, here is what the combinations of accumulation and +valuation show: + +Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value= +Accumulation:v YYYY-MM-DD + /now’ +----------------------------------------------------------------------------- +‘--change’change in sum of period-end DATE-value + period posting-date value of of change in + market values change in period + in period period +‘--cumulative’change from sum of period-end DATE-value + report start to posting-date value of of change + period end market values change from from report + from report report start start to + start to period to period end period end + end +‘--historicalchange from sum of period-end DATE-value +/-H’ journal start posting-date value of of change + to period end market values change from from journal + (historical end from journal journal start start to + balance) start to period to period end period end + end + + +File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance + +24.6.14 Budget report +--------------------- + +The ‘--budget’ report type activates extra columns showing any budget +goals for each account and period. The budget goals are defined by +periodic transactions. This is useful for comparing planned and actual +income, expenses, time usage, etc. + + 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] + + This is different from a normal balance report in several ways: + + • Only accounts with budget goals during the report period are shown, + by default. + + • In each column, in square brackets after the actual amount, budget + goal amounts are shown, and the actual/goal percentage. (Note: + budget goals should be in the same commodity as the actual amount.) + + • All parent accounts are always shown, even in list mode. Eg + assets, assets:bank, and expenses above. + + • Amounts always include all subaccounts, budgeted or unbudgeted, + even in list mode. + + This means that the numbers displayed will not always add up! Eg +above, the ‘expenses’ actual amount includes the gifts and supplies +transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts +are not shown, as they have no budget amounts declared. + + This can be confusing. When you need to make things clearer, use the +‘-E/--empty’ flag, which will reveal all accounts including unbudgeted +ones, giving the full picture. Eg: + +$ 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] + + It’s common to limit budgets/budget reports to just expenses + +hledger bal -M --budget expenses + + or just revenues and expenses (eg, using account types): + +hledger bal -M --budget type:rx + + It’s also common to limit or convert them to a single currency +(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple +currencies, ‘--layout bare’ or ‘--layout tall’ can help. + + For more examples and notes, see Budgeting. + +* Menu: + +* Budget report start date:: +* Budgets and subaccounts:: +* Selecting budget goals:: +* Budget vs forecast:: + + +File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report + +24.6.14.1 Budget report start date +.................................. + +This might be a bug, but for now: when making budget reports, it’s a +good idea to explicitly set the report’s start date to the first day of +a reporting period, because a periodic rule like ‘~ monthly’ generates +its transactions on the 1st of each month, and if your journal has no +regular transactions on the 1st, the default report start date could +exclude that budget goal, which can be a little surprising. Eg here the +default report period is just the day of 2020-01-15: + +~ monthly in 2020 + (expenses:food) $500 + +2020-01-15 + expenses:food $400 + assets:checking + +$ hledger bal expenses --budget +Budget performance in 2020-01-15: + + || 2020-01-15 +==============++============ + || $400 +--------------++------------ + || $400 + + To avoid this, specify the budget report’s period, or at least the +start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the +budget goal transactions (periodic transactions) that you want. Eg, +adding ‘-b 2020/1/1’ to the above: + +$ hledger bal expenses --budget -b 2020/1/1 +Budget performance in 2020-01-01..2020-01-15: + + || 2020-01-01..2020-01-15 +===============++======================== + expenses:food || $400 [80% of $500] +---------------++------------------------ + || $400 [80% of $500] + + +File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report + +24.6.14.2 Budgets and subaccounts +................................. + +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 implicitly +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] + + +File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report + +24.6.14.3 Selecting budget goals +................................ + +The budget report evaluates periodic transaction rules to generate +special "goal transactions", which generate the goal amounts for each +account in each report subperiod. When troubleshooting, you can use +‘print --forecast’ to show these as forecasted transactions: + +$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated + + By default, the budget report uses all available periodic transaction +rules to generate goals. This includes rules with a different report +interval from your report. Eg if you have daily, weekly and monthly +periodic rules, all of these will contribute to the goals in a monthly +budget report. + + You can select a subset of periodic rules by providing an argument to +the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules +whose description contains DESCPAT, a case-insensitive substring (not a +regular expression or query). This means you can give your periodic +rules descriptions (remember that two spaces are needed), and then +select from multiple budgets defined in your journal. + + +File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report + +24.6.14.4 Budget vs forecast +............................ + +‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate +features, though both of them use the periodic transaction rules defined +in the journal, and both of them generate temporary transactions for +reporting purposes ("forecast transactions" and "budget goal +transactions", respectively). You can use both features at the same +time if you want. Here are some differences between them, as of hledger +1.29: + + CLI: + + • –forecast is a general hledger option, usable with any command + • –budget is a ‘balance’ command option, usable only with that + command. + + Visibility of generated transactions: + + • forecast transactions are visible in any report, like ordinary + transactions + • budget goal transactions are invisible except for the goal amounts + they produce in –budget reports. + + Periodic transaction rules: + + • –forecast uses all available periodic transaction rules + • –budget uses all periodic rules (‘--budget’) or a selected subset + (‘--budget=DESCPAT’) + + Period of generated transactions: + + • –forecast generates forecast transactions + • from after the last regular transaction to the end of the + report period (‘--forecast’) + • or, during a specified period (‘--forecast=PERIODEXPR’) + • possibly further restricted by a period specified in the + periodic transaction rule + • and always restricted within the bounds of the report period + + • –budget generates budget goal transactions + • throughout the report period + • possibly restricted by a period specified in the periodic + transaction rule. + + +File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance + +24.6.15 Data layout +------------------- + +The ‘--layout’ option affects how balance reports show multi-commodity +amounts and commodity symbols, which can improve readability. It can +also normalise the data for easy consumption by other programs. It has +four possible values: + + • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line, + optionally elided to WIDTH + • ‘--layout=tall’: each commodity is shown on a separate line + • ‘--layout=bare’: commodity symbols are in their own column, amounts + are bare numbers + • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form, + with one row per data value + + Here are the ‘--layout’ modes supported by each output format; note +only CSV output supports all of them: + +- txt csv html json sql +--------------------------------------- +wide Y Y Y +tall Y Y Y +bare Y Y Y +tidy Y + + Examples: + + • Wide layout. With many commodities, reports can be very wide: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + • Limited wide layout. A width limit reduces the width, but some + commodities will be hidden: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + • Tall layout. Each commodity gets a new line (may be different in + each column), and account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + • Bare layout. Commodity symbols are kept in one column, each + commodity gets its own report row, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + • Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + • Tidy layout produces normalised "tidy data", where every variable + has its own column and each row represents a single data point. + See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html + for more. This is the easiest kind of data for other software to + consume. Here’s how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + +File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance + +24.6.16 Useful balance reports +------------------------------ + +Some frequently used ‘balance’ options/reports are: + + • ‘bal -M revenues expenses’ + Show revenues/expenses in each month. Also available as the + ‘incomestatement’ command. + + • ‘bal -M -H assets liabilities’ + Show historical asset/liability balances at each month end. Also + available as the ‘balancesheet’ command. + + • ‘bal -M -H assets liabilities equity’ + Show historical asset/liability/equity balances at each month end. + Also available as the ‘balancesheetequity’ command. + + • ‘bal -M assets not:receivable’ + Show changes to liquid assets in each month. Also available as the + ‘cashflow’ command. + + Also: + + • ‘bal -M expenses -2 -SA’ + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + • ‘bal -M --budget expenses’ + Show monthly expenses and budget goals. + + • ‘bal -M --valuechange investments’ + Show monthly change in market value of investment assets. + + • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert]’ + Show top gainers [or losers] last week + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS + +24.7 balancesheet +================= + +(bs) + + This command displays a balance sheet, showing historical ending +balances of asset and liability accounts. (To see equity as well, use +the balancesheetequity command.) Amounts are shown with normal positive +sign, as in conventional financial statements. + + This report shows accounts declared with the ‘Asset’, ‘Cash’ or +‘Liability’ type (see account types). Or if no such accounts are +declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case +insensitive, plurals allowed) and their subaccounts. + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance -H assets liabilities’, but with +smarter account detection, and liabilities displayed with their sign +flipped. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS + +24.8 balancesheetequity +======================= + +(bse) + + This command displays a balance sheet, showing historical ending +balances of asset, liability and equity accounts. Amounts are shown +with normal positive sign, as in conventional financial statements. + + This report shows accounts declared with the ‘Asset’, ‘Cash’, +‘Liability’ or ‘Equity’ type (see account types). Or if no such +accounts are declared, it shows top-level accounts named ‘asset’, +‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their +subaccounts. + + 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 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance -H assets liabilities equity’, but +with smarter account detection, and liabilities/equity displayed with +their sign flipped. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS + +24.9 cashflow +============= + +(cf) + + This command displays a cashflow statement, showing the inflows and +outflows affecting "cash" (ie, liquid, easily convertible) assets. +Amounts are shown with normal positive sign, as in conventional +financial statements. + + This report shows accounts declared with the ‘Cash’ type (see account +types). Or if no such accounts are declared, it shows accounts + + • under a top-level account named ‘asset’ (case insensitive, plural + allowed) + • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or + ‘saving’. + + More precisely: all accounts matching this case insensitive regular +expression: + + ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’ + + and their subaccounts. + + An example cashflow report: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance assets not:fixed not:investment +not:receivable’, but with smarter account detection. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS + +24.10 check +=========== + +Check for various kinds of errors in your data. + + hledger provides a number of built-in error checks to help prevent +problems in your data. Some of these are run automatically; or, you can +use this ‘check’ command to run them on demand, with no output and a +zero exit code if all is well. Specify their names (or a prefix) as +argument(s). + + Some examples: + +hledger check # basic checks +hledger check -s # basic + strict checks +hledger check ordereddates payees # basic + two other checks + + If you are an Emacs user, you can also configure flycheck-hledger to +run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available: + +* Menu: + +* Basic checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: +* More about specific checks:: + + +File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check + +24.10.1 Basic checks +-------------------- + +These checks are always run automatically, by (almost) all hledger +commands, including ‘check’: + + • *parseable* - data files are well-formed and can be successfully + parsed + + • *balancedwithautoconversion* - all transactions are balanced, + inferring missing amounts where necessary, and possibly converting + commodities using costs or automatically-inferred costs + + • *assertions* - all balance assertions in the journal are passing. + (This check can be disabled with ‘-I’/‘--ignore-assertions’.) + + +File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check + +24.10.2 Strict checks +--------------------- + +These additional checks are run when the ‘-s’/‘--strict’ (strict mode) +flag is used. Or, they can be run by giving their names as arguments to +‘check’: + + • *accounts* - all account names used by transactions have been + declared + + • *commodities* - all commodity symbols used have been declared + + • *balancednoautoconversion* - transactions are balanced, possibly + using explicit costs but not inferred ones + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +24.10.3 Other checks +-------------------- + +These checks can be run only by giving their names as arguments to +‘check’. They are more specialised and not desirable for everyone, +therefore optional: + + • *ordereddates* - transactions are ordered by date within each file + + • *payees* - all payees used by transactions have been declared + + • *recentassertions* - all accounts with balance assertions have a + balance assertion no more than 7 days before their latest posting + + • *tags* - all tags used by transactions have been declared + + • *uniqueleafnames* - all account leaf names are unique + + +File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check + +24.10.4 Custom checks +--------------------- + +A few more checks are are available as separate add-on commands, in +https://github.com/simonmichael/hledger/tree/master/bin: + + • *hledger-check-tagfiles* - all tag values containing / (a forward + slash) exist as file paths + + • *hledger-check-fancyassertions* - more complex balance assertions + are passing + + You could make similar scripts to perform your own custom checks. +See: Cookbook -> Scripting. + + +File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check + +24.10.5 More about specific checks +---------------------------------- + +‘hledger check recentassertions’ will complain if any balance-asserted +account does not have a balance assertion within 7 days before its +latest posting. This aims to prevent the situation where you are +regularly updating your journal, but forgetting to check your balances +against the real world, then one day must dig back through months of +data to find an error. It assumes that adding a balance assertion +requires/reminds you to check the real-world balance. That may not be +true if you auto-generate balance assertions from bank data; in that +case, I recommend to import transactions uncleared, then use the +manual-review-and-mark-cleared phase as a reminder to check the latest +assertions against real-world balances. + + +File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS + +24.11 close +=========== + +‘close [--retain | --migrate | --open] [QUERY]’ + + By default: prints a transaction that zeroes out ("closes") all +accounts, transferring their balances to an equity account. Query +arguments can be added to override the accounts selection. Three other +modes are supported: + + ‘--retain’: prints a transaction closing revenue and expense +balances. This is traditionally done by businesses at the end of each +accounting period; it is less necessary in personal and computer-based +accounting, but it can help balance the accounting equation A=L+E. + + ‘--migrate’: prints a transaction to close asset, liability and most +equity balances, and another transaction to re-open them. This can be +useful when starting a new file (for performance or data protection). +Adding the closing transaction to the old file allows old and new files +to be combined. + + ‘--open’: as above, but prints just the opening transaction. This +can be useful for starting a new file, leaving the old file unchanged. +Similar to Ledger’s equity command. + + You can change the equity account name with ‘--close-acct ACCT’. It +defaults to ‘equity:retained earnings’ with ‘--retain’, or +‘equity:opening/closing balances’ otherwise. + + You can change the transaction description(s) with ‘--close-desc +'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with +‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise. + + Just one posting to the equity account will be used by default, with +an implicit amount. + + With ‘--x/--explicit’ the amount will be shown explicitly, and if it +involves multiple commodities, a separate posting will be generated for +each commodity. + + With ‘--interleaved’, each equity posting is shown next to the +corresponding source/destination posting. + + The default closing date is yesterday or the journal’s end date, +whichever is later. You can change this by specifying a report end +date; the last day of the report period will be the closing date. Eg +‘-e 2022’ means "close on 2022-12-31". + + The default closing date is yesterday, or the journal’s end date, +whichever is later. You can change this by specifying a report end +date; (The report start date does not matter.) The last day of the +report period will be the closing date; eg ‘-e 2022’ means "close on +2022-12-31". The opening date is always the day after the closing date. + +* Menu: + +* close and costs:: +* close and balance assertions:: +* Example retain earnings:: +* Example migrate balances to a new file:: +* Example excluding closing/opening transactions:: + + +File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close + +24.11.1 close and costs +----------------------- + +With ‘--show-costs’, any amount costs are shown, with separate postings +for each cost. (This currently the best way to view investment assets, +showing lots and cost bases.) If you have many currency conversion or +investment transactions, it can generate very large journal entries. + + +File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close + +24.11.2 close and balance assertions +------------------------------------ + +Balance assertions will be generated, verifying that the accounts have +been reset to zero (and then restored to their previous balances, if +there is an opening transaction). + + These provide useful error checking, but you can ignore them +temporarily with ‘-I’, or remove them if you prefer. + + You probably should avoid filtering transactions by status or +realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’), +with this command, since the balance assertions would depend on these. + + Note custom posting dates spanning the file boundary will disrupt the +balance assertions: + +2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve that you can transfer the money to and from a temporary +account, in effect splitting the multi-day transaction into two +single-day transactions: + +; in 2022.journal: +2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + +; in 2023.journal: +2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + +File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close + +24.11.3 Example: retain earnings +-------------------------------- + +Record 2022’s revenues/expenses as retained earnings on 2022-12-31, +appending the generated transaction to the journal: + +$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + Now 2022’s income statement will show only zeroes. To see it again, +exclude the retain transaction. Eg: + +$ hledger -f 2022.journal is not:desc:'retain earnings' + + +File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close + +24.11.4 Example: migrate balances to a new file +----------------------------------------------- + +Close assets/liabilities/equity on 2022-12-31 and re-open them on +2023-01-01: + +$ hledger close --migrate -f 2022.journal -p 2022 +# copy/paste the closing transaction to the end of 2022.journal +# copy/paste the opening transaction to the start of 2023.journal + + Now 2022’s balance sheet will show only zeroes, indicating a balanced +accounting equation. (Unless you are using @/@@ notation - in that +case, try adding –infer-equity.) To see it again, exclude the closing +transaction. Eg: + +$ hledger -f 2022.journal bs not:desc:'closing balances' + + +File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close + +24.11.5 Example: excluding closing/opening transactions +------------------------------------------------------- + +When combining many files for multi-year reports, the closing/opening +transactions cause some noise in reports like ‘print’ and ‘register’. +You can exclude them as shown above, but ‘not:desc:...’ could be +fragile, and also you will need to avoid excluding the very first +opening transaction, which can be awkward. Here is a way to do it, +using tags: add ‘clopen:’ tags to all opening/closing balances +transactions except the first, like this: + +; 2021.journal +2021-06-01 first opening balances +... +2021-12-31 closing balances ; clopen:2022 +... + +; 2022.journal +2022-01-01 opening balances ; clopen:2022 +... +2022-12-31 closing balances ; clopen:2023 +... + +; 2023.journal +2023-01-01 opening balances ; clopen:2023 +... + + Now, assuming a combined journal like: + +; all.journal +include 2021.journal +include 2022.journal +include 2023.journal + + The ‘clopen:’ tag can exclude all but the first opening transaction. +To show a clean multi-year checking register: + +$ hledger -f all.journal areg checking not:tag:clopen + + And the year values allow more precision. To show 2022’s year-end +balance sheet: + +$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 + + +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS + +24.12 codes +=========== + +List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction’s code field, in +the order transactions were parsed. The transaction code is an optional +value written in parentheses between the date and description, often +used to store a cheque number, order number or similar. + + Transactions aren’t required to have a code, and missing or empty +codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they +will be printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + +2022/1/1 (123) Supermarket + Food $5.00 + Checking + +2022/1/2 (124) Post Office + Postage $8.32 + Checking + +2022/1/3 Supermarket + Food $11.23 + Checking + +2022/1/4 (126) Post Office + Postage $3.21 + Checking + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + +126 + + +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS + +24.13 commodities +================= + +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS + +24.14 descriptions +================== + +List the unique descriptions that appear in transactions. + + This command lists the unique descriptions that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. + + Example: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS + +24.15 diff +========== + +Compares a particular account’s transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + + More precisely, for each posting affecting this account in either +file, it looks for a corresponding posting in the other file which posts +the same amount to the same account (ignoring date, description, etc.) +Since postings not transactions are compared, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This is useful eg if you have downloaded an account’s transactions +from your bank (eg as CSV data). When hledger and your bank disagree +about the account balance, you can compare the bank data with your +journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS + +24.16 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: PART 4 COMMANDS + +24.17 help +========== + +Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a +pager. With a TOPIC argument, open it at that topic if possible. TOPIC +can be any heading in the manual, or a heading prefix, case insensitive. +Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto +postings"’. + + This command shows the hledger manual built in to your hledger +version. It can be useful when offline, or when you prefer the terminal +to a web browser, or when the appropriate hledger manual or viewing +tools are not installed on your system. + + By default it chooses the best viewer found in $PATH (preferring info +since the hledger manual is large). You can select a particular viewer +with the ‘-i’, ‘-m’, or ‘-p’ flags. + + Examples + +$ hledger help --help # show how the help command works +$ hledger help # show the hledger manual with info, man or $PAGER +$ hledger help journal # show the journal topic in the hledger manual + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS + +24.18 import +============ + +Read new transactions added to each FILE since last run, and add them to +the journal. Or with –dry-run, just print the transactions that would +be added. Or with –catchup, just mark all of the FILEs’ transactions as +imported, without actually importing any. + + This command may append new transactions to the main journal file +(which should be in journal format). Existing transactions are not +changed. This is one of the few hledger commands that writes to the +journal file (see also ‘add’). + + Unlike other hledger commands, with ‘import’ the journal file is an +output file, and will be modified, though only by appending (existing +data will not be changed). The input files are specified as arguments, +so to import one or more CSV files to your main journal, you will run +‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’. + + Note you can import from any file format, though CSV files are the +most common import source, and these docs focus on that case. + +* Menu: + +* Deduplication:: +* Import testing:: +* Importing balance assignments:: +* Commodity display styles:: + + +File: hledger.info, Node: Deduplication, Next: Import testing, Up: import + +24.18.1 Deduplication +--------------------- + +As a convenience ‘import’ does _deduplication_ while reading +transactions. This does not mean "ignore transactions that look the +same", but rather "ignore transactions that have been seen before". +This is intended for when you are periodically importing foreign data +which may contain already-imported transactions. So eg, if every day +you download bank CSV files containing redundant data, you can safely +run ‘hledger import bank.csv’ and only new transactions will be +imported. (‘import’ is idempotent.) + + Since the items being read (CSV records, eg) often do not come with +unique identifiers, hledger detects new transactions by date, assuming +that: + + 1. new items always have the newest dates + 2. item dates do not change across reads + 3. and items with the same date remain in the same relative order + across reads. + + These are often true of CSV files representing transactions, or true +enough so that it works pretty well in practice. 1 is important, but +violations of 2 and 3 amongst the old transactions won’t matter (and if +you import often, the new transactions will be few, so less likely to be +the ones affected). + + hledger remembers the latest date processed in each input file by +saving a hidden ".latest" state file in the same directory. Eg when +reading ‘finance/bank.csv’, it will look for and update the +‘finance/.latest.bank.csv’ state file. The format is simple: one or +more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I +have processed transactions up to this date, and this many of them on +that date." Normally you won’t see or manipulate these state files +yourself. But if needed, you can delete them to reset the state (making +all transactions "new"), or you can construct them to "catch up" to a +certain date. + + Note deduplication (and updating of state files) can also be done by +‘print --new’, but this is less often used. + + +File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import + +24.18.2 Import testing +---------------------- + +With ‘--dry-run’, the transactions that will be imported are printed to +the terminal, without updating your journal or state files. The output +is valid journal format, like the print command, so you can re-parse it. +Eg, to see any importable transactions which CSV rules have not +categorised: + +$ hledger import --dry bank.csv | hledger -f- -I print unknown + + or (live updating): + +$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' + + Note: when importing from multiple files at once, it’s currently +possible for some .latest files to be updated successfully, while the +actual import fails because of a problem in one of the files, leaving +them out of sync (and causing some transactions to be missed). To +prevent this, do a –dry-run first and fix any problems before the real +import. + + +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import + +24.18.3 Importing balance assignments +------------------------------------- + +Entries added by import will have their posting amounts made explicit +(like ‘hledger print -x’). This means that any balance assignments in +imported files must be evaluated; but, imported files don’t get to see +the main file’s account balances. As a result, importing entries with +balance assignments (eg from an institution that provides only balances +and not posting amounts) will probably generate incorrect posting +amounts. To avoid this problem, use print instead of import: + +$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE + + (If you think import should leave amounts implicit like print does, +please test it and send a pull request.) + + +File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import + +24.18.4 Commodity display styles +-------------------------------- + +Imported amounts will be formatted according to the canonical commodity +styles (declared or inferred) in the main journal file. + + +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS + +24.19 incomestatement +===================== + +(is) + + This command displays an income statement, showing revenues and +expenses during one or more periods. Amounts are shown with normal +positive sign, as in conventional financial statements. + + This report shows accounts declared with the ‘Revenue’ or ‘Expense’ +type (see account types). Or if no such accounts are declared, it shows +top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case +insensitive, plurals allowed) and their subaccounts. + + Example: + +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance '(revenues|income)' expenses’, but +with smarter account detection, and revenues/income displayed with their +sign flipped. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS + +24.20 notes +=========== + +List the unique notes that appear in transactions. + + This command lists the unique notes that appear in transactions, in +alphabetic order. You can add a query to select a subset of +transactions. The note is the part of the transaction description after +a | character (or if there is no |, the whole description). + + Example: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS + +24.21 payees +============ + +List the unique payee/payer names that appear in transactions. + + This command lists unique payee/payer names which have been declared +with payee directives (–declared), used in transaction descriptions +(–used), or both (the default). + + The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). + + You can add query arguments to select a subset of transactions. This +implies –used. + + Example: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS + +24.22 prices +============ + +Print market price directives from the journal. With +–infer-market-prices, generate additional market prices from costs. +With –infer-reverse-prices, also generate market prices by inverting +known prices. Prices can be filtered by a query. Price amounts are +displayed with their full precision. + + +File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS + +24.23 print +=========== + +Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from +the journal file, sorted by date (or with ‘--date2’, by secondary date). + + Amounts are shown mostly normalised to commodity display style, eg +the placement of commodity symbols will be consistent. All of their +decimal places are shown, as in the original journal entry (with one +alteration: in some cases trailing zeroes are added.) + + Amounts are shown right-aligned within each transaction (but not +across all transactions). + + Directives and inter-transaction comments are not shown, currently. +This means the print command is somewhat lossy, and if you are using it +to reformat your journal you should take care to also copy over the +directives and file-level comments. + + Eg: + +$ 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 + + print’s output is usually a valid hledger journal, and you can +process it again with a second hledger command. This can be useful for +certain kinds of search, eg: + +# Show running total of food expenses paid from cash. +# -f- reads from stdin. -I/--ignore-assertions is sometimes needed. +$ hledger print assets:cash | hledger -f- -I reg expenses:food + + There are some situations where print’s output can become +unparseable: + + • Valuation affects posting amounts but not balance assertion or + balance assignment amounts, potentially causing those to fail. + • Auto postings can generate postings with too many missing amounts. + • Account aliases can generate bad account names. + + Normally, the journal entry’s explicit or implicit amount style is +preserved. For example, when an amount is omitted in the journal, it +will not appear in the output. Similarly, when a cost is implied but +not written, it will not appear in the output. You can use the +‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can +be useful for troubleshooting or for making your journal more readable +and robust against data entry errors. ‘-x’ is also implied by using any +of ‘-B’,‘-V’,‘-X’,‘--value’. + + Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity +amount (these can arise when a multi-commodity transaction has an +implicit amount) to be split into multiple single-commodity postings, +keeping the output parseable. + + With ‘-B’/‘--cost’, amounts with costs are converted to cost using +that price. This can be used for troubleshooting. + + With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one +recent transaction whose description is most similar to DESC. DESC +should contain at least two characters. If there is no similar-enough +match, no transaction will be shown and the program exit code will be +non-zero. + + With ‘--new’, hledger prints only transactions it has not seen on a +previous run. This uses the same deduplication system as the ‘import’ +command. (See import’s docs for details.) + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, and +(experimental) ‘json’ and ‘sql’. + + 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: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS + +24.24 register +============== + +(reg) + + Show postings and their running total. + + The register command displays matched postings, across all accounts, +in date order, with their running total or running historical balance. +(See also the ‘aregister’ command, which shows matched transactions in a +specific account.) + + register normally shows line per posting, but note that +multi-commodity amounts will occupy multiple lines (one line per +commodity). + + It 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. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +‘--align-all’ flag. + + 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. + + The ‘--invert’ flag negates all amounts. For example, it can be used +on an income account where amounts are normally displayed as negative +numbers. It’s also useful to show postings on the checking account +together with the related account: + +$ hledger register --related --invert assets:checking + + 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. + + With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one +recent posting whose description is most similar to DESC. DESC should +contain at least two characters. If there is no similar-enough match, +no posting will be shown and the program exit code will be non-zero. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +24.24.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 the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, and +(experimental) ‘json’. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS + +24.25 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:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +24.25.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. + + +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite + +24.25.2 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: rewrite + +24.25.3 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: PART 4 COMMANDS + +24.26 roi +========= + +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + + At a minimum, you need to supply a query (which could be just an +account name) to select your investment(s) with ‘--inv’, and another +query to identify your profit and loss transactions with ‘--pnl’. + + If you do not record changes in the value of your investment +manually, or do not require computation of time-weighted return (TWR), +‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’ +does not match any of your accounts). + + This command 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. + + Price directives will be taken into account if you supply appropriate +‘--cost’ or ‘--value’ flags (see VALUATION). + + Note, in some cases this report can fail, for these reasons: + + • Error (NotBracketed): No solution for Internal Rate of Return + (IRR). Possible causes: IRR is huge (>1000000%), balance of + investment becomes negative at some point in time. + • Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or + converges too slowly. + + Examples: + + • Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger + + • Cookbook > Return on Investment: https://hledger.org/roi.html + +* Menu: + +* Spaces and special characters in --inv and --pnl:: +* Semantics of --inv and --pnl:: +* IRR and TWR explained:: + + +File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi + +24.26.1 Spaces and special characters in ‘--inv’ and +---------------------------------------------------- + +‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries +could have several space-separated terms (see QUERIES). + + To indicate that all search terms form single command-line argument, +you will need to put them in quotes (see Special characters): + +$ hledger roi --inv 'term1 term2 term3 ...' + + If any query terms contain spaces themselves, you will need an extra +level of nested quoting, eg: + +$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" + + +File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi + +24.26.2 Semantics of ‘--inv’ and ‘--pnl’ +---------------------------------------- + +Query supplied to ‘--inv’ has to match all transactions that are related +to your investment. Transactions not matching ‘--inv’ will be ignored. + + In these transactions, ROI will conside postings that match ‘--inv’ +to be "investment postings" and other postings (not matching ‘--inv’) +will be sorted into two categories: "cash flow" and "profit and loss", +as ROI needs to know which part of the investment value is your +contributions and which is due to the return on investment. + + • "Cash flow" is depositing or withdrawing money, buying or selling + assets, or otherwise converting between your investment commodity + and any other commodity. Example: + + 2019-01-01 Investing in Snake Oil + assets:cash -$100 + investment:snake oil + + 2020-01-01 Selling my Snake Oil + assets:cash $10 + investment:snake oil = 0 + + • "Profit and loss" is change in the value of your investment: + + 2019-06-01 Snake Oil falls in value + investment:snake oil = $57 + equity:unrealized profit or loss + + All non-investment postings are assumed to be "cash flow", unless +they match ‘--pnl’ query. Changes in value of your investment due to +"profit and loss" postings will be considered as part of your investment +return. + + Example: if you use ‘--inv snake --pnl equity:unrealized’, then +postings in the example below would be classifed as: + +2019-01-01 Snake Oil #1 + assets:cash -$100 ; cash flow posting + investment:snake oil ; investment posting + +2019-03-01 Snake Oil #2 + equity:unrealized pnl -$100 ; profit and loss posting + snake oil ; investment posting + +2019-07-01 Snake Oil #3 + equity:unrealized pnl ; profit and loss posting + cash -$100 ; cash flow posting + snake oil $50 ; investment posting + + +File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi + +24.26.3 IRR and TWR explained +----------------------------- + +"ROI" stands for "return on investment". Traditionally this was +computed as a difference between current value of investment and its +initial value, expressed in percentage of the initial value. + + However, this approach is only practical in simple cases, where +investments receives no in-flows or out-flows of money, and where rate +of growth is fixed over time. For more complex scenarios you need +different ways to compute rate of return, and this command implements +two of them: IRR and TWR. + + Internal rate of return, or "IRR" (also called "money-weighted rate +of return") takes into account effects of in-flows and out-flows. +Naively, if you are withdrawing from your investment, your future gains +would be smaller (in absolute numbers), and will be a smaller percentage +of your initial investment, and if you are adding to your investment, +you will receive bigger absolute gains (but probably at the same rate of +return). IRR is a way to compute rate of return for each period between +in-flow or out-flow of money, and then combine them in a way that gives +you a compound annual rate of return that investment is expected to +generate. + + As mentioned before, in-flows and out-flows would be any cash that +you personally put in or withdraw, and for the "roi" command, these are +the postings that match the query in the‘--inv’ argument and NOT match +the query in the‘--pnl’ argument. + + If you manually record changes in the value of your investment as +transactions that balance them against "profit and loss" (or "unrealized +gains") account or use price directives, then in order for IRR to +compute the precise effect of your in-flows and out-flows on the rate of +return, you will need to record the value of your investement on or +close to the days when in- or out-flows occur. + + In technical terms, IRR uses the same approach as computation of net +present value, and tries to find a discount rate that makes net present +value of all the cash flows of your investment to add up to zero. This +could be hard to wrap your head around, especially if you haven’t done +discounted cash flow analysis before. Implementation of IRR in hledger +should produce results that match the ‘XIRR’ formula in Excel. + + Second way to compute rate of return that ‘roi’ command implements is +called "time-weighted rate of return" or "TWR". Like IRR, it will also +break the history of your investment into periods between in-flows, +out-flows and value changes, to compute rate of return per each period +and then a compound rate of return. However, internal workings of TWR +are quite different. + + TWR represents your investment as an imaginary "unit fund" where +in-flows/ out-flows lead to buying or selling "units" of your investment +and changes in its value change the value of "investment unit". Change +in "unit price" over the reporting period gives you rate of return of +your investment. + + References: + + • Explanation of rate of return + • Explanation of IRR + • Explanation of TWR + • Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS + +24.27 stats +=========== + +Show journal and performance 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. + + At the end, it shows (in the terminal) the overall run time and +number of transactions processed per second. Note these are approximate +and will vary based on machine, current load, data size, hledger +version, haskell lib versions, GHC version.. but they may be of +interest. The ‘stats’ command’s run time is similar to that of a +single-column balance report. + + Example: + +$ hledger stats -f examples/1000x1000x10.journal +Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal +Included files : +Transactions span : 2000-01-01 to 2002-09-27 (1000 days) +Last transaction : 2002-09-26 (6995 days ago) +Transactions : 1000 (1.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) +Market prices : 1000 (A) + +Run time : 0.12 s +Throughput : 8342 txns/s + + This command supports the -o/–output-file option (but not +-O/–output-format selection). + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS + +24.28 tags +========== + +List the tags used in the journal, or their values. + + This command lists the tag names used in the journal, whether on +transactions, postings, or account declarations. + + With a TAGREGEX argument, only tag names matching this regular +expression (case insensitive, infix matched) are shown. + + With QUERY arguments, only transactions and accounts matching this +query are considered. If the query involves transaction fields (date:, +desc:, amt:, ...), the search is restricted to the matched transactions +and their accounts. + + With the –values flag, the tags’ unique non-empty values are listed +instead. With -E/–empty, blank/empty values are also shown. + + With –parsed, tags or values are shown in the order they were parsed, +with duplicates included. (Except, tags from account declarations are +always shown first.) + + Tip: remember, accounts also acquire tags from their parents, +postings also acquire tags from their account and transaction, +transactions also acquire tags from their postings. + + +File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS + +24.29 test +========== + +Run built-in unit tests. + + This command runs the unit tests built in to hledger and hledger-lib, +printing the results on stdout. If any test fails, the exit code will +be non-zero. + + This is mainly used by hledger developers, but you can also use it to +sanity-check the installed hledger executable on your platform. All +tests are expected to pass - if you ever see a failure, please report as +a bug! + + This command also accepts tasty test runner options, written after a +– (double hyphen). Eg to run only the tests in Hledger.Data.Amount, +with ANSI colour codes disabled: + +$ hledger test -- -pData.Amount --color=never + + For help on these, see https://github.com/feuerbach/tasty#options +(‘-- --help’ currently doesn’t show them). + + +File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top + +25 PART 5: COMMON TASKS +*********************** + +Here are some quick examples of how to do some basic tasks with hledger. + +* Menu: + +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file:: + + +File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS + +25.1 Getting help +================= + +Here’s how to list commands and view options and command docs: + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version’s manual in several formats by +using the help command. Eg: + +$ hledger help # show the hledger manual with info, man or $PAGER (best available) +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit +https://hledger.org. Chat and mail list support and discussion archives +can be found at https://hledger.org/support. + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS + +25.2 Constructing command lines +=============================== + +hledger has a flexible command line interface. We strive to keep it +simple and ergonomic, but if you run into one of the sharp edges +described in OPTIONS, here are some tips that might help: + + • command-specific options must go after the command (it’s fine to + put common options there too: ‘hledger CMD OPTS ARGS’) + • running add-on executables directly simplifies command line parsing + (‘hledger-ui OPTS ARGS’) + • enclose "problematic" args in single quotes + • if needed, also add a backslash to hide regular expression + metacharacters from the shell + • to see how a misbehaving command line is being parsed, add + ‘--debug=2’. + + +File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS + +25.3 Starting a journal file +============================ + +hledger looks for your accounting data in a journal file, +‘$HOME/.hledger.journal’ by default: + +$ hledger stats +The hledger journal file "/Users/simon/.hledger.journal" was not found. +Please create it first, eg with "hledger add" or a text editor. +Or, specify an existing journal file with -f or LEDGER_FILE. + + You can override this by setting the ‘LEDGER_FILE’ environment +variable. It’s a good practice to keep this important file under +version control, and to start a new file each year. So you could do +something like this: + +$ mkdir ~/finance +$ cd ~/finance +$ git init +Initialized empty Git repository in /Users/simon/finance/.git/ +$ touch 2020.journal +$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc +$ source ~/.bashrc +$ hledger stats +Main file : /Users/simon/finance/2020.journal +Included files : +Transactions span : to (0 days) +Last transaction : none +Transactions : 0 (0.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 0 +Accounts : 0 (depth 0) +Commodities : 0 () +Market prices : 0 () + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS + +25.4 Setting opening balances +============================= + +Pick a starting date for which you can look up the balances of some +real-world assets (bank accounts, wallet..) and liabilities (credit +cards..). + + To avoid a lot of data entry, you may want to start with just one or +two accounts, like your checking account or cash wallet; and pick a +recent starting date, like today or the start of the week. You can +always come back later and add more accounts and older transactions, eg +going back to january 1st. + + Add an opening balances transaction to the journal, declaring the +balances on this date. Here are two ways to do it: + + • The first way: open the journal in any text editor and save an + entry like this: + + 2020-01-01 * opening balances + assets:bank:checking $1000 = $1000 + assets:bank:savings $2000 = $2000 + assets:cash $100 = $100 + liabilities:creditcard $-50 = $-50 + equity:opening/closing balances + + These are start-of-day balances, ie whatever was in the account at + the end of the previous day. + + The * after the date is an optional status flag. Here it means + "cleared & confirmed". + + The currency symbols are optional, but usually a good idea as + you’ll be dealing with multiple currencies sooner or later. + + The = amounts are optional balance assertions, providing extra + error checking. + + • The second way: run ‘hledger add’ and follow the prompts to record + a similar transaction: + + $ hledger add + Adding transactions to journal file /Users/simon/finance/2020.journal + 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 go one step backward. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2020-02-07]: 2020-01-01 + Description: * opening balances + Account 1: assets:bank:checking + Amount 1: $1000 + Account 2: assets:bank:savings + Amount 2 [$-1000]: $2000 + Account 3: assets:cash + Amount 3 [$-3000]: $100 + Account 4: liabilities:creditcard + Amount 4 [$-3100]: $-50 + Account 5: equity:opening/closing balances + Amount 5 [$-3050]: + Account 6 (or . or enter to finish this transaction): . + 2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2020-01-01]: . + + If you’re using version control, this could be a good time to commit +the journal. Eg: + +$ git commit -m 'initial balances' 2020.journal + + +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS + +25.5 Recording transactions +=========================== + +As you spend or receive money, you can record these transactions using +one of the methods above (text editor, hledger add) or by using the +hledger-iadd or hledger-web add-ons, or by using the import command to +convert CSV data downloaded from your bank. + + Here are some simple transactions, see the hledger_journal(5) manual +and hledger.org for more ideas: + +2020/1/10 * gift received + assets:cash $20 + income:gifts + +2020.1.12 * farmers market + expenses:food $13 + assets:cash + +2020-01-15 paycheck + income:salary + assets:bank:checking $1000 + + +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS + +25.6 Reconciling +================ + +Periodically you should reconcile - compare your hledger-reported +balances against external sources of truth, like bank statements or your +bank’s website - to be sure that your ledger accurately represents the +real-world balances (and, that the real-world institutions have not made +a mistake!). This gets easy and fast with (1) practice and (2) +frequency. If you do it daily, it can take 2-10 minutes. If you let it +pile up, expect it to take longer as you hunt down errors and +discrepancies. + + A typical workflow: + + 1. Reconcile cash. Count what’s in your wallet. Compare with what + hledger reports (‘hledger bal cash’). If they are different, try + to remember the missing transaction, or look for the error in the + already-recorded transactions. A register report can be helpful + (‘hledger reg cash’). If you can’t find the error, add an + adjustment transaction. Eg if you have $105 after the above, and + can’t explain the missing $2, it could be: + + 2020-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + 2. Reconcile checking. Log in to your bank’s website. Compare + today’s (cleared) balance with hledger’s cleared balance (‘hledger + bal checking -C’). If they are different, track down the error or + record the missing transaction(s) or add an adjustment transaction, + similar to the above. Unlike the cash case, you can usually + compare the transaction history and running balance from your bank + with the one reported by ‘hledger reg checking -C’. This will be + easier if you generally record transaction dates quite similar to + your bank’s clearing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a +live-updating register while you edit the journal: ‘hledger-ui --watch +--register checking -C’ + + After reconciling, it could be a good time to mark the reconciled +transactions’ status as "cleared and confirmed", if you want to track +that, by adding the ‘*’ marker. Eg in the paycheck transaction above, +insert ‘*’ between ‘2020-01-15’ and ‘paycheck’ + + If you’re using version control, this can be another good time to +commit: + +$ git commit -m 'txns' 2020.journal + + +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS + +25.7 Reporting +============== + +Here are some basic reports. + + Show all transactions: + +$ hledger print +2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +2020-01-10 * gift received + assets:cash $20 + income:gifts + +2020-01-12 * farmers market + expenses:food $13 + assets:cash + +2020-01-15 * paycheck + income:salary + assets:bank:checking $1000 + +2020-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + +$ hledger accounts --tree +assets + bank + checking + savings + cash +equity + opening/closing balances +expenses + food + misc +income + gifts + salary +liabilities + creditcard + + Show all account totals: + +$ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard +-------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to +depth 2: + +$ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard +-------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple +balance sheet: + +$ hledger bs -2 +Balance Sheet 2020-01-16 + + || 2020-01-16 +========================++============ + Assets || +------------------------++------------ + assets:bank || $4000 + assets:cash || $105 +------------------------++------------ + || $4105 +========================++============ + Liabilities || +------------------------++------------ + liabilities:creditcard || $50 +------------------------++------------ + || $50 +========================++============ + Net: || $4055 + + The final total is your "net worth" on the end date. (Or use ‘bse’ +for a full balance sheet with equity.) + + Show income and expense totals, formatted as an income statement: + +hledger is +Income Statement 2020-01-01-2020-01-16 + + || 2020-01-01-2020-01-16 +===============++======================= + Revenues || +---------------++----------------------- + income:gifts || $20 + income:salary || $1000 +---------------++----------------------- + || $1020 +===============++======================= + Expenses || +---------------++----------------------- + expenses:food || $13 + expenses:misc || $2 +---------------++----------------------- + || $15 +===============++======================= + Net: || $1005 + + The final total is your net income during this period. + + Show transactions affecting your wallet, with running total: + +$ hledger register cash +2020-01-01 opening balances assets:cash $100 $100 +2020-01-10 gift received assets:cash $20 $120 +2020-01-12 farmers market assets:cash $-13 $107 +2020-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + +$ hledger activity -W +2019-12-30 ***** +2020-01-06 **** +2020-01-13 **** + + +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS + +25.8 Migrating to a new file +============================ + +At the end of the year, you may want to continue your journal in a new +file, so that old transactions don’t slow down or clutter your reports, +and to help ensure the integrity of your accounting history. See the +close command. + + If using version control, don’t forget to ‘git add’ the new file. + + +Tag Table: +Node: Top210 +Node: PART 1 USER INTERFACE3946 +Ref: #part-1-user-interface4087 +Node: Options4087 +Ref: #options4206 +Node: General options4348 +Ref: #general-options4473 +Node: Command options8923 +Ref: #command-options9074 +Node: Command arguments9490 +Ref: #command-arguments9648 +Node: Special characters10550 +Ref: #special-characters10713 +Node: Single escaping shell metacharacters10876 +Ref: #single-escaping-shell-metacharacters11117 +Node: Double escaping regular expression metacharacters11752 +Ref: #double-escaping-regular-expression-metacharacters12063 +Node: Triple escaping for add-on commands12633 +Ref: #triple-escaping-for-add-on-commands12893 +Node: Less escaping13561 +Ref: #less-escaping13715 +Node: Unicode characters14053 +Ref: #unicode-characters14218 +Node: Regular expressions15650 +Ref: #regular-expressions15790 +Node: Environment17644 +Ref: #environment17755 +Node: Input19366 +Ref: #input19466 +Node: Data formats20029 +Ref: #data-formats20142 +Node: Multiple files21594 +Ref: #multiple-files21731 +Node: Strict mode22216 +Ref: #strict-mode22326 +Node: Commands23080 +Ref: #commands23181 +Node: Add-on commands23665 +Ref: #add-on-commands23767 +Node: Output24934 +Ref: #output25037 +Node: Output destination25153 +Ref: #output-destination25284 +Node: Output format25713 +Ref: #output-format25859 +Node: CSV output27431 +Ref: #csv-output27547 +Node: HTML output27652 +Ref: #html-output27790 +Node: JSON output27890 +Ref: #json-output28028 +Node: SQL output28960 +Ref: #sql-output29076 +Node: Commodity styles29599 +Ref: #commodity-styles29739 +Node: Colour30346 +Ref: #colour30464 +Node: Box-drawing30898 +Ref: #box-drawing31022 +Node: Debug output31336 +Ref: #debug-output31447 +Node: Limitations32122 +Ref: #limitations32242 +Node: Troubleshooting33017 +Ref: #troubleshooting33158 +Node: PART 2 DATA FORMATS35680 +Ref: #part-2-data-formats35827 +Node: Journal35827 +Ref: #journal35938 +Node: Journal cheatsheet36581 +Ref: #journal-cheatsheet36722 +Node: About journal format40710 +Ref: #about-journal-format40872 +Node: Comments42410 +Ref: #comments42542 +Node: Transactions43396 +Ref: #transactions43521 +Node: Dates44555 +Ref: #dates44664 +Node: Simple dates44709 +Ref: #simple-dates44827 +Node: Posting dates45359 +Ref: #posting-dates45479 +Node: Status46462 +Ref: #status46565 +Node: Code48317 +Ref: #code48422 +Node: Description48654 +Ref: #description48787 +Node: Payee and note49109 +Ref: #payee-and-note49217 +Node: Transaction comments49564 +Ref: #transaction-comments49719 +Node: Postings50090 +Ref: #postings50225 +Node: Account names51234 +Ref: #account-names51366 +Node: Amounts53068 +Ref: #amounts53185 +Node: Decimal marks digit group marks54174 +Ref: #decimal-marks-digit-group-marks54351 +Node: Commodity55375 +Ref: #commodity55564 +Node: Directives influencing number parsing and display56546 +Ref: #directives-influencing-number-parsing-and-display56807 +Node: Commodity display style57269 +Ref: #commodity-display-style57477 +Node: Rounding59688 +Ref: #rounding59808 +Node: Costs60109 +Ref: #costs60227 +Node: Other cost/lot notations62258 +Ref: #other-costlot-notations62392 +Node: Balance assertions65145 +Ref: #balance-assertions65298 +Node: Assertions and ordering66391 +Ref: #assertions-and-ordering66582 +Node: Assertions and multiple included files67284 +Ref: #assertions-and-multiple-included-files67546 +Node: Assertions and multiple -f files68054 +Ref: #assertions-and-multiple--f-files68307 +Node: Assertions and commodities68716 +Ref: #assertions-and-commodities68940 +Node: Assertions and prices70130 +Ref: #assertions-and-prices70338 +Node: Assertions and subaccounts70769 +Ref: #assertions-and-subaccounts70992 +Node: Assertions and virtual postings71334 +Ref: #assertions-and-virtual-postings71574 +Node: Assertions and auto postings71714 +Ref: #assertions-and-auto-postings71946 +Node: Assertions and precision72617 +Ref: #assertions-and-precision72801 +Node: Posting comments73068 +Ref: #posting-comments73216 +Node: Tags73601 +Ref: #tags73717 +Node: Tag values74922 +Ref: #tag-values75013 +Node: Directives75786 +Ref: #directives75915 +Node: Directive effects77783 +Ref: #directive-effects77939 +Node: Directives and multiple files81022 +Ref: #directives-and-multiple-files81202 +Node: account directive81912 +Ref: #account-directive82074 +Node: Account comments83494 +Ref: #account-comments83646 +Node: Account subdirectives84166 +Ref: #account-subdirectives84359 +Node: Account error checking84501 +Ref: #account-error-checking84701 +Node: Account display order85920 +Ref: #account-display-order86110 +Node: Account types87249 +Ref: #account-types87392 +Node: alias directive91127 +Ref: #alias-directive91294 +Node: Basic aliases92354 +Ref: #basic-aliases92487 +Node: Regex aliases93241 +Ref: #regex-aliases93400 +Node: Combining aliases94294 +Ref: #combining-aliases94474 +Node: Aliases and multiple files95768 +Ref: #aliases-and-multiple-files95974 +Node: end aliases directive96559 +Ref: #end-aliases-directive96784 +Node: Aliases can generate bad account names96933 +Ref: #aliases-can-generate-bad-account-names97183 +Node: Aliases and account types97780 +Ref: #aliases-and-account-types97974 +Node: commodity directive98676 +Ref: #commodity-directive98856 +Node: Commodity error checking101460 +Ref: #commodity-error-checking101608 +Node: decimal-mark directive102137 +Ref: #decimal-mark-directive102325 +Node: include directive102726 +Ref: #include-directive102896 +Node: P directive103844 +Ref: #p-directive103995 +Node: payee directive104894 +Ref: #payee-directive105049 +Node: tag directive105369 +Ref: #tag-directive105530 +Node: Periodic transactions106002 +Ref: #periodic-transactions106168 +Node: Periodic rule syntax107906 +Ref: #periodic-rule-syntax108086 +Node: Periodic rules and relative dates108741 +Ref: #periodic-rules-and-relative-dates109009 +Node: Two spaces between period expression and description!109548 +Ref: #two-spaces-between-period-expression-and-description109827 +Node: Other syntax110517 +Ref: #other-syntax110643 +Node: Auto postings111288 +Ref: #auto-postings111424 +Node: Auto postings and multiple files113935 +Ref: #auto-postings-and-multiple-files114137 +Node: Auto postings and dates114354 +Ref: #auto-postings-and-dates114626 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions114801 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115140 +Node: Auto posting tags115647 +Ref: #auto-posting-tags115860 +Node: Balance assignments116522 +Ref: #balance-assignments116702 +Node: Balance assignments and prices118036 +Ref: #balance-assignments-and-prices118206 +Node: Bracketed posting dates118417 +Ref: #bracketed-posting-dates118603 +Node: D directive119147 +Ref: #d-directive119321 +Node: apply account directive120989 +Ref: #apply-account-directive121175 +Node: Y directive121874 +Ref: #y-directive122040 +Node: Secondary dates122884 +Ref: #secondary-dates123040 +Node: Star comments123872 +Ref: #star-comments124034 +Node: Valuation expressions124574 +Ref: #valuation-expressions124753 +Node: Virtual postings124875 +Ref: #virtual-postings125056 +Node: Other Ledger directives126628 +Ref: #other-ledger-directives126793 +Node: CSV127363 +Ref: #csv127456 +Node: CSV rules cheatsheet129559 +Ref: #csv-rules-cheatsheet129691 +Node: separator131459 +Ref: #separator131590 +Node: skip132168 +Ref: #skip132280 +Node: date-format132863 +Ref: #date-format132988 +Node: timezone133734 +Ref: #timezone133861 +Node: newest-first134894 +Ref: #newest-first135036 +Node: intra-day-reversed135620 +Ref: #intra-day-reversed135778 +Node: decimal-mark136275 +Ref: #decimal-mark136420 +Node: fields list136759 +Ref: #fields-list136900 +Node: Field assignment138623 +Ref: #field-assignment138767 +Node: Field names139816 +Ref: #field-names139947 +Node: date field141168 +Ref: #date-field141286 +Node: date2 field141338 +Ref: #date2-field141479 +Node: status field141541 +Ref: #status-field141684 +Node: code field141739 +Ref: #code-field141884 +Node: description field141935 +Ref: #description-field142095 +Node: comment field142160 +Ref: #comment-field142315 +Node: account field142628 +Ref: #account-field142778 +Node: amount field143374 +Ref: #amount-field143523 +Node: currency field145628 +Ref: #currency-field145781 +Node: balance field146050 +Ref: #balance-field146182 +Node: if block146570 +Ref: #if-block146695 +Node: Matchers148119 +Ref: #matchers148233 +Node: if table149763 +Ref: #if-table149889 +Node: balance-type151325 +Ref: #balance-type151458 +Node: include152166 +Ref: #include152297 +Node: Working with CSV152747 +Ref: #working-with-csv152894 +Node: Rapid feedback153265 +Ref: #rapid-feedback153398 +Node: Valid CSV153854 +Ref: #valid-csv154000 +Node: File Extension154754 +Ref: #file-extension154927 +Node: Reading CSV from standard input155517 +Ref: #reading-csv-from-standard-input155741 +Node: Reading multiple CSV files155907 +Ref: #reading-multiple-csv-files156125 +Node: Valid transactions156374 +Ref: #valid-transactions156568 +Node: Deduplicating importing157196 +Ref: #deduplicating-importing157391 +Node: Setting amounts158437 +Ref: #setting-amounts158608 +Node: Amount signs161131 +Ref: #amount-signs161299 +Node: Setting currency/commodity162038 +Ref: #setting-currencycommodity162242 +Node: Amount decimal places163434 +Ref: #amount-decimal-places163640 +Node: Referencing other fields163958 +Ref: #referencing-other-fields164171 +Node: How CSV rules are evaluated165074 +Ref: #how-csv-rules-are-evaluated165291 +Node: Well factored rules166804 +Ref: #well-factored-rules166972 +Node: CSV rules examples167310 +Ref: #csv-rules-examples167445 +Node: Bank of Ireland167510 +Ref: #bank-of-ireland167647 +Node: Coinbase169115 +Ref: #coinbase169253 +Node: Amazon170306 +Ref: #amazon170431 +Node: Paypal172156 +Ref: #paypal172264 +Node: Timeclock179910 +Ref: #timeclock180015 +Node: Timedot182183 +Ref: #timedot182306 +Node: PART 3 REPORTING CONCEPTS187157 +Ref: #part-3-reporting-concepts187321 +Node: Time periods187321 +Ref: #time-periods187455 +Node: Report start & end date187573 +Ref: #report-start-end-date187725 +Node: Smart dates189458 +Ref: #smart-dates189611 +Node: Report intervals191571 +Ref: #report-intervals191726 +Node: Date adjustment192178 +Ref: #date-adjustment192338 +Node: Period expressions193670 +Ref: #period-expressions193811 +Node: Period expressions with a report interval195647 +Ref: #period-expressions-with-a-report-interval195881 +Node: More complex report intervals196111 +Ref: #more-complex-report-intervals196356 +Node: Multiple weekday intervals198285 +Ref: #multiple-weekday-intervals198474 +Node: Depth199338 +Ref: #depth199440 +Node: Queries199760 +Ref: #queries199862 +Node: Query types200807 +Ref: #query-types200928 +Node: Combining query terms204268 +Ref: #combining-query-terms204445 +Node: Queries and command options205543 +Ref: #queries-and-command-options205742 +Node: Queries and valuation206007 +Ref: #queries-and-valuation206202 +Node: Querying with account aliases206441 +Ref: #querying-with-account-aliases206652 +Node: Querying with cost or value206794 +Ref: #querying-with-cost-or-value206971 +Node: Pivoting207280 +Ref: #pivoting207394 +Node: Generating data208882 +Ref: #generating-data209014 +Node: Forecasting209512 +Ref: #forecasting209637 +Node: Budgeting212524 +Ref: #budgeting212644 +Node: Cost reporting212915 +Ref: #cost-reporting213043 +Node: -B Convert to cost214158 +Ref: #b-convert-to-cost214314 +Node: Equity conversion postings215722 +Ref: #equity-conversion-postings215936 +Node: Inferring equity postings from cost216831 +Ref: #inferring-equity-postings-from-cost217080 +Node: Inferring cost from equity postings217899 +Ref: #inferring-cost-from-equity-postings218147 +Node: When to infer cost/equity219956 +Ref: #when-to-infer-costequity220174 +Node: How to record conversions220582 +Ref: #how-to-record-conversions220774 +Node: Conversion with implicit cost221065 +Ref: #conversion-with-implicit-cost221270 +Node: Conversion with explicit cost222175 +Ref: #conversion-with-explicit-cost222420 +Node: Conversion with equity postings222847 +Ref: #conversion-with-equity-postings223116 +Node: Conversion with equity postings and explicit cost223953 +Ref: #conversion-with-equity-postings-and-explicit-cost224220 +Node: Cost tips224694 +Ref: #cost-tips224820 +Node: Valuation225556 +Ref: #valuation225680 +Node: -V Value226466 +Ref: #v-value226592 +Node: -X Value in specified commodity226791 +Ref: #x-value-in-specified-commodity226986 +Node: Valuation date227143 +Ref: #valuation-date227314 +Node: Finding market price227753 +Ref: #finding-market-price227958 +Node: --infer-market-prices market prices from transactions229138 +Ref: #infer-market-prices-market-prices-from-transactions229416 +Node: Valuation commodity232262 +Ref: #valuation-commodity232475 +Node: Simple valuation examples233720 +Ref: #simple-valuation-examples233918 +Node: --value Flexible valuation234581 +Ref: #value-flexible-valuation234787 +Node: More valuation examples236473 +Ref: #more-valuation-examples236682 +Node: Interaction of valuation and queries238693 +Ref: #interaction-of-valuation-and-queries238934 +Node: Effect of valuation on reports239414 +Ref: #effect-of-valuation-on-reports239611 +Node: PART 4 COMMANDS247370 +Ref: #part-4-commands247513 +Node: Commands overview247883 +Ref: #commands-overview248017 +Node: DATA ENTRY248196 +Ref: #data-entry248320 +Node: DATA CREATION248523 +Ref: #data-creation248677 +Node: DATA MANAGEMENT248801 +Ref: #data-management248966 +Node: REPORTS FINANCIAL249091 +Ref: #reports-financial249266 +Node: REPORTS VERSATILE249581 +Ref: #reports-versatile249754 +Node: REPORTS BASIC250015 +Ref: #reports-basic250167 +Node: HELP250700 +Ref: #help250822 +Node: ADD-ONS250881 +Ref: #add-ons250987 +Node: accounts251584 +Ref: #accounts251717 +Node: activity253692 +Ref: #activity253811 +Node: add254185 +Ref: #add254295 +Node: aregister257156 +Ref: #aregister257277 +Node: aregister and custom posting dates260253 +Ref: #aregister-and-custom-posting-dates260419 +Node: balance260987 +Ref: #balance261113 +Node: balance features262118 +Ref: #balance-features262258 +Node: Simple balance report264388 +Ref: #simple-balance-report264573 +Node: Balance report line format266218 +Ref: #balance-report-line-format266420 +Node: Filtered balance report268670 +Ref: #filtered-balance-report268862 +Node: List or tree mode269189 +Ref: #list-or-tree-mode269357 +Node: Depth limiting270732 +Ref: #depth-limiting270898 +Node: Dropping top-level accounts271515 +Ref: #dropping-top-level-accounts271715 +Node: Showing declared accounts272029 +Ref: #showing-declared-accounts272228 +Node: Sorting by amount272769 +Ref: #sorting-by-amount272936 +Node: Percentages273626 +Ref: #percentages273785 +Node: Multi-period balance report274355 +Ref: #multi-period-balance-report274555 +Node: Balance change end balance276948 +Ref: #balance-change-end-balance277157 +Node: Balance report types278605 +Ref: #balance-report-types278786 +Node: Calculation type279302 +Ref: #calculation-type279457 +Node: Accumulation type279988 +Ref: #accumulation-type280168 +Node: Valuation type281096 +Ref: #valuation-type281284 +Node: Combining balance report types282351 +Ref: #combining-balance-report-types282545 +Node: Budget report284449 +Ref: #budget-report284601 +Node: Budget report start date290335 +Ref: #budget-report-start-date290513 +Node: Budgets and subaccounts291875 +Ref: #budgets-and-subaccounts292082 +Node: Selecting budget goals295568 +Ref: #selecting-budget-goals295767 +Node: Budget vs forecast296814 +Ref: #budget-vs-forecast296973 +Node: Data layout298673 +Ref: #data-layout298823 +Node: Useful balance reports306764 +Ref: #useful-balance-reports306914 +Node: balancesheet308067 +Ref: #balancesheet308212 +Node: balancesheetequity309578 +Ref: #balancesheetequity309736 +Node: cashflow311179 +Ref: #cashflow311310 +Node: check312796 +Ref: #check312910 +Node: Basic checks313716 +Ref: #basic-checks313836 +Node: Strict checks314374 +Ref: #strict-checks314517 +Node: Other checks314958 +Ref: #other-checks315100 +Node: Custom checks315677 +Ref: #custom-checks315834 +Node: More about specific checks316255 +Ref: #more-about-specific-checks316417 +Node: close317149 +Ref: #close317260 +Node: close and costs319898 +Ref: #close-and-costs320042 +Node: close and balance assertions320331 +Ref: #close-and-balance-assertions320533 +Node: Example retain earnings321704 +Ref: #example-retain-earnings321921 +Node: Example migrate balances to a new file322279 +Ref: #example-migrate-balances-to-a-new-file322544 +Node: Example excluding closing/opening transactions323097 +Ref: #example-excluding-closingopening-transactions323346 +Node: codes324524 +Ref: #codes324641 +Node: commodities325517 +Ref: #commodities325653 +Node: descriptions325723 +Ref: #descriptions325860 +Node: diff326151 +Ref: #diff326266 +Node: files327312 +Ref: #files327421 +Node: help327562 +Ref: #help-1327671 +Node: import328661 +Ref: #import328784 +Node: Deduplication329892 +Ref: #deduplication330017 +Node: Import testing331939 +Ref: #import-testing332104 +Node: Importing balance assignments332955 +Ref: #importing-balance-assignments333161 +Node: Commodity display styles333818 +Ref: #commodity-display-styles333991 +Node: incomestatement334120 +Ref: #incomestatement334262 +Node: notes335629 +Ref: #notes335751 +Node: payees336113 +Ref: #payees336228 +Node: prices336753 +Ref: #prices336868 +Node: print337170 +Ref: #print337285 +Node: register342731 +Ref: #register342853 +Node: Custom register output347962 +Ref: #custom-register-output348093 +Node: rewrite349468 +Ref: #rewrite349586 +Node: Re-write rules in a file351498 +Ref: #re-write-rules-in-a-file351661 +Node: Diff output format352814 +Ref: #diff-output-format352997 +Node: rewrite vs print --auto354109 +Ref: #rewrite-vs.-print---auto354271 +Node: roi354845 +Ref: #roi354952 +Node: Spaces and special characters in --inv and --pnl356713 +Ref: #spaces-and-special-characters-in---inv-and---pnl356961 +Node: Semantics of --inv and --pnl357459 +Ref: #semantics-of---inv-and---pnl357706 +Node: IRR and TWR explained359584 +Ref: #irr-and-twr-explained359744 +Node: stats362856 +Ref: #stats362964 +Node: tags364361 +Ref: #tags-1364468 +Node: test365485 +Ref: #test365578 +Node: PART 5 COMMON TASKS366328 +Ref: #part-5-common-tasks366461 +Node: Getting help366735 +Ref: #getting-help366876 +Node: Constructing command lines367640 +Ref: #constructing-command-lines367841 +Node: Starting a journal file368522 +Ref: #starting-a-journal-file368729 +Node: Setting opening balances369927 +Ref: #setting-opening-balances370132 +Node: Recording transactions373285 +Ref: #recording-transactions373474 +Node: Reconciling374030 +Ref: #reconciling374182 +Node: Reporting376495 +Ref: #reporting376644 +Node: Migrating to a new file380633 +Ref: #migrating-to-a-new-file380790  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -18,8 +18,8 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.29. It - also describes the common options, file formats and concepts used by + This manual is for hledger's command line interface, version 1.29.1. + It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeep- ing/accounting as well! You don't need to know everything in here to use hledger productively, but when you have a question about function- @@ -8659,4 +8659,4 @@ -hledger-1.29 March 2023 HLEDGER(1) +hledger-1.29.1 March 2023 HLEDGER(1) diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "March 2023" "hledger-1.29 " "hledger User Manuals" +.TH "HLEDGER" "1" "March 2023" "hledger-1.29.1 " "hledger User Manuals" @@ -26,7 +26,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP -This manual is for hledger\[aq]s command line interface, version 1.29. +This manual is for hledger\[aq]s command line interface, version 1.29.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack name: hledger -version: 1.29 +version: 1.29.1 synopsis: Command-line interface for the hledger accounting system description: The command-line interface for the hledger accounting system. Its basic function is to read a plain text file describing @@ -131,13 +131,13 @@ other-modules: Paths_hledger ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.29" + cpp-options: -DVERSION="1.29.1" build-depends: Decimal >=0.5.1 , Diff >=0.2 , aeson >=1 , ansi-terminal >=0.9 - , base >=4.14 && <4.18 + , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9 @@ -148,7 +148,7 @@ , githash >=0.1.6.2 , hashable >=1.2.4 , haskeline >=0.6 - , hledger-lib ==1.29.* + , hledger-lib >=1.29.1 && <1.30 , lucid , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4 @@ -183,12 +183,12 @@ hs-source-dirs: app ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.29" + cpp-options: -DVERSION="1.29.1" build-depends: Decimal >=0.5.1 , aeson >=1 , ansi-terminal >=0.9 - , base >=4.14 && <4.18 + , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9 @@ -199,7 +199,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib ==1.29.* + , hledger-lib >=1.29.1 && <1.30 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4 , microlens >=0.4 @@ -234,12 +234,12 @@ hs-source-dirs: test ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.29" + cpp-options: -DVERSION="1.29.1" build-depends: Decimal >=0.5.1 , aeson >=1 , ansi-terminal >=0.9 - , base >=4.14 && <4.18 + , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9 @@ -250,7 +250,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib ==1.29.* + , hledger-lib >=1.29.1 && <1.30 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4 , microlens >=0.4 @@ -287,7 +287,7 @@ Decimal >=0.5.1 , aeson >=1 , ansi-terminal >=0.9 - , base >=4.14 && <4.18 + , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9 @@ -299,7 +299,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib ==1.29.* + , hledger-lib >=1.29.1 && <1.30 , html , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4 diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -23,10948 +23,10948 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger’s command line interface, version 1.29. -It also describes the common options, file formats and concepts used by -all hledger programs. It might accidentally teach you some -bookkeeping/accounting as well! You don’t need to know everything in -here to use hledger productively, but when you have a question about -functionality, this doc should answer it. It is detailed, so do skip -ahead or skim when needed. You can read it on hledger.org, or as an -info manual or man page on your system. You can also get it from -hledger itself with -‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’. - - The main function of the hledger CLI is to read plain text files -describing financial transactions, crunch the numbers, and print a -useful report on the terminal (or save it as HTML, CSV, JSON or SQL). -Many reports are available, as subcommands. hledger will also detect -other ‘hledger-*’ executables as extra subcommands. - - hledger reads data from one or more files in journal, timeclock, -timedot, or CSV format. The default file is ‘.hledger.journal’ in your -home directory; this can be overridden with one or more ‘-f FILE’ -options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can -also read from stdin with ‘-f-’; more on that below. - - Here is a small but valid hledger journal file describing one -transaction: - -2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more -_accounts_: bank accounts, your wallet, revenue/expense categories, -people, etc. You can choose any account names you wish, using ‘:’ to -indicate subaccounts. There must be at least two spaces between account -name and amount. Positive amounts are inflow to that account (_debit_), -negatives are outflow from it (_credit_). (Some reports show revenue, -liability and equity account balances as negative numbers as a result; -this is normal.) - - hledger’s add command can help you add transactions, or you can -install other data entry UIs like hledger-web or hledger-iadd. For more -extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM -+ vim-ledger, or VS Code + hledger-vscode are some good choices (see -https://hledger.org/editors.html). - - To get started, run ‘hledger add’ and follow the prompts, or save -some entries like the above in ‘$HOME/.hledger.journal’, then try -commands like: -‘hledger print -x’ -‘hledger aregister assets’ -‘hledger balance’ -‘hledger balancesheet’ -‘hledger incomestatement’. -Run ‘hledger’ to list the commands. See also the "Starting a journal -file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -* Menu: - -* PART 1 USER INTERFACE:: -* Options:: -* Environment:: -* Input:: -* Commands:: -* Output:: -* Limitations:: -* Troubleshooting:: -* PART 2 DATA FORMATS:: -* Journal:: -* CSV:: -* Timeclock:: -* Timedot:: -* PART 3 REPORTING CONCEPTS:: -* Time periods:: -* Depth:: -* Queries:: -* Pivoting:: -* Generating data:: -* Forecasting:: -* Budgeting:: -* Cost reporting:: -* Valuation:: -* PART 4 COMMANDS:: -* PART 5 COMMON TASKS:: - - -File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top - -1 PART 1: USER INTERFACE -************************ - - -File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top - -2 Options -********* - -* Menu: - -* General options:: -* Command options:: -* Command arguments:: -* Special characters:: -* Unicode characters:: -* 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 or COMMAND help -‘--man’ - - show general or COMMAND user manual with man -‘--info’ - - show general or COMMAND user manual with info -‘--version’ - - show general or ADDONCMD version -‘--debug[=N]’ - - show debug output (levels 1-9, default: 1) - - General input options: - -‘-f FILE --file=FILE’ - - use a different input file. For stdin, use - (default: - ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’) -‘--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’ - - disable balance assertion checks (note: does not disable balance - assignments) -‘-s --strict’ - - do extra error checking (check that all posted accounts are - declared) - - General reporting options: - -‘-b --begin=DATE’ - - include postings/txns on or after this date (will be adjusted to - preceding subperiod start when using a report interval) -‘-e --end=DATE’ - - include postings/txns before this date (will be adjusted to - following subperiod end when using a report interval) -‘-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 -‘--date2’ - - match the secondary date instead (see command help for other - effects) -‘--today=DATE’ - - override today’s date (affects relative smart dates, for - tests/examples) -‘-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/selling amount at transaction time -‘-V --market’ - - convert amounts to their market value in default valuation - commodities -‘-X --exchange=COMM’ - - convert amounts to their market value in commodity COMM -‘--value’ - - convert amounts to cost or market value, more flexibly than - -B/-V/-X -‘--infer-market-prices’ - - use transaction prices (recorded with @ or @@) as additional market - prices, as if they were P directives -‘--auto’ - - apply automated posting rules to modify transactions. -‘--forecast’ - - generate future transactions from periodic transaction rules, for - the next 6 months or till report end date. In hledger-ui, also - make ordinary future transactions visible. -‘--commodity-style’ - - Override the commodity style in the output for the specified - commodity. For example ’EUR1.000,00’. -‘--color=WHEN (or --colour=WHEN)’ - - Should color-supporting commands use ANSI color codes in text - output. ’auto’ (default): whenever stdout seems to be a - color-supporting terminal. ’always’ or ’yes’: always, useful eg - when piping output into ’less -R’. ’never’ or ’no’: never. A - NO_COLOR environment variable overrides this. -‘--pretty[=WHEN]’ - - Show prettier output, e.g. using unicode box-drawing characters. - Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’ - also work). If you provide an argument you must use ’=’, e.g. - ’–pretty=yes’. - - When a reporting option appears more than once in the command line, -the 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 add-on, you may need to put its -options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can -run the add-on executable directly: ‘hledger-ui --watch’. - - -File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options - -2.3 Command arguments -===================== - -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. - - You can save a set of command line options/arguments in a file, and -then reuse them by writing ‘@FILENAME’ as a command line argument. Eg: -‘hledger bal @foo.args’. (To prevent this, eg if you have an argument -that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal --- @ARG’). - - Inside the argument file, each line should contain just one option or -argument. Avoid the use of spaces, except inside quotes (or you’ll see -a confusing error). Between a flag and its argument, use = (or -nothing). Bad: - -assets depth:2 --X USD - - Good: - -assets -depth:2 --X=USD - - For special characters (see below), use one less level of quoting -than you would at the command prompt. Bad: - --X"$" - - Good: - --X$ - - See also: Save frequently used options. - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options - -2.4 Special characters -====================== - -* Menu: - -* Single escaping shell metacharacters:: -* Double escaping regular expression metacharacters:: -* Triple escaping for add-on commands:: -* Less escaping:: - - -File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters - -2.4.1 Single escaping (shell metacharacters) --------------------------------------------- - -In shell command lines, characters significant to your shell - such as -spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped" -if you want hledger to see them. This is done by enclosing them in -single or double quotes, or by writing a backslash before them. Eg to -match an account name containing a space: - -$ hledger register 'credit card' - - or: - -$ hledger register credit\ card - - Windows users should keep in mind that ‘cmd’ treats single quote as a -regular character, so you should be using double quotes exclusively. -PowerShell treats both single and double quotes as quotes. - - -File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters - -2.4.2 Double escaping (regular expression metacharacters) ---------------------------------------------------------- - -Characters significant in regular expressions (described below) - such -as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be -"regex-escaped" if you don’t want them to be interpreted by hledger’s -regular expression engine. This is done by writing backslashes before -them, but since backslash is typically also a shell metacharacter, both -shell-escaping and regex-escaping will be needed. Eg to match a literal -‘$’ sign while using the bash shell: - -$ hledger balance cur:'\$' - - or: - -$ hledger balance cur:\\$ - - -File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters - -2.4.3 Triple escaping (for add-on commands) -------------------------------------------- - -When you use hledger to run an external add-on command (described -below), one level of shell-escaping is lost from any options or -arguments intended for by the add-on command, so those need an extra -level of shell-escaping. Eg to match a literal ‘$’ sign while using the -bash shell and running an add-on command (‘ui’): - -$ hledger ui cur:'\\$' - - or: - -$ hledger ui cur:\\\\$ - - If you wondered why _four_ backslashes, perhaps this helps: - -unescaped: ‘$’ -escaped: ‘\$’ -double-escaped: ‘\\$’ -triple-escaped: ‘\\\\$’ - - Or, you can avoid the extra escaping by running the add-on executable -directly: - -$ hledger-ui cur:\\$ - - -File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters - -2.4.4 Less escaping -------------------- - -Options and arguments are sometimes used in places other than the shell -command line, where shell-escaping is not needed, so there you should -use one less level of escaping. Those places include: - - • an @argumentfile - • hledger-ui’s filter field - • hledger-web’s search form - • GHCI’s prompt (used by developers). - - -File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options - -2.5 Unicode characters -====================== - -hledger is expected to handle non-ascii characters correctly: - - • they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web’s - search/add/edit forms, etc.) - - • they should be displayed correctly by all hledger tools, and - on-screen alignment should be preserved. - - This requires a well-configured environment. Here are some tips: - - • A system locale must be configured, and it must be one that can - decode the characters being used. In bash, you can set a locale - like this: ‘export LANG=en_US.UTF-8’. There are some more details - in Troubleshooting. This step is essential - without it, hledger - will quit on encountering a non-ascii character (as with all - GHC-compiled programs). - - • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode - - • the terminal must be using a font which includes the required - unicode glyphs - - • the terminal should be configured to display wide characters as - double width (for report alignment) - - • on Windows, for best results you should run hledger in the same - kind of environment in which it was built. Eg hledger built in the - standard CMD.EXE environment (like the binaries on our download - page) might show display problems when run in a cygwin or msys - terminal, and vice versa. (See eg #961). - - -File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options - -2.6 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 directive and ‘--alias’ option: ‘alias /REGEX/ = - REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’ - - hledger’s regular expressions come from the regex-tdfa library. If -they’re not doing what you expect, it’s important to know exactly what -they support: - - 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing - being matched) - 3. they are POSIX ERE (extended regular expressions) - 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’) - 5. they do not support backreferences; if you write ‘\1’, it will - match the digit ‘1’. Except when doing text replacement, eg in - account aliases, where backreferences can be used in the - replacement string to reference capturing groups in the search - regexp. - 6. they do not support mode modifiers (‘(?s)’), character classes - (‘\w’, ‘\d’), or anything else not mentioned above. - - 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: Environment, Next: Input, Prev: Options, Up: Top - -3 Environment -************* - -*LEDGER_FILE* The journal file path when not specified with ‘-f’. - - On unix computers, the default value is: ‘~/.hledger.journal’. - - A more typical value is something like ‘~/finance/YYYY.journal’, -where ‘~/finance’ is a version-controlled finance directory and YYYY is -the current year. Or, ‘~/finance/current.journal’, where -current.journal is a symbolic link to YYYY.journal. - - The usual way to set this permanently is to add a command to one of -your shell’s startup files (eg ‘~/.profile’): - -export LEDGER_FILE=~/finance/current.journal` - - On some Mac computers, there is a more thorough way to set -environment variables, that will also affect applications started from -the GUI (eg, Emacs started from a dock icon): In -‘~/.MacOSX/environment.plist’, add an entry like: - -{ - "LEDGER_FILE" : "~/finance/current.journal" -} - - For this to take effect you might need to ‘killall Dock’, or reboot. - - On Windows computers, the default value is probably -‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a -command like this in a powershell window (let us know if you need to be -an Administrator, and if this persists across a reboot): - -> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - - Or, change it in settings: see -https://www.java.com/en/download/help/path.html. - - *COLUMNS* The screen width used by the register command. Default: -the full terminal width. - - *NO_COLOR* If this variable exists with any value, hledger will not -use ANSI color codes in terminal output. This is overriden by the -–color/–colour option. - - -File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top - -4 Input -******* - -hledger reads transactions from one or more data files. The default -data file is ‘$HOME/.hledger.journal’ (or on Windows, something like -‘C:\Users\YOURNAME\.hledger.journal’). - - You can override this with the ‘$LEDGER_FILE’ environment variable: - -$ setenv LEDGER_FILE ~/finance/2016.journal -$ hledger stats - - or with one or more ‘-f/--file’ options: - -$ hledger -f /some/file -f another_file stats - - The file name ‘-’ means standard input: - -$ cat some.journal | hledger -f- - -* Menu: - -* Data formats:: -* Multiple files:: -* Strict mode:: - - -File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input - -4.1 Data formats -================ - -Usually the data file is in hledger’s journal format, but it can be in -any of the supported file formats, which currently are: - -Reader: Reads: Used for file - extensions: --------------------------------------------------------------------------- -‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’ - journals, for transactions ‘.hledger’ ‘.ledger’ -‘timeclock’timeclock files, for precise time ‘.timeclock’ - logging -‘timedot’timedot files, for approximate time ‘.timedot’ - logging -‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’ - values, for data import - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions -shown above. If it can’t recognise the file extension, it assumes -‘journal’ format. So for non-journal files, it’s important to use a -recognised file extension, so as to either read successfully or to show -relevant error messages. - - You can also force a specific reader/format by prefixing the file -path with the format and a colon. Eg, to read a .dat file as csv -format: - -$ hledger -f csv:/some/csv-file.dat stats - - Or to read stdin (‘-’) as timeclock format: - -$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- - - -File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input - -4.2 Multiple files -================== - -You can specify multiple ‘-f’ options, to read multiple files as one big -journal. There are some limitations with this: - - • most directives do not affect sibling files - • balance assertions will not see any account balances from previous - files - - If you need either of those things, you can - - • use a single parent file which includes the others - • or concatenate the files into one before reading, eg: ‘cat - a.journal b.journal | hledger -f- CMD’. - - -File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input - -4.3 Strict mode -=============== - -hledger checks input files for valid data. By default, the most -important errors are detected, while still accepting easy journal files -without a lot of declarations: - - • Are the input files parseable, with valid syntax ? - • Are all transactions balanced ? - • Do all balance assertions pass ? - - With the ‘-s’/‘--strict’ flag, additional checks are performed: - - • Are all accounts posted to, declared with an ‘account’ directive ? - (Account error checking) - • Are all commodities declared with a ‘commodity’ directive ? - (Commodity error checking) - • Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks – the ones -listed above and some more. - - -File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top - -5 Commands -********** - -hledger provides a number of built-in subcommands (described below). -Most of these read your data without changing it, and display a report. -A few assist with data entry and management. - - Run ‘hledger’ with no arguments to list the commands available, and -‘hledger CMD’ to run a command. CMD can be the full command name, or -its standard abbreviation shown in the commands list, or any unambiguous -prefix of the name. Eg: ‘hledger bal’. - -* Menu: - -* Add-on commands:: - - -File: hledger.info, Node: Add-on commands, Up: Commands - -5.1 Add-on commands -=================== - -Add-on commands are extra subcommands provided by programs or scripts in -your PATH - - • whose name starts with ‘hledger-’ - • whose name ends with a recognised file extension: - ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’ - or none - • and (on unix, mac) which are executable by the current user. - - Addons can be written in any language, but haskell scripts or -programs have a big advantage: they can use hledger’s library code, for -command-line options, parsing and reporting. - - Several add-on commands are installed by the hledger-install script. -See https://hledger.org/scripts.html for more details. - - Note in a hledger command line, add-on command flags must have a -double dash (‘--’) preceding them. Eg you must write: - -$ hledger web -- --serve - - and not: - -$ hledger web --serve - - (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’). - - The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’. - - If you have any trouble with this, remember you can always run the -add-on program directly, eg: - -$ hledger-web --serve - - -File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top - -6 Output -******** - -* Menu: - -* Output destination:: -* Output format:: -* Commodity styles:: -* Colour:: -* Box-drawing:: -* Debug output:: - - -File: hledger.info, Node: Output destination, Next: Output format, Up: Output - -6.1 Output destination -====================== - -hledger commands send their output to the terminal by default. You can -of course redirect this, eg into a file, using standard shell syntax: - -$ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also -provide the ‘-o/--output-file’ option, which does the same thing without -needing the shell. Eg: - -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) - - -File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output - -6.2 Output format -================= - -Some commands offer other kinds of output, not just text on the -terminal. Here are those commands and the formats currently supported: - -- txt csv html json sql ------------------------------------------------------------------------------ -aregister Y Y Y Y -balance Y _1_ Y _1_ Y _1,2_ Y -balancesheet Y _1_ Y _1_ Y _1_ Y -balancesheetequity Y _1_ Y _1_ Y _1_ Y -cashflow Y _1_ Y _1_ Y _1_ Y -incomestatement Y _1_ Y _1_ Y _1_ Y -print Y Y Y Y -register Y Y Y - - • _1 Also affected by the balance commands’ ‘--layout’ option._ - • _2 ‘balance’ does not support html output without a report interval - or with ‘--budget’._ - - The output format is selected by the ‘-O/--output-format=FMT’ option: - -$ hledger print -O csv # print CSV on stdout - - or by the filename extension of an output file specified with the -‘-o/--output-file=FILE.FMT’ option: - -$ hledger balancesheet -o foo.csv # write CSV to foo.csv - - The ‘-O’ option can be combined with ‘-o’ to override the file -extension, if needed: - -$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - - Some notes about the various output formats: - -* Menu: - -* CSV output:: -* HTML output:: -* JSON output:: -* SQL output:: - - -File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format - -6.2.1 CSV output ----------------- - - • In CSV output, digit group marks (such as thousands separators) are - disabled automatically. - - -File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format - -6.2.2 HTML output ------------------ - - • HTML output can be styled by an optional ‘hledger.css’ file in the - same directory. - - -File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format - -6.2.3 JSON output ------------------ - - • This is not yet much used; real-world feedback is welcome. - - • Our JSON is rather large and verbose, since it is a faithful - representation of hledger’s internal data types. To understand the - JSON, read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. - - • hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can - arise in practice (from automatically-calculated transaction - prices), and would break most JSON consumers. So in JSON, we show - quantities as simple Numbers with at most 10 decimal places. We - don’t limit the number of integer digits, but that part is under - your control. We hope this approach will not cause problems in - practice; if you find otherwise, please let us know. (Cf #1195) - - -File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format - -6.2.4 SQL output ----------------- - - • This is not yet much used; real-world feedback is welcome. - - • SQL output is expected to work with sqlite, MySQL and PostgreSQL - - • SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables - created via SQL output of hledger, you would probably want to - either clear tables of existing data (via ‘delete’ or ‘truncate’ - SQL statements) or drop tables completely as otherwise your - postings will be duped. - - -File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output - -6.3 Commodity styles -==================== - -When displaying amounts, hledger infers a standard display style for -each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a ‘-c/--commodity-style’ option -(except for cost amounts and amounts displayed by the ‘print’ command, -which are always displayed with all decimal digits). For example, the -following will force dollar amounts to be displayed as shown: - -$ hledger print -c '$1.000,0' - - This option can repeated to set the display style for multiple -commodities/currencies. Its argument is as described in the commodity -directive. - - -File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output - -6.4 Colour -========== - -In terminal output, some commands can produce colour when the terminal -supports it: - - • if the ‘--color/--colour’ option is given a value of ‘yes’ or - ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used; - • otherwise, if the ‘NO_COLOR’ environment variable is set, colour - will not be used; - • otherwise, colour will be used if the output (terminal or file) - supports it. - - -File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output - -6.5 Box-drawing -=============== - -In terminal output, you can enable unicode box-drawing characters to -render prettier tables: - - • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or - ‘no’ or ‘never’), unicode characters will (or will not) be used; - • otherwise, unicode characters will not be used. - - -File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output - -6.6 Debug output -================ - -We intend hledger to be relatively easy to troubleshoot, introspect and -develop. You can add ‘--debug[=N]’ to any hledger command line to see -additional debug output. N ranges from 1 (least output, the default) to -9 (maximum output). Typically you would start with 1 and increase until -you are seeing enough. Debug output goes to stderr, and is not affected -by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg: -‘2>&1’). It will be interleaved with normal output, which can help -reveal when parts of the code are evaluated. To capture debug output in -a log file instead, you can usually redirect stderr, eg: - -hledger bal --debug=3 2>hledger.log - - -File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top - -7 Limitations -************* - -The need to precede add-on 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. - - On Windows, non-ascii characters may not display correctly when -running a hledger built in CMD in MSYS/CYGWIN, or vice-versa. - - 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 hledger -and Ledger > Differences > journal format. - - On large data files, hledger is slower and uses more memory than -Ledger. - - -File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top - -8 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. - - *Getting errors like "Illegal byte sequence" or "Invalid or -incomplete multibyte or wide character" or "commitAndReleaseBuffer: -invalid argument (invalid character)"* -Programs compiled with GHC (hledger, haskell build tools, etc.) need to -have a UTF-8-aware locale configured in the environment, otherwise they -will fail with these kinds of errors when they encounter non-ascii -characters. - - To fix it, set the LANG environment variable to some locale which -supports UTF-8. The locale you choose must be installed on your system. - - Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux: - -$ file my.journal -my.journal: UTF-8 Unicode text # the file is UTF8-encoded -$ echo $LANG -C # LANG is set to the default locale, which does not support UTF8 -$ locale -a # which locales are installed ? -C -en_US.utf8 # here's a UTF8-aware one we can use -POSIX -$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command - - If available, ‘C.UTF-8’ will also work. If your preferred locale -isn’t listed by ‘locale -a’, you might need to install it. Eg on -Ubuntu/Debian: - -$ 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 - - Here’s how you could set it permanently, if you use a bash shell: - -$ echo "export LANG=en_US.utf8" >>~/.bash_profile -$ bash --login - - Exact spelling and capitalisation may be important. Note the -difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu) -allow variant spellings, but others (eg macos) require it to be exact: - -$ locale -a | grep -iE en_us.*utf -en_US.UTF-8 -$ LANG=en_US.UTF-8 hledger -f my.journal print - - -File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top - -9 PART 2: DATA FORMATS -********************** - - -File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top - -10 Journal -********** - -hledger’s default file format, representing a General Journal. Here’s a -cheatsheet/mini-tutorial, or you can skip ahead to About journal format. - -* Menu: - -* Journal cheatsheet:: -* About journal format:: -* Comments:: -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Transaction comments:: -* Postings:: -* Account names:: -* Amounts:: -* Costs:: -* Balance assertions:: -* Posting comments:: -* Tags:: -* Directives:: -* account directive:: -* alias directive:: -* commodity directive:: -* decimal-mark directive:: -* include directive:: -* P directive:: -* payee directive:: -* tag directive:: -* Periodic transactions:: -* Other syntax:: - - -File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal - -10.1 Journal cheatsheet -======================= - -# Here is the main syntax of hledger's journal format -# (omitting extra Ledger compatibility syntax). -# hledger journals contain comments, directives, and transactions, in any order: - -############################################################################### -# 1. Comment lines are for notes or temporarily disabling things. -# They begin with #, ;, or a line containing the word "comment". - -# hash comment line -; semicolon comment line -comment -These lines -are commented. -end comment - -# Some but not all hledger entries can have same-line comments attached to them, -# from ; (semicolon) to end of line. - -############################################################################### -# 2. Directives modify parsing or reports in some way. -# They begin with a word or letter (or symbol). - -account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. -account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) -alias chkg = assets:checking -commodity $0.00 -decimal-mark . -include /dev/null -payee Whole Foods -P 2022-01-01 AAAA $1.40 -~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - -############################################################################### -# 3. Transactions are what it's all about; they are dated events, -# usually describing movements of money. -# They begin with a date. - -# DATE DESCRIPTION ; This is a transaction comment. -# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. -# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. -# ; ^^ At least 2 spaces between account and amount. -# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - -2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - -2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - -Kv -2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - -2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - -2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - -1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - -2022.01.01 These date -2022/1/1 formats are -12/31 also allowed (but consistent YYYY-MM-DD is recommended). - - -File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal - -10.2 About journal format -========================= - -hledger’s usual data source is a plain text file containing journal -entries in hledger journal format. This file represents a standard -accounting general journal. I use file names ending in ‘.journal’, but -that’s not required. The journal file contains a number of transaction -entries, each describing a transfer of money (or any commodity) between -two or more named accounts, in a simple format readable by both hledger -and humans. - - hledger’s journal format is a compatible subset, mostly, of ledger’s -journal format, so hledger can work with compatible ledger journal files -as well. It’s safe, and encouraged, to run both hledger and ledger on -the same journal file, eg to validate the results you’re getting. - - You can use hledger without learning any more about this file; just -use the add or web or import commands to create and update it. - - Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor addons -such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and -hledger-vscode for Visual Studio Code, make this easier, adding colour, -formatting, tab completion, and useful commands. See Editor -configuration at hledger.org for the full list. - - Here’s a description of each part of the file format (and hledger’s -data model). - - A hledger journal file can contain three kinds of thing: file -comments, transactions, and/or directives (counting periodic transaction -rules and auto posting rules as directives). - - -File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal - -10.3 Comments -============= - -Lines in the journal will be ignored if they begin with a hash (‘#’) or -a semicolon (‘;’). (See also Other syntax.) hledger will also ignore -regions beginning with a ‘comment’ line and ending with an ‘end comment’ -line (or file end). Here’s a suggestion for choosing between them: - - • ‘#’ for top-level notes - • ‘;’ for commenting out things temporarily - • ‘comment’ for quickly commenting large regions (remember it’s - there, or you might get confused) - - Eg: - -# a comment line -; another commentline -comment -A multi-line comment block, -continuing until "end comment" directive -or the end of the current file. -end comment - - Some hledger entries can have same-line comments attached to them, -from ; (semicolon) to end of line. See Transaction comments, Posting -comments, and Account comments below. - - -File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal - -10.4 Transactions -================= - -Transactions are the main unit of information in a journal file. They -represent events, typically a movement of some quantity of commodities -between two or more named accounts. - - Each transaction is recorded as a journal entry, beginning with a -simple date in column 0. This can be followed by any of the following -optional fields, separated by spaces: - - • a status character (empty, ‘!’, or ‘*’) - • a code (any short number or text, enclosed in parentheses) - • a description (any remaining text until end of line or a semicolon) - • a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - • 0 or more indented _posting_ lines, describing what was transferred - and the accounts involved (indented comment lines are also allowed, - but not blank lines or non-indented lines). - - Here’s a simple journal file containing one transaction: - -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - -File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal - -10.5 Dates -========== - -* Menu: - -* Simple dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates - -10.5.1 Simple dates -------------------- - -Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or -‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may -be omitted, in which case it will be inferred from the context: the -current transaction, the default year set with a ‘Y’ directive, or the -current date when the command is run. Some examples: ‘2010-01-31’, -‘2010/01/31’, ‘2010.1.31’, ‘1/31’. - - (The UI also accepts simple dates, as well as the more flexible smart -dates documented in the hledger manual.) - - -File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates - -10.5.2 Posting dates --------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like ‘date:DATE’. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction’s date. -The ‘date:’ tag must have a valid simple date value if it is present, eg -a ‘date:’ tag with no value is not allowed. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal - -10.6 Status -=========== - -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: - -mark status - ------------------ - unmarked -‘!’ pending -‘*’ cleared - - When reporting, you can filter by status with the ‘-U/--unmarked’, -‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’, -and ‘status:*’ queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" -state is called "uncleared". As of hledger 1.3 we have renamed it to -unmarked for clarity. - - To replicate Ledger and old hledger’s behaviour of also matching -pending, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. Some editor modes provide highlighting and -shortcuts for working with status. Eg in Emacs ledger-mode, you can -toggle transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to -you. Here’s one suggestion: - -status meaning --------------------------------------------------------------------------- -uncleared recorded but not yet reconciled; needs review -pending tentatively reconciled (if needed, eg during a big - reconciliation) -cleared complete, reconciled as far as possible, and considered - correct - - With this scheme, you would use ‘-PC’ to see the current balance at -your bank, ‘-U’ to see things which will probably hit your bank soon -(like uncashed checks), and no flags to see the most up-to-date state of -your finances. - - -File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal - -10.7 Code -========= - -After the status mark, but before the description, you can optionally -write a transaction "code", enclosed in parentheses. This is a good -place to record a check number, or some other important transaction id -or reference number. - - -File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal - -10.8 Description -================ - -A transaction’s description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -10.8.1 Payee and note ---------------------- - -You can optionally include a ‘|’ (pipe) character in descriptions to -subdivide the description into separate fields for payee/payer name on -the left (up to the first ‘|’) and an additional note field on the right -(after the first ‘|’). This may be worthwhile if you need to do more -precise querying and pivoting by payee or by note. - - -File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal - -10.9 Transaction comments -========================= - -Text following ‘;’, after a transaction description, and/or on indented -lines immediately below it, form comments for that transaction. They -are reproduced by ‘print’ but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal - -10.10 Postings -============== - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - • (optional) a status character (empty, ‘!’, or ‘*’), followed by a - space - • (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - • (optional) *two or more spaces* or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are -being removed. - - The amounts within a transaction must always sum up to zero. As a -convenience, one amount may be left blank; it will be inferred so as to -balance the transaction. - - Be sure to note the unusual two-space delimiter between account name -and amount. This makes it easy to write account names containing -spaces. But if you accidentally leave only one space (or tab) before -the amount, the amount will be considered part of the account name. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal - -10.11 Account names -=================== - -Accounts are the main way of categorising things in hledger. As in -Double Entry Bookkeeping, they can represent real world accounts (such -as a bank account), or more abstract categories such as "money borrowed -from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are ‘assets’, -‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these -referred to as A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. For example, from the account names ‘assets:bank:checking’ -and ‘expenses:food’, hledger will infer this hierarchy of five accounts: - -assets -assets:bank -assets:bank:checking -expenses -expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - -assets - bank - checking -expenses - food - - hledger reports can summarise the account tree to any depth, so you -can go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. Note, when an account name and an -amount are written on the same line, they must be separated by *two or -more spaces* (or tabs). - - Parentheses or brackets enclosing the full account name indicate -virtual postings, described below. Parentheses or brackets internal to -the account name have no special meaning. - - Account names can be altered temporarily or permanently by account -aliases. - - -File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal - -10.12 Amounts -============= - -After the account name, there is usually an amount. (Important: between -account name and amount, there must be *two or more spaces*.) - - hledger’s amount format is flexible, supporting several international -formats. Here are some examples. Amounts have a number (the -"quantity"): - -1 - - ..and usually a currency symbol or commodity name (more on this -below), to the left or right of the quantity, with or without a -separating space: - -$1 -4000 AAPL -3 "green apples" - - Amounts can be preceded by a minus sign (or a plus sign, though plus -is the default), The sign can be written before or after a left-side -commodity symbol: - --$1 -$-1 - - One or more spaces between the sign and the number are acceptable -when parsing (but they won’t be displayed in output): - -+ $1 -$- 1 - - Scientific E notation is allowed: - -1E-6 -EUR 1E3 - -* Menu: - -* Decimal marks digit group marks:: -* Commodity:: -* Directives influencing number parsing and display:: -* Commodity display style:: -* Rounding:: - - -File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts - -10.12.1 Decimal marks, digit group marks ----------------------------------------- - -A _decimal mark_ can be written as a period or a comma: - -1.23 -1,23456780000009 - - In the integer part of the quantity (left of the decimal mark), -groups of digits can optionally be separated by a _digit group mark_ - a -space, comma, or period (different from the decimal mark): - - $1,000,000.00 - EUR 2.000.000,00 -INR 9,99,99,999.00 - 1 000 000.9455 - - Note, a number containing a single digit group mark and no decimal -mark is ambiguous. Are these digit group marks or decimal marks ? - -1,000 -1.000 - - If you don’t tell it otherwise, hledger will assume both of the above -are decimal marks, parsing both numbers as 1. - - To prevent confusing parsing mistakes and undetected typos, -especially if your data contains digit group marks (eg, thousands -separators), we recommend explicitly declaring the decimal mark -character in each journal file, using a directive at the top of the -file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’ -directives will also work. These are described below. - - -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts - -10.12.2 Commodity ------------------ - -Amounts in hledger have both a "quantity", which is a signed decimal -number, and a "commodity", which is a currency symbol, stock ticker, or -any word or phrase describing something you are tracking. - - If the commodity name contains non-letters (spaces, numbers, or -punctuation), you must always write it inside double quotes (‘"green -apples"’, ‘"ABC123"’). - - If you write just a bare number, that too will have a commodity, with -name ‘""’; we call that the "no-symbol commodity". - - Actually, hledger combines these single-commodity amounts into more -powerful multi-commodity amounts, which are what it works with most of -the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456 -TSLA’. In practice, you will only see multi-commodity amounts in -hledger’s output; you can’t write them directly in the journal file. - - (If you are writing scripts or working with hledger’s internals, -these are the ‘Amount’ and ‘MixedAmount’ types.) - - -File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts - -10.12.3 Directives influencing number parsing and display ---------------------------------------------------------- - -You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to -declare and control these things more explicitly and precisely. These -are described below, but here’s a quick example: - -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 - - -File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts - -10.12.4 Commodity display style -------------------------------- - -For the amounts in each commodity, hledger chooses a consistent display -style to use in most reports. (Exceptions: price amounts, and all -amounts displayed by the ‘print’ command, are displayed with all of -their decimal digits visible.) - - A commodity’s display style is inferred as follows. - - First, if a default commodity is declared with ‘D’, this commodity -and its style is applied to any no-symbol amounts in the journal. - - Then each commodity’s style is inferred from one of the following, in -order of preference: - - • The commodity directive for that commodity (including the no-symbol - commodity), if any. - • The amounts in that commodity seen in the journal’s transactions. - (Posting amounts only; prices and periodic or auto rules are - ignored, currently.) - • The built-in fallback style, which looks like this: ‘$1000.00’. - (Symbol on the left, period decimal mark, two decimal places.) - - A style is inferred from journal amounts as follows: - - • Use the general style (decimal mark, symbol placement) of the first - amount - • Use the first-seen digit group style (digit group mark, digit group - sizes), if any - • Use the maximum number of decimal places of all. - - Cost amounts don’t affect the commodity display style directly, but -occasionally they can do so indirectly (eg when a posting’s amount is -inferred using a cost). If you find this causing problems, use a -commodity directive to fix the display style. - - To summarise: each commodity’s amounts will be normalised to (a) the -style declared by a ‘commodity’ directive, or (b) the style of the first -posting amount in the journal, with the first-seen digit group style and -the maximum-seen number of decimal places. So if your reports are -showing amounts in a way you don’t like, eg with too many decimal -places, use a commodity directive. Some examples: - -# declare euro, dollar, bitcoin and no-symbol commodities and set their -# input number formats and output display styles: -commodity EUR 1.000, -commodity $1000.00 -commodity 1000.00000000 BTC -commodity 1 000. - - The inferred commodity style can be overridden by supplying a command -line option. - - -File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts - -10.12.5 Rounding ----------------- - -Amounts are stored internally as decimal numbers with up to 255 decimal -places, and displayed with the number of decimal places specified by the -commodity display style. Note, hledger uses banker’s rounding: it -rounds to the nearest even number, eg 0.5 displayed with zero decimal -places is "0"). - - -File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal - -10.13 Costs -=========== - -After a posting amount, you can note its cost (when buying) or selling -price (when selling) in another commodity, by writing either ‘@ -UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion -transaction, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, -discussions, or code; that term was directionally neutral and reminded -that it is a price specific to a transaction, but we now just call it -"cost", with the understanding that the transaction could be a purchase -or a sale.) - - Costs are usually written explicitly with ‘@’ or ‘@@’, but can also -be inferred automatically for simple multi-commodity transactions. -Note, if costs are inferred, the order of postings is significant; the -first posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign -currency in hledger, using the cost notation either explicitly or -implicitly: - - 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction. - Note the effect of posting order: the price is added to first - posting, making it ‘€100 @@ $135’, as in example 2: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the ‘-B/--cost’ -flag; this is discussed more in the ˜COST REPORTING section. - -* Menu: - -* Other cost/lot notations:: - - -File: hledger.info, Node: Other cost/lot notations, Up: Costs - -10.13.1 Other cost/lot notations --------------------------------- - -A slight digression for Ledger and Beancount users. Ledger has a number -of cost/lot-related notations: - - • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ - • expresses a conversion rate, as in hledger - • when buying, also creates a lot than can be selected at - selling time - - • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost) - • like the above, but also means "this cost was exceptional, - don’t use it when inferring market prices". - - Currently, hledger treats the above like ‘@’ and ‘@@’; the -parentheses are ignored. - - • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price) - • when buying, means "this cost is also the fixed price, don’t - let it fluctuate in value reports" - - • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price) - • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’, - also creates a lot - • when selling, combined with ‘@ ...’, specifies an investment - lot by its cost basis; does not check if that lot is present - - • and related: ‘[YYYY/MM/DD]’ (lot date) - • when buying, attaches this acquisition date to the lot - • when selling, selects a lot by its acquisition date - - • ‘(SOME TEXT)’ (lot note) - • when buying, attaches this note to the lot - • when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. (This can break transaction -balancing.) - - For Beancount users, the notation and behaviour is different: - - • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ - • expresses a cost without creating a lot, as in hledger - • when buying (augmenting) or selling (reducing) a lot, combined - with ‘{...}’: documents the cost/selling price (not used for - transaction balancing) - - • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ - • when buying (augmenting), expresses the cost for transaction - balancing, and also creates a lot with this cost basis - attached - • when selling (reducing), - • selects a lot by its cost basis - • raises an error if that lot is not present or can not be - selected unambiguously (depending on booking method - configured) - • expresses the selling price for transaction balancing - - Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation -but ignores it. - - • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST, - "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc. - - Currently, hledger rejects these. - - -File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal - -10.14 Balance assertions -======================== - -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s -amount. Eg here we assert the expected dollar balance in accounts a and -b after each posting: - -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the ‘-I/--ignore-assertions’ flag, which can be useful for -troubleshooting or for reading Ledger files. (Note: this flag currently -does not disable balance assignments, described below). - -* Menu: - -* Assertions and ordering:: -* Assertions and multiple included files:: -* Assertions and multiple -f files:: -* Assertions and commodities:: -* Assertions and prices:: -* Assertions and subaccounts:: -* Assertions and virtual postings:: -* Assertions and auto postings:: -* Assertions and precision:: - - -File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions - -10.14.1 Assertions and ordering -------------------------------- - -hledger sorts an account’s postings and assertions first by date and -then (for postings on the same day) by parse order. Note this is -different from Ledger, which sorts assertions only by parse order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder -differently-dated transactions within the journal. But if you reorder -same-dated transactions or postings, assertions might break and require -updating. This order dependence does bring an advantage: precise -control over the order of postings and assertions within a day, so you -can assert intra-day balances. - - -File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions - -10.14.2 Assertions and multiple included files ----------------------------------------------- - -Multiple files included with the ‘include’ directive are processed as if -concatenated into one file, preserving their order and the posting order -within each file. It means that balance assertions in later files will -see balance from earlier files. - - And if you have multiple postings to an account on the same day, -split across multiple files, and you want to assert the account’s -balance on that day, you’ll need to put the assertion in the right file -- the last one in the sequence, probably. - - -File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions - -10.14.3 Assertions and multiple -f files ----------------------------------------- - -Unlike ‘include’, when multiple files are specified on the command line -with multiple ‘-f/--file’ options, balance assertions will not see -balance from earlier files. This can be useful when you do not want -problems in earlier files to disrupt valid assertions in later files. - - If you do want assertions to see balance from earlier files, use -‘include’, or concatenate the files temporarily. - - -File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions - -10.14.4 Assertions and commodities ----------------------------------- - -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity’s balance within the -(possibly multi-commodity) account balance. This is how assertions work -in Ledger also. We could call this a "partial" balance assertion. - - To assert the balance of more than one commodity in an account, you -can write multiple postings, each asserting one commodity’s balance. - - You can make a stronger "total" balance assertion by writing a double -equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no -other commodities in the account besides the asserted one (or at least, -that their balance is 0). - -2013/1/1 - a $1 - a 1€ - b $-1 - c -1€ - -2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1€ - b 0 == $-1 - c 0 == -1€ - -2013/1/3 ; This assertion fails as 'a' also contains 1€ - a 0 == $1 - - It’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: - -2013/1/1 - a:usd $1 - a:euro 1€ - b - -2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1€ - - -File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions - -10.14.5 Assertions and prices ------------------------------ - -Balance assertions ignore costs, 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.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions - -10.14.6 Assertions and subaccounts ----------------------------------- - -The balance assertions above (‘=’ and ‘==’) do not count the balance -from subaccounts; they check the account’s exclusive balance only. You -can assert the balance including subaccounts by writing ‘=*’ or ‘==*’, -eg: - -2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 - - -File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions - -10.14.7 Assertions and virtual postings ---------------------------------------- - -Balance assertions always consider both real and virtual postings; they -are not affected by the ‘--real/-R’ flag or ‘real:’ query. - - -File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions - -10.14.8 Assertions and auto postings ------------------------------------- - -Balance assertions _are_ affected by the ‘--auto’ flag, which generates -auto postings, which can alter account balances. Because auto postings -are optional in hledger, accounts affected by them effectively have two -balances. But balance assertions can only test one or the other of -these. So to avoid making fragile assertions, either: - - • assert the balance calculated with ‘--auto’, and always use - ‘--auto’ with that file - • or assert the balance calculated without ‘--auto’, and never use - ‘--auto’ with that file - • or avoid balance assertions on accounts affected by auto postings - (or avoid auto postings entirely). - - -File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions - -10.14.9 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.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal - -10.15 Posting comments -====================== - -Text following ‘;’, at the end of a posting line, and/or on indented -lines immediately below it, form comments for that posting. They are -reproduced by ‘print’ but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - -File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal - -10.16 Tags -========== - -Tags are a way to add extra labels or labelled data to transactions, -postings, or accounts, which you can then search or pivot on. - - They are written as a word (optionally hyphenated) immediately -followed by a full colon, in a transaction or posting or account -directive’s comment. (This is an exception to the usual rule that -things in comments are ignored.) Eg, here four different tags are -recorded: one on the checking account, two on the transaction, and one -on the expenses posting: - -account assets:checking ; accounttag: - -2017/1/16 bought groceries ; transactiontag-1: - ; transactiontag-2: - assets:checking $-1 - expenses:food $1 ; postingtag: - - Postings also inherit tags from their transaction and their account. -And transactions also acquire tags from their postings (and postings’ -accounts). So in the example above, the expenses posting effectively -has all four tags (by inheriting from account and transaction), and the -transaction also has all four tags (by acquiring from the expenses -posting). - - You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by -tag name with a ‘tag:NAMEREGEX’ query. - -* Menu: - -* Tag values:: - - -File: hledger.info, Node: Tag values, Up: Tags - -10.16.1 Tag values ------------------- - -Tags can have a value, which is any text after the colon up until a -comma or end of line (with surrounding whitespace removed). Note this -means that hledger tag values can not contain commas. Eg in the -following posting, the three tags’ values are "value 1", "value 2", and -"" (empty) respectively: - - expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - - Note that tags can be repeated, and are additive rather than -overriding: when the same tag name is seen again with a new value, the -new name:value pair is added to the tags. (It is not possible to -override a tag’s value or remove a tag.) - - You can list a tag’s values with ‘hledger tags TAGNAME --values’, or -match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query. - - -File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal - -10.17 Directives -================ - -A directive is a line in the journal beginning with a special keyword, -that influences how the journal is processed, how things are displayed, -and so on. hledger’s directives are based on (a subset of) Ledger’s, -but there are many differences, and also some differences between -hledger versions. Here are some more definitions: - - • _subdirective_ - Some directives support subdirectives, written - indented below the parent directive. - - • _decimal mark_ - The character to interpret as a decimal mark - (period or comma) when parsing amounts of a commodity. - - • _display style_ - How to display amounts of a commodity in output: - symbol side and spacing, digit groups, decimal mark, and number of - decimal places. - - Directives are not required when starting out with hledger, but you -will probably want to add some as your needs grow. Here some key -directives for particular needs: - -purpose directives --------------------------------------------------------------------------- -*READING DATA:* -Declare file’s decimal mark to help parse ‘decimal-mark’ -amounts accurately -Rewrite account names ‘alias’ -Comment out sections of the data ‘comment’ -Include extra data files ‘include’ -*GENERATING DATA:* -Generate recurring transactions or budget ‘~’ -goals -Generate extra postings on transactions ‘=’ -*CHECKING FOR ERRORS:* -Define valid entities to provide more ‘account’, ‘commodity’, -error checking ‘payee’ -*REPORTING:* -Declare accounts’ type and display order ‘account’ -Declare commodity display styles ‘commodity’ -Declare market prices ‘P’ - -* Menu: - -* Directive effects:: -* Directives and multiple files:: - - -File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives - -10.17.1 Directive effects -------------------------- - -And here is what each directive does, and which files and journal -entries (transactions) it affects: - -directivewhat it does ends - at - file - end? ---------------------------------------------------------------------------- -*‘account’*Declares an account, for checking all entries in all files; andN - its display order and type. Subdirectives: any text, ignored. -*‘alias’*Rewrites account names, in following entries until end of Y - current file or ‘end aliases’. Command line equivalent: - ‘--alias’ -*‘comment’*Ignores part of the journal file, until end of current file orY - ‘end comment’. -*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N - all amounts in all files 2. the decimal mark for parsing - amounts of this commodity, in the following entries until end of - current file (if there is no ‘decimal-mark’ directive) 3. and - the display style for amounts of this commodity 4. which is - also the precision to use for balanced-transaction checking in - this commodity. Takes precedence over ‘D’. Subdirectives: - ‘format’ (Ledger-compatible syntax). Command line equivalent: - ‘-c/--commodity-style’ -*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y - commodities in following entries until next ‘decimal-mark’ or - end of current file. Included files can override. Takes - precedence over ‘commodity’ and ‘D’. -*‘include’*Includes entries and directives from another file, as if theyN - were written inline. Command line alternative: multiple - ‘-f/--file’ -*‘payee’*Declares a payee name, for checking all entries in all files. N -*‘P’*Declares the market price of a commodity on some date, for value N - reports. -*‘~’*Declares a periodic transaction rule that generates future N -(tilde)transactions with ‘--forecast’ and budget goals with ‘balance - --budget’. -Other -syntax: -*‘applyPrepends a common parent account to all account names, in Y -account’*following entries until end of current file or ‘end apply - account’. -*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no ‘commodity’ directive for this commodity: its - decimal mark, balancing precision, and display style, as above. -*‘Y’*Sets a default year to use for any yearless dates, in following Y - entries until end of current file. -*‘=’*Declares an auto posting rule that generates extra postings on partly -(equals)matched transactions with ‘--auto’, in current, parent, and - child files (but not sibling files, see #1212). -*OtherOther directives from Ledger’s file format are accepted but -Ledgerignored. -directives* - - -File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives - -10.17.2 Directives and multiple files -------------------------------------- - -If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive, -hledger will process multiple input files. But directives which affect -input typically have effect only until the end of the file in which they -occur (and on any included files in that region). - - This may seem inconvenient, but it’s intentional; it makes reports -stable and deterministic, independent of the order of input. Otherwise -you could see different numbers if you happened to write -f options in a -different order, or if you moved includes around while cleaning up your -files. - - It can be surprising though; for example, it means that ‘alias’ -directives do not affect parent or sibling files (see below). - - -File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal - -10.18 ‘account’ directive -========================= - -‘account’ directives can be used to declare accounts (ie, the places -that amounts are transferred from and to). Though not required, these -declarations can provide several benefits: - - • They can document your intended chart of accounts, providing a - reference. - • In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - • They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - • They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - • They can store additional account information as comments, or as - tags which can be used to filter or pivot reports. - • They can help hledger know your accounts’ types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - - They are written as the word ‘account’ followed by a hledger-style -account name, eg: - -account assets:bank:checking - - Note, however, that accounts declared in account directives are not -allowed to have surrounding brackets and parentheses, unlike accounts -used in postings. So the following journal will not parse: - -account (assets:bank:checking) - -* Menu: - -* Account comments:: -* Account subdirectives:: -* Account error checking:: -* Account display order:: -* Account types:: - - -File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive - -10.18.1 Account comments ------------------------- - -Text following *two or more spaces* and ‘;’ at the end of an account -directive line, and/or following ‘;’ on indented lines immediately below -it, form comments for that account. They are ignored except they may -contain tags, which are not ignored. - - The two-space requirement for same-line account comments is because -‘;’ is allowed in account names. - -account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - -File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive - -10.18.2 Account subdirectives ------------------------------ - -Ledger-style indented subdirectives are also accepted, but currently -ignored: - -account assets:bank:checking - format subdirective is ignored - - -File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive - -10.18.3 Account error checking ------------------------------- - -By default, accounts need not be declared; they come into existence when -a posting references them. This is convenient, but it means hledger -can’t warn you when you mis-spell an account name in the journal. -Usually you’ll find that error later, as an extra account in balance -reports, or an incorrect balance when reconciling. - - In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will -report an error if any transaction uses an account name that has not -been declared by an account directive. Some notes: - - • The declaration is case-sensitive; transactions must use the - correct account name capitalisation. - • The account directive’s scope is "whole file and below" (see - directives). This means it affects all of the current file, and - any files it includes, but not parent or sibling files. The - position of account directives within the file does not matter, - though it’s usual to put them at the top. - • Accounts can only be declared in ‘journal’ files, but will affect - included files of all types. - • It’s currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - -File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive - -10.18.4 Account display order ------------------------------ - -The order in which account directives are written influences the order -in which accounts appear in reports, hledger-ui, hledger-web etc. By -default accounts appear in alphabetical order, but if you add these -account directives to the journal file: - -account assets -account liabilities -account equity -account revenues -account expenses - - those accounts will be displayed in declaration order: - -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses - - Any undeclared accounts are displayed last, in alphabetical order. - - 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 - • sibling accounts stay together (you couldn’t display ‘x:y’ in - between ‘a:b’ and ‘a:c’). - - -File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive - -10.18.5 Account types ---------------------- - -hledger knows that accounts come in several types: assets, liabilities, -expenses and so on. This enables easy reports like balancesheet and -incomestatement, and filtering by account type with the ‘type:’ query. - - As a convenience, hledger will detect these account types -automatically if you are using common english-language top-level account -names (described below). But generally we recommend you declare types -explicitly, by adding a ‘type:’ tag to your top-level account -directives. Subaccounts will inherit the type of their parent. The -tag’s value should be one of the five main account types: - - • ‘A’ or ‘Asset’ (things you own) - • ‘L’ or ‘Liability’ (things you owe) - • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of - assets & liabilities) - • ‘R’ or ‘Revenue’ (what you received money from, AKA income; - technically part of Equity) - • ‘X’ or ‘Expense’ (what you spend money on; technically part of - Equity) - - or, it can be (these are used less often): - - • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the - cashflow report) - • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST - REPORTING).) - - Here is a typical set of account type declarations: - -account assets ; type: A -account liabilities ; type: L -account equity ; type: E -account revenues ; type: R -account expenses ; type: X - -account assets:bank ; type: C -account assets:cash ; type: C - -account equity:conversion ; type: V - - Here are some tips for working with account types. - - • The rules for inferring types from account names are as follows. - These are just a convenience that sometimes help new users get - going; if they don’t work for you, just ignore them and declare - your account types. See also Regular expressions. - - If account's name contains this (CI) regular expression: | its type is: - --------------------------------------------------------------------|------------- - ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash - ^assets?(:|$) | Asset - ^(debts?|liabilit(y|ies))(:|$) | Liability - ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion - ^equity(:|$) | Equity - ^(income|revenue)s?(:|$) | Revenue - ^expenses?(:|$) | Expense - - • If you declare any account types, it’s a good idea to declare an - account for all of the account types, because a mixture of declared - and name-inferred types can disrupt certain reports. - - • Certain uses of account aliases can disrupt account types. See - Rewriting accounts > Aliases and account types. - - • As mentioned above, subaccounts will inherit a type from their - parent account. More precisely, an account’s type is decided by - the first of these that exists: - - 1. A ‘type:’ declaration for this account. - 2. A ‘type:’ declaration in the parent accounts above it, - preferring the nearest. - 3. An account type inferred from this account’s name. - 4. An account type inferred from a parent account’s name, - preferring the nearest parent. - 5. Otherwise, it will have no type. - - • For troubleshooting, you can list accounts and their types with: - - $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] - - -File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal - -10.19 ‘alias’ directive -======================= - -You can define account alias rules which rewrite your account names, or -parts of them, before generating reports. This can be useful for: - - • expanding shorthand account names to their full form, allowing - easier data entry and a less verbose journal - • adapting old journals to your current chart of accounts - • experimenting with new account organisations, like a new hierarchy - • combining two accounts into one, eg to see their sum or difference - on one line - • customising reports - - Account aliases also rewrite account names in account directives. -They do not affect account names being entered via hledger add or -hledger-web. - - Account aliases are very powerful. They are generally easy to use -correctly, but you can also generate invalid account names with them; -more on this below. - - See also Rewrite account names. - -* Menu: - -* Basic aliases:: -* Regex aliases:: -* Combining aliases:: -* Aliases and multiple files:: -* end aliases directive:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive - -10.19.1 Basic aliases ---------------------- - -To set an account alias, use the ‘alias’ directive in your journal file. -This affects all subsequent journal entries in the current file or its -included files (but note: not sibling or parent files). The spaces -around the = are optional: - -alias OLD = NEW - - Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line. -This affects all entries. It’s useful for trying out aliases -interactively. - - OLD and NEW are case sensitive full account names. hledger will -replace any occurrence of the old account name with the new one. -Subaccounts are also affected. Eg: - -alias checking = assets:bank:wells fargo:checking -; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - -File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive - -10.19.2 Regex aliases ---------------------- - -There is also a more powerful variant that uses a regular expression, -indicated by wrapping the pattern in forward slashes. (This is the only -place where hledger requires forward slashes around a regular -expression.) - - Eg: - -alias /REGEX/ = REPLACEMENT - - or: - -$ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by -REPLACEMENT. REGEX is case-insensitive as usual. - - If you need to match a forward slash, escape it with a backslash, eg -‘/\/=:’. - - If REGEX contains parenthesised match groups, these can be referenced -by the usual backslash and number in REPLACEMENT: - -alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 -; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - REPLACEMENT continues to the end of line (or on command line, to end -of option argument), so it can contain trailing whitespace. - - -File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive - -10.19.3 Combining aliases -------------------------- - -You can define as many aliases as you like, using journal directives -and/or command line options. - - Recursive aliases - where an account name is rewritten by one alias, -then by another alias, and so on - are allowed. Each alias sees the -effect of previously applied aliases. - - In such cases it can be important to understand which aliases will be -applied and in which order. For (each account name in) each journal -entry, we apply: - - 1. ‘alias’ directives preceding the journal entry, most recently - parsed first (ie, reading upward from the journal entry, bottom to - top) - 2. ‘--alias’ options, in the order they appeared on the command line - (left to right). - - In other words, for (an account name in) a given journal entry: - - • the nearest alias declaration before/above the entry is applied - first - • the next alias before/above that will be be applied next, and so on - • aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps -provide semantic stability - aliases will keep working the same way -independent of which files are being read and in which order. - - In case of trouble, adding ‘--debug=6’ to the command line will show -which aliases are being applied when. - - -File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive - -10.19.4 Aliases and multiple files ----------------------------------- - -As explained at Directives and multiple files, ‘alias’ directives do not -affect parent or sibling files. Eg in this command, - -hledger -f a.aliases -f b.journal - - account aliases defined in a.aliases will not affect b.journal. -Including the aliases doesn’t work either: - -include a.aliases - -2020-01-01 ; not affected by a.aliases - foo 1 - bar - - This means that account aliases should usually be declared at the -start of your top-most file, like this: - -alias foo=Foo -alias bar=Bar - -2020-01-01 ; affected by aliases above - foo 1 - bar - -include c.journal ; also affected - - -File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive - -10.19.5 ‘end aliases’ directive -------------------------------- - -You can clear (forget) all currently defined aliases (seen in the -journal so far, or defined on the command line) with this directive: - -end aliases - - -File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive - -10.19.6 Aliases can generate bad account names ----------------------------------------------- - -Be aware that account aliases can produce malformed account names, which -could cause confusing reports or invalid ‘print’ output. For example, -you could erase all account names: - -2021-01-01 - a:aa 1 - b - -$ hledger print --alias '/.*/=' -2021-01-01 - 1 - - The above ‘print’ output is not a valid journal. Or you could insert -an illegal double space, causing ‘print’ output that would give a -different journal when reparsed: - -2021-01-01 - old 1 - other - -$ hledger print --alias old="new USD" | hledger -f- print -2021-01-01 - new USD 1 - other - - -File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive - -10.19.7 Aliases and account types ---------------------------------- - -If an account with a type declaration (see Declaring accounts > Account -types) is renamed by an alias, normally the account type remains in -effect. - - However, renaming in a way that reshapes the account tree (eg -renaming parent accounts but not their children, or vice versa) could -prevent child accounts from inheriting the account type of their -parents. - - Secondly, if an account’s type is being inferred from its name, -renaming it by an alias could prevent or alter that. - - If you are using account aliases and the ‘type:’ query is not -matching accounts as you expect, try troubleshooting with the accounts -command, eg something like: - -$ hledger accounts --alias assets=bassetts type:a - - -File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal - -10.20 ‘commodity’ directive -=========================== - -You can use ‘commodity’ directives to declare your commodities. In fact -the ‘commodity’ directive performs several functions at once: - - 1. It declares commodities which may be used in the journal. This can - optionally be enforced, providing useful error checking. (Cf - Commodity error checking) - - 2. It declares which decimal mark character (period or comma), to - expect when parsing input - useful to disambiguate international - number formats in your data. Without this, hledger will parse both - ‘1,000’ and ‘1.000’ as 1. (Cf Amounts) - - 3. It declares how to render the commodity’s amounts when displaying - output - the decimal mark, any digit group marks, the number of - decimal places, symbol placement and so on. (Cf Commodity display - style) - - You will run into one of the problems solved by commodity directives -sooner or later, so we recommend using them, for robust and predictable -parsing and display. - - Generally you should put them at the top of your journal file (since -for function 2, they affect only following amounts, cf #793). - - A commodity directive is just the word ‘commodity’ followed by a -sample amount, like this: - -;commodity SAMPLEAMOUNT - -commodity $1000.00 -commodity 1,000.0000 AAAA ; optional same-line comment - - It may also be written on multiple lines, and use the ‘format’ -subdirective, as in Ledger. Note in this case the commodity symbol -appears twice; it must be the same in both places: - -;commodity SYMBOL -; format SAMPLEAMOUNT - -; display indian rupees with currency name on the left, -; thousands, lakhs and crores comma-separated, -; period as decimal point, and two decimal places. -commodity INR - format INR 1,00,00,000.00 - - Other indented subdirectives are currently ignored. - - Remember that if the commodity symbol contains spaces, numbers, or -punctuation, it must be enclosed in double quotes (cf Commodity). - - The amount’s quantity does not matter; only the format is -significant. It must include a decimal mark - either a period or a -comma - followed by 0 or more decimal digits. - - A few more examples: - -# number formats for $, EUR, INR and the no-symbol commodity: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.0 -commodity 1 000 000. - - Note hledger normally uses banker’s rounding, so 0.5 displayed with -zero decimal digits is "0". (More at Commodity display style.) - - Even in the presence of commodity directives, the commodity display -style can still be overridden by supplying a command line option. - -* Menu: - -* Commodity error checking:: - - -File: hledger.info, Node: Commodity error checking, Up: commodity directive - -10.20.1 Commodity error checking --------------------------------- - -In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will -report an error if a commodity symbol is used that has not been declared -by a ‘commodity’ directive. This works similarly to account error -checking, see the notes there for more details. - - Note, this disallows amounts without a commodity symbol, because -currently it’s not possible (?) to declare the "no-symbol" commodity -with a directive. This is one exception for convenience: zero amounts -are always allowed to have no commodity symbol. - - -File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal - -10.21 ‘decimal-mark’ directive -============================== - -You can use a ‘decimal-mark’ directive - usually one per file, at the -top of the file - to declare which character represents a decimal mark -when parsing amounts in this file. It can look like - -decimal-mark . - - or - -decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we -recommend it, especially if the file contains digit group marks (eg -thousands separators). - - -File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal - -10.22 ‘include’ directive -========================= - -You can pull in the content of additional files by writing an include -directive, like this: - -include FILEPATH - - Only journal files can include, and only journal, timeclock or -timedot files can be included (not CSV files, currently). - - If the file path does not begin with a slash, it is relative to the -current file’s folder. - - A tilde means home directory, eg: ‘include ~/main.journal’. - - The path may contain glob patterns to match multiple files, eg: -‘include *.journal’. - - There is limited support for recursive wildcards: ‘**/’ (the slash is -required) matches 0 or more subdirectories. It’s not super convenient -since you have to avoid include cycles and including directories, but -this can be done, eg: ‘include */**/*.journal’. - - The path may also be prefixed to force a specific file format, -overriding the file extension (as described in hledger.1 -> Input -files): ‘include timedot:~/notes/2020*.md’. - - -File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal - -10.23 ‘P’ directive -=================== - -The ‘P’ directive declares a market price, which is a conversion rate -between two commodities on a certain date. This allows value reports to -convert amounts of one commodity to their value in another, on or after -that date. These prices are often obtained from a stock exchange, -cryptocurrency exchange, the or foreign exchange market. - - The format is: - -P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the -commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and -quantity) of commodity 2 that one unit of commodity 1 is worth on this -date. Examples: - -# one euro was worth $1.35 from 2009-01-01 onward: -P 2009-01-01 € $1.35 - -# and $1.40 from 2010-01-01 onward: -P 2010-01-01 € $1.40 - - The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show -amount values in another commodity. See Valuation. - - -File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal - -10.24 ‘payee’ directive -======================= - -‘payee PAYEE NAME’ - - This directive can be used to declare a limited set of payees which -may appear in transaction descriptions. The "payees" check will report -an error if any transaction refers to a payee that has not been -declared. Eg: - -payee Whole Foods - - Any indented subdirectives are currently ignored. - - -File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal - -10.25 ‘tag’ directive -===================== - -‘tag TAGNAME’ - - This directive can be used to declare a limited set of tag names -allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - -tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is -used. It is quite easy to accidentally create a tag through normal use -of colons in comments(#comments]; if you want to prevent this, you can -declare and check your tags . - - -File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal - -10.26 Periodic transactions -=========================== - -The ‘~’ directive declares recurring transactions. Such directives -allow hledger to generate temporary future transactions (visible in -reports, not in the journal file) to help with forecasting or budgeting. - - Periodic transactions can be a little tricky, so before you use them, -read this whole section, or at least these tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - 2. For troubleshooting, show the generated transactions with ‘hledger - print --forecast tag:generated’ or ‘hledger register --forecast - tag:generated’. - 3. Forecasted transactions will begin only after the last - non-forecasted transaction’s date. - 4. Forecasted transactions will end 6 months from today, by default. - See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs - improvement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in ‘weekly from DATE’, DATE - must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give - an error. - 7. Other period expressions with an interval are automatically - expanded to cover a whole number of that interval. (This is done - to improve reports, but it also affects periodic transactions. - Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th - day of month from 2020/01’, which is equivalent to ‘~ every 10th - day of month from 2020/01/01’, will be adjusted to start on - 2019/12/10. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -10.26.1 Periodic rule syntax ----------------------------- - -A periodic transaction rule looks like a normal journal entry, with the -date replaced by a tilde (‘~’) followed by a period expression -(mnemonic: ‘~’ looks like a recurring sine wave.): - -# every first of month -~ monthly - expenses:rent $2000 - assets:bank:checking - -# every 15th of month in 2023's first quarter: -~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying -multi-period reports, just interpreted differently; there, it specifies -report periods; here it specifies recurrence dates (the periods’ start -dates). - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -10.26.2 Periodic rules and relative dates ------------------------------------------ - -Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’, -‘next quarter’) are usually not recommended in periodic rules, since the -results will change as time passes. If used, they will be interpreted -relative to, in order of preference: - - 1. the first day of the default year specified by a recent ‘Y’ - directive - 2. or the date specified with ‘--today’ - 3. or the date on which you are running the report. - - They will not be affected at all by report period or forecast period -dates. - - -File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions - -10.26.3 Two spaces between period expression and description! -------------------------------------------------------------- - -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 - - So, - - • Do write two spaces between your period expression and your - transaction description, if any. - • Don’t accidentally write two spaces in the middle of your period - expression. - - -File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal - -10.27 Other syntax -================== - -hledger journal format supports quite a few other features, mainly to -make interoperating with or converting from Ledger easier. Note some of -the features below are powerful and can be useful in special cases, but -in general, features in this section are considered less important or -even not recommended for most users. Downsides are mentioned to help -you decide if you want to use them. - -* Menu: - -* Auto postings:: -* Balance assignments:: -* Bracketed posting dates:: -* D directive:: -* apply account directive:: -* Y directive:: -* Secondary dates:: -* Star comments:: -* Valuation expressions:: -* Virtual postings:: -* Other Ledger directives:: - - -File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax - -10.27.1 Auto postings ---------------------- - -The ‘=’ directive declares a rule for automatically adding temporary -extra postings (visible in reports, not in the journal file) to all -transactions matched by a certain query, when you use the ‘--auto’ flag. - - Downsides: depending on generated data for your reports makes your -financial data less portable, less future-proof, and less trustworthy in -an audit. Also, because the feature is optional, other features like -balance assertions can break depending on whether it is on or off. - - An auto posting rule looks a bit like a transaction: - -= QUERY - ACCOUNT AMOUNT - ... - ACCOUNT [AMOUNT] - - except the first line is an equals sign (mnemonic: ‘=’ suggests -matching), followed by a query (which matches existing postings), and -each "posting" line describes a posting to be generated, and the posting -amounts can be: - - • a normal amount with a commodity symbol, eg ‘$2’. This will be - used as-is. - • a number, eg ‘2’. The commodity symbol (if any) from the matched - posting will be added to this. - • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The - matched posting’s amount (and total price, if any) will be - multiplied by N. - • a multiplier with a commodity symbol, eg ‘*$2’ (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. - - Any query term containing spaces must be enclosed in single or double -quotes, as on the command line. Eg, note the quotes around the second -query term below: - -= expenses:groceries 'expenses:dining out' - (budget:funds:dining out) *-1 - - Some examples: - -; every time I buy food, schedule a dollar donation -= expenses:food - (liabilities:charity) $-1 - -; when I buy a gift, also deduct that amount from a budget envelope subaccount -= expenses:gifts - assets:checking:gifts *-1 - assets:checking *1 - -2017/12/1 - expenses:food $10 - assets:checking - -2017/12/14 - expenses:gifts $20 - assets:checking - -$ hledger print --auto -2017-12-01 - expenses:food $10 - assets:checking - (liabilities:charity) $-1 - -2017-12-14 - expenses:gifts $20 - assets:checking - assets:checking:gifts -$20 - assets:checking $20 - -* Menu: - -* Auto postings and multiple files:: -* Auto postings and dates:: -* Auto postings and transaction balancing / inferred amounts / balance assertions:: -* Auto posting tags:: - - -File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings - -10.27.1.1 Auto postings and multiple files -.......................................... - -An auto posting rule can affect any transaction in the current file, or -in any parent file or child file. Note, currently it will not affect -sibling files (when multiple ‘-f’/‘--file’ are used - see #1212). - - -File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings - -10.27.1.2 Auto postings and dates -................................. - -A posting date (or secondary date) in the matched posting, or (taking -precedence) a posting date in the auto posting rule itself, will also be -used in the generated posting. - - -File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings - -10.27.1.3 Auto postings and transaction balancing / inferred -............................................................ - -amounts / balance assertions Currently, 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. - - This also means that you cannot have more than one auto-posting with -a missing amount applied to a given transaction, as it will be unable to -infer amounts. - - -File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings - -10.27.1.4 Auto posting tags -........................... - -Automated postings will have some extra tags: - - • ‘generated-posting:= QUERY’ - shows this was generated by an auto - posting rule, and the query - • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear - in hledger’s output. This can be used to match postings generated - "just now", rather than generated in the past and saved to the - journal. - - Also, any transaction that has been changed by auto posting rules -will have these tags added: - - • ‘modified:’ - this transaction was modified - • ‘_modified:’ - a hidden tag not appearing in the comment; this - transaction was modified "just now". - - -File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax - -10.27.2 Balance assignments ---------------------------- - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account’s balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). - - Downsides: using balance assignments makes your journal less -explicit; to know the exact amount posted, you have to run hledger or do -the calculations yourself, instead of just reading it. Also balance -assignments’ forcing of balances can hide errors. These things make -your financial data less portable, less future-proof, and less -trustworthy in an audit. - -* Menu: - -* Balance assignments and prices:: - - -File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments - -10.27.2.1 Balance assignments and prices -........................................ - -A cost 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.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax - -10.27.3 Bracketed posting dates -------------------------------- - -For setting posting dates and secondary posting dates, Ledger’s -bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or -‘[=DATE2]’ in posting comments. hledger will attempt to parse any -square-bracketed sequence of the ‘0123456789/-.=’ characters in this -way. With this syntax, DATE infers its year from the transaction and -DATE2 infers its year from DATE. - - Downsides: another syntax to learn, redundant with hledger’s -‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date -syntax. - - -File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax - -10.27.4 ‘D’ directive ---------------------- - -‘D AMOUNT’ - - This directive sets a default commodity, to be used for any -subsequent commodityless amounts (ie, plain numbers) seen while parsing -the journal. This effect lasts until the next ‘D’ directive, or the end -of the journal. - - For compatibility/historical reasons, ‘D’ also acts like a -‘commodity’ directive (setting the commodity’s decimal mark for parsing -and display style for output). So its argument is not just a commodity -symbol, but a full amount demonstrating the style. The amount must -include a decimal mark (either period or comma). Eg: - -; commodity-less amounts should be treated as dollars -; (and displayed with the dollar sign on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity’s display style, a ‘commodity’ directive has -highest priority, then a ‘D’ directive. - - For detecting a commodity’s decimal mark during parsing, -‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’. - - For checking commodity symbols with the check command, a ‘commodity’ -directive is required (‘hledger check commodities’ ignores ‘D’ -directives). - - Downsides: omitting commodity symbols makes your financial data less -explicit, less portable, and less trustworthy in an audit. It is -usually an unsustainable shortcut; sooner or later you will want to -track multiple commodities. D is overloaded with functions redundant -with ‘commodity’ and ‘decimal-mark’. And it works differently from -Ledger’s ‘D’. - - -File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax - -10.27.5 ‘apply account’ directive ---------------------------------- - -This directive sets a default parent account, which will be prepended to -all accounts in following entries, until an ‘end apply account’ -directive or end of current file. Eg: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - ‘account’ directives are also affected, and so is any ‘include’d -content. - - Account names entered via hledger add or hledger-web are not -affected. - - Account aliases, if any, are applied after the parent account is -prepended. - - Downsides: this can make your financial data less explicit, less -portable, and less trustworthy in an audit. - - -File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax - -10.27.6 ‘Y’ directive ---------------------- - -‘Y YEAR’ - - or (deprecated backward-compatible forms): - - ‘year YEAR’ ‘apply year YEAR’ - - The space is optional. This sets a default year to be used for -subsequent dates which don’t specify a year. Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -year 2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at -least) makes your financial data less explicit, less portable, and less -trustworthy in an audit. Such dates can get separated from their -corresponding Y directive, eg when evaluating a region of the journal in -your editor. A missing Y directive makes reports dependent on today’s -date. - - -File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax - -10.27.7 Secondary dates ------------------------ - -A secondary date is written after the primary date, following an equals -sign. If the year is omitted, the primary date’s year is assumed. When -running reports, the primary (left) date is used by default, but with -the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary -(right) date will be used instead. - - The meaning of secondary dates is up to you, but it’s best to follow -a consistent rule. Eg "primary = the bank’s clearing date, secondary = -date the transaction was initiated, if different". - - Downsides: makes your financial data more complicated, less portable, -and less trustworthy in an audit. Keeping the meaning of the two dates -consistent requires discipline, and you have to remember which reporting -mode is appropriate for a given report. Posting dates are simpler and -better. - - -File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax - -10.27.8 Star comments ---------------------- - -Lines beginning with ‘*’ (star/asterisk) are also comment lines. This -feature allows Emacs users to insert org headings in their journal, -allowing them to fold/unfold/navigate it like an outline when viewed -with org mode. - - Downsides: another, unconventional comment syntax to learn. -Decreases your journal’s portability. And switching to Emacs org mode -just for folding/unfolding meant losing the benefits of ledger mode; -nowadays you can add outshine mode to ledger mode to get folding without -losing ledger mode’s features. - - -File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax - -10.27.9 Valuation expressions ------------------------------ - -Ledger allows a valuation function or value to be written in double -parentheses after an amount. hledger ignores these. - - -File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax - -10.27.10 Virtual postings -------------------------- - -A posting with parentheses around the account name is called a _virtual -posting_ or _unbalanced posting_, which means it is exempt from the -usual rule that a transaction’s postings must balance add up to zero. - - This is not part of double entry bookkeeping, so you might choose to -avoid this feature. Or you can use it sparingly for certain special -cases where it can be convenient. Eg, you could set opening balances -without using a balancing equity account: - -2022-01-01 opening balances - (assets:checking) $1000 - (assets:savings) $2000 - - A posting with brackets around the account name is called a _balanced -virtual posting_. The balanced virtual postings in a transaction must -add up to zero (separately from other postings). Eg: - -2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Postings whose account names are neither parenthesised nor bracketed -are called _real postings_. You can exclude virtual postings from -reports with the ‘-R/--real’ flag or a ‘real:1’ query. - - Downsides: violates double entry bookkeeping, can be used to avoid -figuring out correct entries, makes your financial data less portable -and less trustworthy in an audit. - - -File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax - -10.27.11 Other Ledger directives --------------------------------- - -These other Ledger directives are currently accepted but ignored. This -allows hledger to read more Ledger files, but be aware that hledger’s -reports may differ from Ledger’s if you use these. - -apply fixed COMM AMT -apply tag TAG -assert EXPR -bucket / A ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR -end apply fixed -end apply tag -end apply year -end tag -eval / expr EXPR -python - PYTHONCODE -tag NAME -value EXPR ---command-line-flags - - See also https://hledger.org/ledger.html for a detailed -hledger/Ledger syntax comparison. - - -File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top - -11 CSV -****** - -hledger can read CSV files (Character Separated Value - usually comma, -semicolon, or tab) containing dated records, automatically converting -each record into a transaction. - - (To learn about _writing_ CSV, see CSV output.) - - For best error messages when reading CSV/TSV/SSV files, make sure -they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use -a hledger file prefix (see File Extension below). - - Each CSV file must be described by a corresponding _rules file_. -This contains rules describing the CSV data (header line, fields layout, -date format etc.), how to construct hledger transactions from it, and -how to categorise transactions based on description or other attributes. - - By default hledger looks for a rules file named like the CSV file -with an extra ‘.rules’ extension, in the same directory. Eg when asked -to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can -specify a different rules file with the ‘--rules-file’ option. If no -rules file is found, hledger will create a sample rules file, which -you’ll need to adjust. - - At minimum, the rules file must identify the date and amount fields, -and often it also specifies the date format and how many header lines -there are. Here’s a simple CSV file and a rules file for it: - -Date, Description, Id, Amount -12/11/2019, Foo, 123, 10.23 - -# basic.csv.rules -skip 1 -fields date, description, , amount -date-format %d/%m/%Y - -$ hledger print -f basic.csv -2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There’s an introductory Importing CSV data tutorial on hledger.org, -and more CSV rules examples below, and a larger collection at -https://github.com/simonmichael/hledger/tree/master/examples/csv. - -* Menu: - -* CSV rules cheatsheet:: -* separator:: -* skip:: -* date-format:: -* timezone:: -* newest-first:: -* intra-day-reversed:: -* decimal-mark:: -* fields list:: -* Field assignment:: -* Field names:: -* if block:: -* Matchers:: -* if table:: -* balance-type:: -* include:: -* Working with CSV:: -* CSV rules examples:: - - -File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV - -11.1 CSV rules cheatsheet -========================= - -The following kinds of rule can appear in the rules file, in any order. -(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.) - -*‘separator’* declare the field separator, instead of - relying on file extension -*‘skip’* skip one or more header lines at start of file -*‘date-format’* declare how to parse CSV dates/date-times -*‘timezone’* declare the time zone of ambiguous CSV - date-times -*‘newest-first’* improve txn order when: there are multiple - records, newest first, all with the same date -*‘intra-day-reversed’* improve txn order when: same-day txns are in - opposite order to the overall file -*‘decimal-mark’* declare the decimal mark used in CSV amounts, - when ambiguous -*‘fields’ list* name CSV fields for easy reference, and - optionally assign their values to hledger - fields -*Field assignment* assign a CSV value or interpolated text value - to a hledger field -*‘if’ block* conditionally assign values to hledger fields, - or ‘skip’ a record or ‘end’ (skip rest of - file) -*‘if’ table* conditionally assign values to hledger fields, - using compact syntax -*‘balance-type’* select which type of balance - assertions/assignments to generate -*‘include’* inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are -evaluated. - - -File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV - -11.2 ‘separator’ -================ - -You can use the ‘separator’ rule to read other kinds of -character-separated data. The argument is any single separator -character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for -comma-separated values (CSV): - -separator , - - or for semicolon-separated values (SSV): - -separator ; - - or for tab-separated values (TSV): - -separator TAB - - If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a -‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be -inferred automatically, and you won’t need this rule. - - -File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV - -11.3 ‘skip’ -=========== - -skip N - - The word ‘skip’ followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines at the start of the input -data. (Empty/blank lines are skipped automatically, so you don’t need -to count those.) You’ll need this whenever your CSV data contains -header lines. Header lines skipped in this way are ignored, and not -parsed as CSV. - - ‘skip’ can also be used inside if blocks (described below), to skip -individual data records. Note records skipped in this way are still -required to be valid CSV, even though otherwise ignored. - - -File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV - -11.4 ‘date-format’ -================== - -date-format DATEFMT - - This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV -dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, -you’ll need to add a date-format rule describing them with a -strptime-style date parsing pattern - see -https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. -The pattern must parse the CSV date value completely. Some examples: - -# MM/DD/YY -date-format %m/%d/%y - -# D/M/YYYY -# The - makes leading zeros optional. -date-format %-d/%-m/%Y - -# YYYY-Mmm-DD -date-format %Y-%h-%d - -# M/D/YYYY HH:MM AM some other junk -# Note the time and junk must be fully parsed, though only the date is used. -date-format %-m/%-d/%Y %l:%M %p some other junk - - -File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV - -11.5 ‘timezone’ -=============== - -timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone -other than yours, but containing no explicit time zone information, you -can use this rule to declare the CSV’s native time zone, which helps -prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don’t -need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’, -‘%Ez’; see the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware -conversion, localising the CSV date-times to your current system time -zone. If you prefer to localise to some other time zone, eg for -reproducibility, you can (on unix at least) set the output timezone with -the TZ environment variable, eg: - -$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - ‘timezone’ currently does not understand timezone names, except -"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". -For others, use numeric format: +HHMM or -HHMM. - - -File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV - -11.6 ‘newest-first’ -=================== - -hledger tries to ensure that the generated transactions will be ordered -chronologically, including intra-day transactions. Usually it can -auto-detect how the CSV records are ordered. But if it encounters CSV -where all records are on the same date, it assumes that the records are -oldest first. If in fact the CSV’s records are normally newest first, -like: - -2022-10-01, txn 3... -2022-10-01, txn 2... -2022-10-01, txn 1... - - you can add the ‘newest-first’ rule to help hledger generate the -transactions in correct order. - -# same-day CSV records are newest first -newest-first - - -File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV - -11.7 ‘intra-day-reversed’ -========================= - -CSV records for each day are sometimes ordered in reverse compared to -the overall date order. Eg, here dates are newest first, but the -transactions on each date are oldest first: - -2022-10-02, txn 3... -2022-10-02, txn 4... -2022-10-01, txn 1... -2022-10-01, txn 2... - - In this situation, add the ‘intra-day-reversed’ rule, and hledger -will compensate, improving the order of transactions. - -# transactions within each day are reversed with respect to the overall date order -intra-day-reversed - - -File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV - -11.8 ‘decimal-mark’ -=================== - -decimal-mark . - - or: - -decimal-mark , - - hledger automatically accepts either period or comma as a decimal -mark when parsing numbers (cf Amounts). However if any numbers in the -CSV contain digit group marks, such as thousand-separating commas, you -should declare the decimal mark explicitly with this rule, to avoid -misparsed numbers. - - -File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV - -11.9 ‘fields’ list -================== - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word ‘fields’ followed by comma-separated field -names) is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say - ‘%SomeField’ instead of remembering ‘%13’. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger’s fields and - build a transaction. - - Here’s an example that says "use the 1st, 2nd and 4th fields as the -transaction’s date, description and amount; name the last two fields for -later reference; and ignore the others": - -fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to -the CSV file’s separator. Also: - - • There must be least two items in the list (at least one comma). - • Field names may not contain spaces. Spaces before/after field - names are optional. - • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen). - • Fields you don’t care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it’s convenient to use these for -your field names, suitably modified (eg lower-cased with spaces replaced -by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning -to a hledger field with the same name. Eg you could call the CSV’s -"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’ -field (and generating a balance assertion). - - -File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV - -11.10 Field assignment -====================== - -HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to -hledger fields. They can be used instead of or in addition to a fields -list (see above). - - To assign a value to a hledger field, write the field name (any of -the standard hledger field/pseudo-field names, defined below), a space, -followed by a text value on the same line. This text value may -interpolate CSV fields, referenced by their 1-based position in the CSV -record (‘%N’), or by the name they were given in the fields list -(‘%CSVFIELD’). - - Some examples: - -# set the amount to the 4th CSV field, with " USD" appended -amount %4 USD - -# combine three fields to make a comment, containing note: and date: tags -comment note: %somefield - %anotherfield, date: %1 - - Tips: - - • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’ - becomes ‘1’ when interpolated) (#1051). - • Interpolations always refer to a CSV field - you can’t interpolate - a hledger field. (See Referencing other fields below). - - -File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV - -11.11 Field names -================= - -Note the two kinds of field names mentioned here, and used only in -hledger CSV rules files: - - 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally - name the CSV columns for easy reference (since hledger doesn’t yet - automatically recognise column headings in a CSV file), by writing - arbitrary names in a ‘fields’ list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you - must set at least some of these to generate the hledger transaction - from a CSV record, by writing them as the left hand side of a field - assignment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a ‘fields’ list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what -happens when you assign values to them: - -* Menu: - -* date field:: -* date2 field:: -* status field:: -* code field:: -* description field:: -* comment field:: -* account field:: -* amount field:: -* currency field:: -* balance field:: - - -File: hledger.info, Node: date field, Next: date2 field, Up: Field names - -11.11.1 date field ------------------- - -Assigning to ‘date’ sets the transaction date. - - -File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names - -11.11.2 date2 field -------------------- - -‘date2’ sets the transaction’s secondary date, if any. - - -File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names - -11.11.3 status field --------------------- - -‘status’ sets the transaction’s status, if any. - - -File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names - -11.11.4 code field ------------------- - -‘code’ sets the transaction’s code, if any. - - -File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names - -11.11.5 description field -------------------------- - -‘description’ sets the transaction’s description, if any. - - -File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names - -11.11.6 comment field ---------------------- - -‘comment’ sets the transaction’s comment, if any. - - ‘commentN’, where N is a number, sets the Nth posting’s comment. - - You can assign multi-line comments by writing literal ‘\n’ in the -code. A comment starting with ‘\n’ will begin on a new line. - - Comments can contain tags, as usual. - - -File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names - -11.11.7 account field ---------------------- - -Assigning to ‘accountN’, where N is 1 to 99, sets the account name of -the Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you’ll want to set ‘account1’ -and ‘account2’. Typically ‘account1’ is associated with the CSV file, -and is set once with a top-level assignment, while ‘account2’ is set -based on each transaction’s description, in conditional rules. - - If a posting’s account name is left unset but its amount is set (see -below), a default account name will be chosen (like "expenses:unknown" -or "income:unknown"). - - -File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names - -11.11.8 amount field --------------------- - -There are several "amount" field name variants, useful for different -situations: - - • ‘amountN’ sets the amount of the Nth posting, and causes that - posting to be generated. By assigning to ‘amount1’, ‘amount2’, ... - etc. you can generate up to 99 postings. Posting numbers don’t - have to be consecutive; in certain situations using a high number - might be helpful to influence the layout of postings. - - • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair, - when and only when the amount must be obtained from two CSV fields. - Eg when the CSV has separate Debit and Credit fields instead of a - single Amount field. Note: - - • Don’t think "-in is for the first posting and -out is for the - second posting" - that’s not correct. Think: "‘amountN-in’ - and ‘amountN-out’ together detect the amount for posting N, by - inspecting two CSV fields at once." - • hledger assumes both CSV fields are unsigned, and will - automatically negate the -out value. - • It also expects that at least one of the values is empty or - zero, so it knows which one to ignore. If that’s not the case - you’ll need an if rule (see Setting amounts below). - - • ‘amount’, with no posting number (and similarly, ‘amount-in’ and - ‘amount-out’ with no number) are an older syntax. We keep them for - backwards compatibility, and because they have special behaviour - that is sometimes convenient: - - • They set the amount of posting 1 and (negated) the amount of - posting 2. - • Posting 2’s amount will be converted to cost if it has a cost - price. - • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or - ‘amount2-in’ and ‘amount2-out’) will take precedence. This - allows incrementally migrating old rules files to the new - syntax. - - There’s more to say about amount-setting that doesn’t fit here; -please see also "Setting amounts" below. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -11.11.9 currency field ----------------------- - -‘currency’ sets a currency symbol, to be prepended to all postings’ -amounts. You can use this if the CSV amounts do not have a currency -symbol, eg if it is in a separate column. - - ‘currencyN’ prepends a currency symbol to just the Nth posting’s -amount. - - -File: hledger.info, Node: balance field, Prev: currency field, Up: Field names - -11.11.10 balance field ----------------------- - -‘balanceN’ sets a balance assertion amount (or if the posting amount is -left empty, a balance assignment) on posting N. - - ‘balance’ is a compatibility spelling for hledger <1.17; it is -equivalent to ‘balance1’. - - You can adjust the type of assertion/assignment with the -‘balance-type’ rule (see below). - - See Tips below for more about setting amounts and currency. - - -File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV - -11.12 ‘if’ block -================ - -Rules can be applied conditionally, depending on patterns in the CSV -data. This allows flexibility; in particular, it is how you can -categorise transactions, selecting an appropriate account name based on -their description (for example). There are two ways to write -conditional rules: "if blocks", described here, and "if tables", -described below. - - An if block is the word ‘if’ and one or more "matcher" expressions -(can be a word or phrase), one per line, starting either on the same or -next line; followed by one or more indented rules. Eg, - -if MATCHER - RULE - - or - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be -applied. They are usually field assignments, but the following special -rules may also be used within an if block: - - • ‘skip’ - skips the matched CSV record (generating no transaction - from it) - • ‘end’ - skips the rest of the current CSV file. - - Some examples: - -# if the record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the record contains any of these phrases, set account2 and a transaction comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - -# if an empty record is seen (assuming five fields), ignore the rest of the CSV file -if ,,,, - end - - -File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV - -11.13 Matchers -============== - -There are two kinds: - - 1. A record matcher is a word or single-line text fragment or regular - expression (‘REGEX’), which hledger will try to match - case-insensitively anywhere within the CSV record. - Eg: ‘whole foods’ - - 2. A field matcher is preceded with a percent sign and CSV field name - (‘%CSVFIELD REGEX’). hledger will try to match these just within - the named CSV field. - Eg: ‘%date 2023’ - - The regular expression is (as usual in hledger) a POSIX extended -regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’, -‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular -expressions" in the hledger manual -(https://hledger.org/hledger.html#regular-expressions). - - With record matchers, it’s important to know that the record matched -is not the original CSV record, but a modified one: separators will be -converted to commas, and enclosing double quotes (but not enclosing -whitespace) are removed. So for example, when reading an SSV file, if -the original record was: - -2020-01-01; "Acme, Inc."; 1,000 - - the regex would see, and try to match, this modified record text: - -2020-01-01,Acme, Inc., 1,000 - - When an if block has multiple matchers, they are combined as follows: - - • By default they are OR’d (any one of them can match) - • When a matcher is preceded by ampersand (‘&’) it will be AND’ed - with the previous matcher (both of them must match). - - There’s not yet an easy syntax to negate a matcher. - - -File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV - -11.14 ‘if’ table -================ - -"if tables" are an alternative to if blocks; they can express many -matchers and field assignments in a more compact tabular format, like -this: - -if,HLEDGERFIELD1,HLEDGERFIELD2,... -MATCHERA,VALUE1,VALUE2,... -MATCHERB,VALUE1,VALUE2,... -MATCHERC,VALUE1,VALUE2,... - - - The first character after ‘if’ is taken to be the separator for the -rest of the table. It should be a non-alphanumeric character like ‘,’ -or ‘|’ that does not appear anywhere else in the table. (Note: it is -unrelated to the CSV file’s separator.) Whitespace can be used in the -matcher lines for readability, but not in the if line currently. The -table must be terminated by an empty line (or end of file). Each line -must contain the same number of separators; empty values are allowed. - - The above means: try all of the matchers; whenever a matcher -succeeds, assign all of the values on that line to the corresponding -hledger fields; later lines can overrider earlier ones. It is -equivalent to this sequence of if blocks: - -if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERB - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - -if,account2,comment -atm transaction fee,expenses:business:banking,deductible? check it -%description groceries,expenses:groceries, -2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - -File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV - -11.15 ‘balance-type’ -==================== - -Balance assertions generated by assigning to balanceN are of the simple -‘=’ type by default, which is a single-commodity, subaccount-excluding -assertion. You may find the subaccount-including variants more useful, -eg if you have created some virtual subaccounts of checking to help with -budgeting. You can select a different type of assertion with the -‘balance-type’ rule: - -# balance assertions will consider all commodities and all subaccounts -balance-type ==* - - Here are the balance assertion types for quick reference: - -= single commodity, exclude subaccounts -=* single commodity, include subaccounts -== multi commodity, exclude subaccounts -==* multi commodity, include subaccounts - - -File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV - -11.16 ‘include’ -=============== - -include RULESFILE - - This includes the contents of another CSV rules file at this point. -‘RULESFILE’ is an absolute file path or a path relative to the current -file’s directory. This can be useful for sharing common rules between -several rules files, eg: - -# someaccount.csv.rules - -## someaccount-specific rules -fields date,description,amount -account1 assets:someaccount -account2 expenses:misc - -## common rules -include categorisation.rules - - -File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV - -11.17 Working with CSV -====================== - -Some tips: - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading CSV from standard input:: -* Reading multiple CSV files:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Amount signs:: -* Setting currency/commodity:: -* Amount decimal places:: -* Referencing other fields:: -* How CSV rules are evaluated:: -* Well factored rules:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV - -11.17.1 Rapid feedback ----------------------- - -It’s a good idea to get rapid feedback while creating/troubleshooting -CSV rules. Here’s a good way, using entr from eradman.com/entrproject: - -$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - - A desc: query (eg) is used to select just one, or a few, transactions -of interest. "bash -c" is used to run multiple commands, so we can echo -a separator each time the command re-runs, making it easier to read the -output. - - -File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV - -11.17.2 Valid CSV ------------------ - -Note that hledger will only accept valid CSV conforming to RFC 4180, and -equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab -as separators). This means, eg: - - • Values may be enclosed in double quotes, or not. Enclosing in - single quotes is not allowed. (Eg ‘'A','B'’ is rejected.) - • When values are enclosed in double quotes, spaces outside the - quotes are not allowed. (Eg ‘"A", "B"’ is rejected.) - • When values are not enclosed in quotes, they may not contain double - quotes. (Eg ‘A"A, B’ is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you’ll need to -transform it before reading with hledger. Try using sed, or a more -permissive CSV parser like python’s csv lib. - - -File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV - -11.17.3 File Extension ----------------------- - -To help hledger choose the CSV file reader and show the right error -messages (and choose the right field separator character by default), -it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’ -filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV -reader (and the default field separator) by prefixing the file path with -‘csv:’, ‘ssv:’ or ‘tsv:’: Eg: - -$ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator -rule if needed. - - -File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV - -11.17.4 Reading CSV from standard input ---------------------------------------- - -You’ll need the file format prefix when reading CSV from stdin also, -since hledger assumes journal format by default. Eg: - -$ cat foo.dat | hledger -f ssv:- print - - -File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV - -11.17.5 Reading multiple CSV files ----------------------------------- - -If you use multiple ‘-f’ options to read multiple CSV files at once, -hledger will look for a correspondingly-named rules file for each CSV -file. But if you use the ‘--rules-file’ option, that rules file will be -used for all the CSV files. - - -File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV - -11.17.6 Valid transactions --------------------------- - -After reading a CSV file, hledger post-processes and validates the -generated journal entries as it would for a journal file - balancing -them, applying balance assignments, and canonicalising amount styles. -Any errors at this stage will be reported in the usual way, displaying -the problem entry. - - There is one exception: balance assertions, if you have generated -them, will not be checked, since normally these will work only when the -CSV data is part of the main journal. If you do need to check balance -assertions generated from CSV right away, pipe into another hledger: - -$ hledger -f file.csv print | hledger -f- print - - -File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV - -11.17.7 Deduplicating, importing --------------------------------- - -When you download a CSV file periodically, eg to get your latest bank -transactions, the new file may overlap with the old one, containing some -of the same records. - - The import command will (a) detect the new transactions, and (b) -append just those transactions to your main journal. It is idempotent, -so you don’t have to remember how many times you ran it or with which -version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’ -file.) This is the easiest way to import CSV data. Eg: - -# download the latest CSV files, then run this command. -# Note, no -f flags needed here. -$ hledger import *.csv [--dry] - - This method works for most CSV files. (Where records have a stable -chronological order, and new records appear only at the new end.) - - A number of other tools and workflows, hledger-specific and -otherwise, exist for converting, deduplicating, classifying and managing -CSV data. See: - - • https://hledger.org/cookbook.html#setups-and-workflows - • https://plaintextaccounting.org -> data import/conversion - - -File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV - -11.17.8 Setting amounts ------------------------ - -Continuing from amount field above, here are more tips on handling -various amount-setting situations: - - 1. *If the amount is in a single CSV field:* - - a. *If its sign indicates direction of flow:* - Assign it to ‘amountN’, to set the Nth posting’s amount. N is - usually 1 or 2 but can go up to 99. - - b. *If another field indicates direction of flow:* - Use one or more conditional rules to set the appropriate - amount sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. *If the amount is in one of two CSV fields (eg Debit and Credit):* - - a. *If both fields are unsigned:* - Assign the fields to ‘amountN-in’ and ‘amountN-out’. This - sets posting N’s amount to whichever of these has a non-zero - value. If it’s the -out value, the amount will be negated. - - b. *If either field is signed:* - Use a conditional rule to flip the sign when needed. Eg - below, the -out value already has a minus sign so we undo - hledger’s automatic negating by negating once more (but only - if the field is non-empty, so that we don’t leave a minus sign - by itself): - - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields can contain a non-zero value (or both can be - empty):* - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such - as ‘1’ and ‘none’. For such cases, use conditional rules to - help select the amount. Eg, to handle the above you could - select the value containing non-zero digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. *If you want posting 2’s amount converted to cost:* - Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’) - syntax. - - 4. *If the CSV has only balance amounts, not transaction amounts:* - Assign to ‘balanceN’, to set a balance assignment on the Nth - posting, causing the posting’s amount to be calculated - automatically. ‘balance’ with no number is equivalent to - ‘balance1’. In this situation hledger is more likely to guess the - wrong default account name, so you may need to set that explicitly. - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV - -11.17.9 Amount signs --------------------- - -There is some special handling for amount signs, to simplify parsing and -sign-flipping: - - • *If an amount value begins with a plus sign:* - that will be removed: ‘+AMT’ becomes ‘AMT’ - - • *If an amount value is parenthesised:* - it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes - ‘-AMT’ - - • *If an amount value has two minus signs (or two sets of - parentheses, or a minus sign and parentheses):* - they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes - ‘AMT’ - - • *If an amount value contains just a sign (or just a set of - parentheses):* - that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or - ‘"()"’ becomes ‘""’. - - -File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV - -11.17.10 Setting currency/commodity ------------------------------------ - -If the currency/commodity symbol is included in the CSV’s amount -field(s): - -2020-01-01,foo,$123.00 - - you don’t have to do anything special for the commodity symbol, it -will be assigned as part of the amount. Eg: - -fields date,description,amount - -2020-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - -2020-01-01,foo,USD,123.00 - - You can assign that to the ‘currency’ pseudo-field, which has the -special effect of prepending itself to every amount in the transaction -(on the left, with no separating space): - -fields date,description,currency,amount - -2020-01-01 foo - expenses:unknown USD123.00 - income:unknown USD-123.00 - - Or, you can use a field assignment to construct the amount yourself, -with more control. Eg to put the symbol on the right, and separated by -a space: - -fields date,description,cur,amt -amount %amt %cur - -2020-01-01 foo - expenses:unknown 123.00 USD - income:unknown -123.00 USD - - Note we used a temporary field name (‘cur’) that is not ‘currency’ - -that would trigger the prepending effect, which we don’t want here. - - -File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV - -11.17.11 Amount decimal places ------------------------------- - -Like amounts in a journal file, the amounts generated by CSV rules like -‘amount1’ influence commodity display styles, such as the number of -decimal places displayed in reports. - - The original amounts as written in the CSV file do not affect display -style (because we don’t yet reliably know their commodity). - - -File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV - -11.17.12 Referencing other fields ---------------------------------- - -In field assignments, you can interpolate only CSV fields, not hledger -fields. In the example below, there’s both a CSV field and a hledger -field named amount1, but %amount1 always means the CSV field, not the -hledger field: - -# Name the third CSV field "amount1" -fields date,description,amount1 - -# Set hledger's amount1 to the CSV amount1 field followed by USD -amount1 %amount1 USD - -# Set comment to the CSV amount1 (not the amount1 assigned above) -comment %amount1 - - Here, since there’s no CSV amount1 field, %amount1 will produce a -literal "amount1": - -fields date,description,csvamount -amount1 %csvamount USD -# Can't interpolate amount1 here -comment %amount1 - - When there are multiple field assignments to the same hledger field, -only the last one takes effect. Here, comment’s value will be be B, or -C if "something" is matched, but never A: - -comment A -comment B -if something - comment C - - -File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV - -11.17.13 How CSV rules are evaluated ------------------------------------- - -Here’s how to think of CSV rules being evaluated (if you really need -to). First, - - • ‘include’ - all includes are inlined, from top to bottom, depth - first. (At each include point the file is inlined and scanned for - further includes, recursively, before proceeding.) - - Then "global" rules are evaluated, top to bottom. If a rule is -repeated, the last one wins: - - • ‘skip’ (at top level) - • ‘date-format’ - • ‘newest-first’ - • ‘fields’ - names the CSV fields, optionally sets up initial - assignments to hledger fields - - Then for each CSV record in turn: - - • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip - all remaining CSV records. Otherwise if any of them contain a - ‘skip’ rule, skip that many CSV records. If there are multiple - matched ‘skip’ rules, the first one wins. - • collect all field assignments at top level and in matched ‘if’ - blocks. When there are multiple assignments for a field, keep only - the last one. - • compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELD references), or a - default - • generate a hledger transaction (journal entry) from these values. - - This is all part of the CSV reader, one of several readers hledger -can use to parse input files. When all files have been read -successfully, the transactions are passed as input to whichever hledger -command the user specified. - - -File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV - -11.17.14 Well factored rules ----------------------------- - -Some things than can help reduce duplication and complexity in rules -files: - - • Extracting common rules usable with multiple CSV files into a - ‘common.rules’, and adding ‘include common.rules’ to each CSV’s - rules file. - - • Splitting if blocks into smaller if blocks, extracting the - frequently used parts. - - -File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV - -11.18 CSV rules examples -======================== - -* Menu: - -* Bank of Ireland:: -* Coinbase:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples - -11.18.1 Bank of Ireland ------------------------ - -Here’s a CSV with two amount fields (Debit and Credit), and a balance -field, which we can use to add balance assertions, which is not -necessary but provides extra error checking: - -Date,Details,Debit,Credit,Balance -07/12/2012,LODGMENT 529898,,10.0,131.21 -07/12/2012,PAYMENT,5,,126 - -# bankofireland-checking.csv.rules - -# skip the header line -skip - -# name the csv fields, and assign some of them as journal entry fields -fields date, description, amount-out, amount-in, balance - -# We generate balance assertions by assigning to "balance" -# above, but you may sometimes need to remove these because: -# -# - the CSV balance differs from the true balance, -# by up to 0.0000000000005 in my experience -# -# - it is sometimes calculated based on non-chronological ordering, -# eg when multiple transactions clear on the same day - -# date is in UK/Ireland format -date-format %d/%m/%Y - -# set the currency -currency EUR - -# set the base account for all txns -account1 assets:bank:boi:checking - -$ hledger -f bankofireland-checking.csv print -2012-12-07 LODGMENT 529898 - assets:bank:boi:checking EUR10.0 = EUR131.2 - income:unknown EUR-10.0 - -2012-12-07 PAYMENT - assets:bank:boi:checking EUR-5.0 = EUR126.0 - expenses:unknown EUR5.0 - - The balance assertions don’t raise an error above, because we’re -reading directly from CSV, but they will be checked if these entries are -imported into a journal file. - - -File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples - -11.18.2 Coinbase ----------------- - -A simple example with some CSV from Coinbase. The spot price is -recorded using cost notation. The legacy ‘amount’ field name -conveniently sets amount 2 (posting 2’s amount) to the total cost. - -# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes -# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - -# coinbase.csv.rules -skip 1 -fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes -date %Timestamp -date-format %Y-%m-%dT%T%Z -description %Notes -account1 assets:coinbase:cc -amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - -$ hledger print -f coinbase.csv -2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - -File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples - -11.18.3 Amazon --------------- - -Here we convert amazon.com order history, and use an if block to -generate a third posting if there’s a fee. (In practice you’d probably -get this data from your bank instead, but it’s an example.) - -"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" -"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" -"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" - -# amazon-orders.csv.rules - -# skip one header line -skip 1 - -# name the csv fields, and assign the transaction's date, amount and code. -# Avoided the "status" and "amount" hledger field names to prevent confusion. -fields date, _, toorfrom, name, amzstatus, amzamount, fees, code - -# how to parse the date -date-format %b %-d, %Y - -# combine two fields to make the description -description %toorfrom %name - -# save the status as a tag -comment status:%amzstatus - -# set the base account for all transactions -account1 assets:amazon -# leave amount1 blank so it can balance the other(s). -# I'm assuming amzamount excludes the fees, don't remember - -# set a generic account2 -account2 expenses:misc -amount2 %amzamount -# and maybe refine it further: -#include categorisation.rules - -# add a third posting for fees, but only if they are non-zero. -if %fees [1-9] - account3 expenses:fees - amount3 %fees - -$ hledger -f amazon-orders.csv print -2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed - assets:amazon - expenses:misc $20.00 - -2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed - assets:amazon - expenses:misc $25.00 - expenses:fees $1.00 - - -File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples - -11.18.4 Paypal --------------- - -Here’s a real-world rules file for (customised) Paypal CSV, with some -Paypal-specific rules, and a second rules file included: - -"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" -"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" -"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" -"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" -"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" -"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" -"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" -"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" - -# paypal-custom.csv.rules - -# Tips: -# Export from Activity -> Statements -> Custom -> Activity download -# Suggested transaction type: "Balance affecting" -# Paypal's default fields in 2018 were: -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" -# This rules file assumes the following more detailed fields, configured in "Customize report fields": -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" - -fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note - -skip 1 - -date-format %-m/%-d/%Y - -# ignore some paypal events -if -In Progress -Temporary Hold -Update to - skip - -# add more fields to the description -description %description_ %itemtitle - -# save some other fields as tags -comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ - -# convert to short currency symbols -if %currency USD - currency $ -if %currency EUR - currency E -if %currency GBP - currency P - -# generate postings - -# the first posting will be the money leaving/entering my paypal account -# (negative means leaving my account, in all amount fields) -account1 assets:online:paypal -amount1 %netamount - -# the second posting will be money sent to/received from other party -# (account2 is set below) -amount2 -%grossamount - -# if there's a fee, add a third posting for the money taken by paypal. -if %feeamount [1-9] - account3 expenses:banking:paypal - amount3 -%feeamount - comment3 business: - -# choose an account for the second posting - -# override the default account names: -# if the amount is positive, it's income (a debit) -if %grossamount ^[^-] - account2 income:unknown -# if negative, it's an expense (a credit) -if %grossamount ^- - account2 expenses:unknown - -# apply common rules for setting account2 & other tweaks -include common.rules - -# apply some overrides specific to this csv - -# Transfers from/to bank. These are usually marked Pending, -# which can be disregarded in this case. -if -Bank Account -Bank Deposit to PP Account - description %type for %referencetxnid %itemtitle - account2 assets:bank:wf:pchecking - account1 assets:online:paypal - -# Currency conversions -if Currency Conversion - account2 equity:currency conversion - -# common.rules - -if -darcs -noble benefactor - account2 revenues:foss donations:darcshub - comment2 business: - -if -Calm Radio - account2 expenses:online:apps - -if -electronic frontier foundation -Patreon -wikimedia -Advent of Code - account2 expenses:dues - -if Google - account2 expenses:online:apps - description google | music - -$ hledger -f paypal-custom.csv print -2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed - assets:online:paypal $-6.99 = $-6.99 - expenses:online:apps $6.99 - -2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $6.99 = $0.00 - assets:bank:wf:pchecking $-6.99 - -2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed - assets:online:paypal $-7.00 = $-7.00 - expenses:dues $7.00 - -2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $7.00 = $0.00 - assets:bank:wf:pchecking $-7.00 - -2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed - assets:online:paypal $-2.00 = $-2.00 - expenses:dues $2.00 - expenses:banking:paypal ; business: - -2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $2.00 = $0.00 - assets:bank:wf:pchecking $-2.00 - -2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed - assets:online:paypal $9.41 = $9.41 - revenues:foss donations:darcshub $-10.00 ; business: - expenses:banking:paypal $0.59 ; business: - - -File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top - -12 Timeclock -************ - -The time logging format of timeclock.el, as read by hledger. - - hledger can read time logs in timeclock format. As with Ledger, -these are (a subset of) timeclock.el’s format, containing clock-in and -clock-out entries as in the example below. The date is a simple date. -The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are -optional. The timezone, if present, must be four digits and is ignored -(currently the time is always interpreted as a local time). Lines -beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored. - -i 2015/03/30 09:00:00 some:account name optional description after two spaces -o 2015/03/30 09:20:00 -i 2015/03/31 22:21:45 another account -o 2015/04/01 02:00:34 - - hledger treats each clock-in/clock-out pair as a transaction posting -some number of hours to an account. Or if the session spans more than -one day, it is split into several transactions, one for each day. For -the above time log, ‘hledger print’ generates these journal entries: - -$ hledger -f t.timeclock print -2015-03-30 * optional description after two spaces - (some:account name) 0.33h - -2015-03-31 * 22:21-23:59 - (another account) 1.64h - -2015-04-01 * 00:00-02:00 - (another account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - -$ hledger -f sample.timeclock balance # current time balances -$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 -$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - • use emacs and the built-in timeclock.el, or the extended - timeclock-x.el and perhaps the extras in ledgerutils.el - - • at the command line, use these bash aliases: ‘shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’ - - • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository. - These rely on a "timeclock" executable which I think is just the - ledger 2 executable renamed. - - -File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top - -13 Timedot -********** - -‘timedot’ format is hledger’s human-friendly time logging format. -Compared to ‘timeclock’ format, it is - - • convenient for quick, approximate, and retroactive time logging - • readable: you can see at a glance where time was spent. - - A timedot file contains a series of day entries, which might look -like this: - -2021-08-04 -hom:errands .... .... -fos:hledger:timedot .. ; docs -per:admin:finance - - hledger reads this as three time transactions on this day, with each -dot representing a quarter-hour spent: - -$ hledger -f a.timedot print # .timedot file extension activates the timedot reader -2021-08-04 * - (hom:errands) 2.00 - -2021-08-04 * - (fos:hledger:timedot) 0.50 - -2021-08-04 * - (per:admin:finance) 0 - - A day entry begins with a date line: - - • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D). - - Optionally this can be followed on the same line by - - • a common *transaction description* for this day - • a common *transaction comment* for this day, after a semicolon - (‘;’). - - After the date line are zero or more optionally-indented time -transaction lines, consisting of: - - • an *account name* - any word or phrase, usually a hledger-style - account name. - • *two or more spaces* - a field separator, required if there is an - amount (as in journal format). - • a *timedot amount* - dots representing quarter hours, or a number - representing hours. - • an optional *comment* beginning with semicolon. This is ignored. - - In more detail, timedot amounts can be: - - • *dots*: zero or more period characters, each representing one - quarter-hour. Spaces are ignored and can be used for grouping. - Eg: ‘.... ..’ - - • a *number*, representing hours. Eg: ‘1.5’ - - • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’, - ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days - weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following - equivalencies are assumed: - ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ = - ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the - generated transaction amount, which is always in hours.) - - There is some added flexibility to help with keeping time log data in -the same file as your notes, todo lists, etc.: - - • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored. - - • Before the first date line, lines beginning with ‘*’ are ignored. - From the first date line onward, a sequence of ‘*’’s followed by a - space at beginning of lines (ie, the headline prefix used by Emacs - Org mode) is ignored. This means the time log can be kept under an - Org headline, and date lines or time transaction lines can be Org - headlines. - - • Lines not ending with a double-space and amount are parsed as - transactions with zero amount. (Most hledger reports hide these by - default; add -E to see them.) - - More examples: - -# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. -2016/2/1 -inc:client1 .... .... .... .... .... .... -fos:haskell .... .. -biz:research . - -2016/2/2 -inc:client1 .... .... -biz:research . - -2016/2/3 -inc:client1 4 -fos:hledger 3 -biz:research 1 - -* Time log -** 2020-01-01 -*** adm:time . -*** adm:finance . - -* 2020 Work Diary -** Q1 -*** 2020-02-29 -**** DONE -0700 yoga -**** UNPLANNED -**** BEGUN -hom:chores - cleaning ... - water plants - outdoor - one full watering can - indoor - light watering -**** TODO -adm:planning: trip -*** LATER - - Reporting: - -$ hledger -f a.timedot print date:2016/2/2 -2016-02-02 * - (inc:client1) 2.00 - -2016-02-02 * - (biz:research) 0.25 - -$ hledger -f a.timedot bal --daily --tree -Balance changes in 2016-02-01-2016-02-03: - - || 2016-02-01d 2016-02-02d 2016-02-03d -============++======================================== - biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 -------------++---------------------------------------- - || 7.75 2.25 8.00 - - Using period instead of colon as account name separator: - -2016/2/4 -fos.hledger.timedot 4 -fos.ledger .. - -$ hledger -f a.timedot --alias /\\./=: bal --tree - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger --------------------- - 4.50 - - A sample.timedot file. - - -File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top - -14 PART 3: REPORTING CONCEPTS -***************************** - - -File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top - -15 Time periods -*************** - -* Menu: - -* Report start & end date:: -* Smart dates:: -* Report intervals:: -* Date adjustment:: -* Period expressions:: - - -File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods - -15.1 Report start & end date -============================ - -By default, most hledger reports will show the full span of time -represented by the journal. The report start date will be the earliest -transaction or posting date, and the report end date will be the latest -transaction, posting, or market price date. - - 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 (below). - - Some notes: - - • End dates are exclusive, as in Ledger, so you should write the date - _after_ the last day you want to see in the report. - • As noted in reporting options: among start/end dates specified with - _options_, the last (i.e. right-most) option takes precedence. - • The effective report start and end dates are the intersection of - the start/end dates from options and that from ‘date:’ queries. - That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January - 2019, the smallest common time span. - • In some cases a report interval will adjust start/end dates to fall - on interval boundaries (see below). - - Examples: - -‘-b begin on St. Patrick’s day 2016 -2016/3/17’ -‘-e 12/1’ end at the start of december 1st of the current year - (11/30 will be the last date included) -‘-b all transactions on or after the 1st of the current month -thismonth’ -‘-p all transactions in the current month -thismonth’ -‘date:2016/3/17..’the above written as queries instead (‘..’ can also be - replaced with ‘-’) -‘date:..12/1’ -‘date:thismonth..’ -‘date:thismonth’ - - -File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods - -15.2 Smart dates -================ - -hledger’s user interfaces accept a "smart date" syntax for added -convenience. Smart dates optionally can be relative to today’s date, be -written with english words, and have less-significant parts omitted -(missing parts are inferred as 1). Some examples: - -‘2004/10/1’, exact date, several separators allowed. Year -‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31 -‘2004.9.1’ -‘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, -1, 0, 1 days from today -tomorrow’ -‘last/this/next -1, 0, 1 periods from the current period -day/week/month/quarter/year’ -‘in n n periods from the current period -days/weeks/months/quarters/years’ -‘n n periods from the current period -days/weeks/months/quarters/years -ahead’ -‘n -n periods from the current period -days/weeks/months/quarters/years -ago’ -‘20181201’ 8 digit YYYYMMDD with valid year month and - day -‘201812’ 6 digit YYYYMM with valid year and month - - Some 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 - - "Today’s date" can be overridden with the ‘--today’ option, in case -it’s needed for testing or for recreating old reports. (Except for -periodic transaction rules, which are not affected by ‘--today’.) - - -File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods - -15.3 Report intervals -===================== - -A report interval can be specified so that reports like register, -balance or activity become multi-period, showing each subperiod as a -separate row or column. - - The following standard intervals can be enabled with command-line -flags: - - • ‘-D/--daily’ - • ‘-W/--weekly’ - • ‘-M/--monthly’ - • ‘-Q/--quarterly’ - • ‘-Y/--yearly’ - - More complex intervals can be specified using ‘-p/--period’, -described below. - - -File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods - -15.4 Date adjustment -==================== - -With a report interval (other than daily), report start / end dates -which have not been specified explicitly and in full (eg not ‘-b -2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are -considered flexible: - - • A flexible start date will be automatically adjusted earlier if - needed to fall on a natural interval boundary. - • Similarly, a flexible end date will be adjusted later if needed to - make the last period a whole interval (the same length as the - others). - - This is convenient for producing clean periodic reports (this is -traditional hledger behaviour). By contrast, fully-specified exact -dates will not be adjusted (this is new in hledger 1.29). - - An example: with a journal whose first date is 2023-01-10 and last -date is 2023-03-20: - - • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’ - The report periods will begin on the 15th day of each month, - starting from 2023-01-15, and the last period’s last day will be - 2023-03-09. (Exact start and end dates, neither is adjusted.) - - • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’ - The report periods will begin on the 1st of each month, starting - from 2023-01-01, and the last period’s last day will be 2023-03-31. - (Flexible start and end dates, both are adjusted.) - - -File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods - -15.5 Period expressions -======================= - -The ‘-p/--period’ option specifies a period expression, which is a -compact way of expressing a start date, end date, and/or report -interval. - - Here’s a period expression with a start and end date (specifying the -first quarter of 2009): - -‘-p "from 2009/1/1 to 2009/4/1"’ - - Several keywords like "from" and "to" are supported for readability; -these are optional. "to" can also be written as ".." or "-". The -spaces are also optional, as long as you don’t run two dates together. -So the following 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, these are also -equivalent to the above: - -‘-p "1/1 4/1"’ -‘-p "jan-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 date in the journal: - -‘-p "from 2009/1/1"’ everything after january 1, 2009 -‘-p "since 2009/1"’ the same, since is a synonym -‘-p "from 2009"’ the same -‘-p "to 2009"’ everything before january 1, 2009 - - You can also specify a period by writing a single partial or full -date: - -‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1” -‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to - 2009/2/1” -‘-p the first day of 2009; equivalent to “2009/1/1 to -"2009/1/1"’ 2009/1/2” - - or by using the "Q" quarter-year syntax (case insensitive): - -‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to - 2009/4/1” -‘-p "q4"’ fourth quarter of the current year - -* Menu: - -* Period expressions with a report interval:: -* More complex report intervals:: -* Multiple weekday intervals:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -15.5.1 Period expressions with a report interval ------------------------------------------------- - -A period expression can also begin with a report interval, separated -from the start/end dates (if any) by a space or the word ‘in’: - -‘-p "weekly from 2009/1/1 to 2009/4/1"’ -‘-p "monthly in 2008"’ -‘-p "quarterly"’ - - -File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions - -15.5.2 More complex report intervals ------------------------------------- - -Some more complex intervals can be specified within period expressions, -such as: - - • ‘biweekly’ (every two weeks) - • ‘fortnightly’ - • ‘bimonthly’ (every two months) - • ‘every day|week|month|quarter|year’ - • ‘every N days|weeks|months|quarters|years’ - - Weekly on a custom day: - - • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted - after the number) - • ‘every WEEKDAYNAME’ (full or three-letter english weekday name, - case insensitive) - - Monthly on a custom day: - - • ‘every Nth day [of month]’ - • ‘every Nth WEEKDAYNAME [of month]’ - - Yearly on a custom day: - - • ‘every MM/DD [of year]’ (month number and day of month number) - • ‘every MONTHNAME DDth [of year]’ (full or three-letter english - month name, case insensitive, and day of month number) - • ‘every DDth MONTHNAME [of year]’ (equivalent to the above) - - Examples: - -‘-p "bimonthly from -2008"’ -‘-p "every 2 weeks"’ -‘-p "every 5 months from -2009/03"’ -‘-p "every 2nd day of periods will go from Tue to Tue -week"’ -‘-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 - November -‘-p "every 5th November"’ same -‘-p "every Nov 5th"’ same - - Show historical balances at end of the 15th day of each month (N is -an end date, exclusive as always): - -$ hledger balance -H -p "every 16th day" - - Group postings from the start of wednesday to end of the following -tuesday (N is both (inclusive) start date and (exclusive) end date): - -$ hledger register checking -p "every 3rd day of week" - - -File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions - -15.5.3 Multiple weekday intervals ---------------------------------- - -This special form is also supported: - - • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english - weekday names, case insensitive) - - Also, ‘weekday’ and ‘weekendday’ are shorthand for -‘mon,tue,wed,thu,fri’ and ‘sat,sun’. - - This is mainly intended for use with ‘--forecast’, to generate -periodic transactions on arbitrary days of the week. It may be less -useful with ‘-p’, since it divides each week into subperiods of unequal -length, which is unusual. (Related: #1632) - - Examples: - -‘-p "every dates will be Mon, Wed, Fri; periods will be -mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun -‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will -weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun -‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri -weekendday"’ - - -File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top - -16 Depth -******** - -With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show -accounts only to the specified depth, hiding deeper subaccounts. Use -this when you want a summary with less detail. This flag has the same -effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are -equivalent. - - -File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top - -17 Queries -********** - -One of hledger’s strengths is being able to quickly report on a precise -subset of your data. Most hledger commands accept optional query -arguments to restrict their scope. The syntax is as follows: - - • Zero or more space-separated query terms. These are most often - account name substrings: - - ‘utilities food:groceries’ - - • Terms with spaces or other special characters should be enclosed in - quotes: - - ‘"personal care"’ - - • Regular expressions are also supported: - - ‘"^expenses\b" "accounts (payable|receivable)"’ - - • Add a query type prefix to match other parts of the data: - - ‘date:202012- desc:amazon cur:USD amt:">100" status:’ - - • Add a ‘not:’ prefix to negate a term: - - ‘not:cur:USD’ - -* Menu: - -* Query types:: -* Combining query terms:: -* Queries and command options:: -* Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value:: - - -File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries - -17.1 Query types -================ - -Here are the types of query term available. Remember these can also be -prefixed with *‘not:’* to convert them into a negative match. - - *‘acct:REGEX’, ‘REGEX’* -Match account names containing this (case insensitive) regular -expression. This is the default query type when there is no prefix, and -regular expression syntax is typically not needed, so usually we just -write an account name substring, like ‘expenses’ or ‘food’. - - *‘amt:N, amt:N, amt:>=N’* -Match postings with a single-commodity amount equal to, less than, or -greater than N. (Postings with 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 special characters which are -regex-significant, you need to escape them with ‘\’. And for characters -which are significant to your shell you may need one more level of -escaping. So eg to match the dollar sign: -‘hledger print cur:\\$’. - - *‘desc:REGEX’* -Match transaction descriptions. - - *‘date:PERIODEXPR’* -Match dates (or with the ‘--date2’ flag, secondary dates) within the -specified period. PERIODEXPR is a period expression with no report -interval. Examples: -‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’, -‘date:2021-07-27..nextquarter’. - - *‘date2:PERIODEXPR’* -Match secondary dates within the specified period (independent of the -‘--date2’ flag). - - *‘depth:N’* -Match (or display, depending on command) accounts at or above this -depth. - - *‘note:REGEX’* -Match transaction notes (the part of the description right of ‘|’, or -the whole description if there’s no ‘|’). - - *‘payee:REGEX’* -Match transaction payee/payer names (the part of the description left of -‘|’, or the whole description if there’s no ‘|’). - - *‘real:, real:0’* -Match real or virtual postings respectively. - - *‘status:, status:!, status:*’* -Match unmarked, pending, or cleared transactions respectively. - - *‘type:TYPECODES’* -Match by account type (see Declaring accounts > Account types). -‘TYPECODES’ is one or more of the single-letter account type codes -‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match -their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain -kinds of account alias can disrupt account types, see Rewriting accounts -> Aliases and account types. - - *‘tag:REGEX[=REGEX]’* -Match by tag name, and optionally also by tag value. (To match only by -value, use ‘tag:.=REGEX’.) - - When querying by tag, note that: - - • Accounts also inherit the tags of their parent accounts - • Postings also inherit the tags of their account and their - transaction - • Transactions also acquire the tags of their postings. - - (*‘inacct:ACCTNAME’* -A special query term used automatically in hledger-web only: tells -hledger-web to show the transaction register for an account.) - - -File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries - -17.2 Combining query terms -========================== - -When given multiple query terms, most commands select things which -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 is a little different, showing 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. - - Although these fixed rules are enough for many needs, we do not -support full boolean expressions (#203), (and you should not write AND -or OR in your queries). This makes certain queries hard to express, but -here are some tricks that can help: - - 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses - paid with cash: - - $ hledger print food not:not:cash - - 2. Or pre-filter the transactions with ‘print’, piping the result into - a second hledger command (with balance assertions disabled): - - $ hledger print cash | hledger -f- -I balance food - - -File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries - -17.3 Queries and command options -================================ - -Some queries can also be expressed as command-line options: ‘depth:2’ is -equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc. -When you mix command options and query arguments, generally the -resulting query is their intersection. - - -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries - -17.4 Queries and valuation -========================== - -When amounts are converted to other commodities in cost or value -reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old -amount quantity, not the new ones (except in hledger 1.22.0 where it’s -reversed, see #1625). - - -File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries - -17.5 Querying with account aliases -================================== - -When account names are rewritten with ‘--alias’ or ‘alias’, note that -‘acct:’ will match either the old or the new account name. - - -File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries - -17.6 Querying with cost or value -================================ - -When amounts are converted to other commodities in cost or value -reports, note that ‘cur:’ matches the new commodity symbol, and not the -old one, and ‘amt:’ matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, see -the discussion at #1625. - - -File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top - -18 Pivoting -*********** - -Normally, hledger groups and sums amounts within each account. The -‘--pivot FIELD’ option substitutes some other transaction field for -account names, causing amounts to be grouped and summed by that field’s -value instead. FIELD can be any of the transaction fields ‘status’, -‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on -a tag and a posting has multiple values of that tag, only the first -value is displayed. Values containing ‘colon:separated:parts’ will be -displayed hierarchically, like account names. - - Some examples: - -2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues --------------------- - 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): - -$ 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: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top - -19 Generating data -****************** - -Two features for generating transient data (visible only at report time) -are built in to hledger’s journal format: - - • Auto posting rules can generate extra postings on certain - transactions. They are activated by the ‘--auto’ flag. - - • Periodic transaction rules can generate repeating transactions, - usually dated in the future, to help with forecasting or budgeting. - They are activated by the ‘--forecast’ or ‘balance --budget’ - options, described next. - - -File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top - -20 Forecasting -************** - -The ‘--forecast’ flag activates any periodic transaction rules in the -journal. These will generate temporary additional transactions, usually -recurring and in the future, which will appear in all reports. ‘hledger -print --forecast’ is a good way to see them. - - This can be useful for estimating balances into the future, perhaps -experimenting with different scenarios. - - It could also be useful for scripted data entry: you could describe -recurring transactions, and every so often copy the output of ‘print ---forecast’ into the journal. - - The generated transactions will have an extra tag, like -‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule -generated them. There is also a similar, hidden tag, named -‘_generated-transaction:’, which you can use to reliably match -transactions generated "just now" (rather than ‘print’ed in the past). - - The forecast transactions are generated within a _forecast period_, -which is independent of the report period. (Forecast period sets the -bounds for generated transactions, report period controls which -transactions are reported.) The forecast period begins on: - - • the start date provided within ‘--forecast’’s argument, if any - • otherwise, the later of - • the report start date, if specified (with ‘-b’/‘-p’/‘date:’) - • the day after the latest ordinary transaction in the journal, - if any - - • otherwise today. - - It ends on: - - • the end date provided within ‘--forecast’’s argument, if any - • otherwise, the report end date, if specified (with - ‘-e’/‘-p’/‘date:’) - • otherwise 180 days (6 months) from today. - - Note, this means that ordinary transactions will suppress periodic -transactions, by default; the periodic transactions will not start until -after the last ordinary transaction. This is usually convenient, but -you can get around it in two ways: - - • If you need to record some transactions in the future, make them - periodic transactions (with a single occurrence, eg: ‘~ - YYYY-MM-DD’) rather than ordinary transactions. That way they - won’t suppress other periodic transactions. - - • Or give ‘--forecast’ a period expression argument. A forecast - period specified this way can overlap ordinary transactions, and - need not be in the future. Some things to note: - - • You must use ‘=’ between flag and argument; a space won’t - work. - • The period expression can specify the forecast period’s start - date, end date, or both. See also Report start & end date. - • The period expression should not specify a report interval. - (Each periodic transaction rule specifies its own interval.) - - Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’, -‘--forecast=2021’. - - -File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top - -21 Budgeting -************ - -With the balance command’s ‘--budget’ report, each periodic transaction -rule generates recurring budget goals in specified accounts, and goals -and actual performance can be compared. See the balance command’s doc -below. - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top - -22 Cost reporting -***************** - -This section is about recording the cost of things, in transactions -where one commodity is exchanged for another. Eg an exchange of -currency, or a stock purchase or sale. First, a quick glossary: - - • Conversion - an exchange of one currency or commodity for another. - Eg a foreign currency exchange, or a purchase or sale of stock or - cryptocurrency. - - • Conversion transaction - a transaction involving one or more - conversions. - - • Conversion rate - the cost per unit of one commodity in the other, - ie the exchange rate. - - • Cost - how much of one commodity was paid to acquire the other. - And more generally, in hledger docs: the amount exchanged in the - "secondary" commodity (usually your base currency), whether in a - purchase or a sale, and whether expressed per unit or in total. - Also, the "@/@@ PRICE" notation used to represent this. - -* Menu: - -* -B Convert to cost:: -* Equity conversion postings:: -* Inferring equity postings from cost:: -* Inferring cost from equity postings:: -* When to infer cost/equity:: -* How to record conversions:: -* Cost tips:: - - -File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting - -22.1 -B: Convert to cost -======================== - -As discussed in JOURNAL > Costs, when recording a transaction you can -also record the amount’s cost in another commodity, by adding ‘@ -UNITPRICE’ or ‘@@ TOTALPRICE’. - - Then you can see a report with amounts converted to cost, by adding -the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger). -Eg: - -2022-01-01 - assets:dollars $-135 ; 135 dollars is exchanged for.. - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - -$ hledger bal -N - $-135 assets:dollars - €100 assets:euros -$ hledger bal -N -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Notes: - - -B is sensitive to the order of postings when a cost 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: - -2022-01-01 - assets:dollars $-135 ; 135 dollars sold - assets:euros €100 ; for 100 euros - -$ hledger bal -N -B - €-100 assets:dollars # <- the dollars' selling price - €100 assets:euros - - The @/@@ cost notation is convenient, but has some drawbacks: it does -not truly balance the transaction, so it disrupts the accounting -equation and tends to causes a non-zero total in balance reports. - - -File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting - -22.2 Equity conversion postings -=============================== - -By contrast, conventional double entry bookkeeping (DEB) uses a -different notation: an extra pair of equity postings to balance -conversion transactions. In this style, the above entry might be -written: - -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 - - This style is more correct, but it’s also more verbose and makes cost -reporting more difficult for PTA tools. - - Happily, current hledger can read either notation, or convert one to -the other when needed, so you can use the one you prefer. - - You can even use cost notation and equivalent conversion postings at -the same time, for clarity. hledger will ignore the redundancy. But be -sure the cost and conversion posting amounts match, or you’ll see a -not-so-clear transaction balancing error message. - - -File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting - -22.3 Inferring equity postings from cost -======================================== - -With ‘--infer-equity’, hledger detects transactions written with PTA -cost notation and adds equity conversion postings to them: - -2022-01-01 - assets:dollars -$135 - assets:euros €100 @ $1.35 - -$ hledger print --infer-equity -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 - equity:conversion:$-€:€ €-100 ; generated-posting: - equity:conversion:$-€:$ $135.00 ; generated-posting: - - The conversion account names can be changed with the conversion -account type declaration. - - –infer-equity is useful when when transactions have been recorded -using cost notation, to help preserve the accounting equation and -balance reports’ zero total, or to produce more conventional journal -entries for sharing with non-PTA-users. - - -File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting - -22.4 Inferring cost from equity postings -======================================== - -The reverse operation is possible using ‘--infer-costs’, which detects -transactions written with equity conversion postings and adds cost -notation to them: - -2022-01-01 - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 - -$ hledger print --infer-costs -2022-01-01 - assets:dollars $-135 @@ €100 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 - - –infer-costs is useful when combined with -B/–cost, allowing cost -reporting even when transactions have been recorded using equity -postings: - -$ hledger print --infer-costs -B -2009-01-01 - assets:dollars €-100 - assets:euros €100 - - Notes: - - For ‘--infer-costs’ to work, an exchange must consist of four -postings: - - 1. two non-equity postings - 2. two equity postings, next to one another - 3. the equity accounts must be declared, with account type - ‘V’/‘Conversion’ (or if they are not declared, they must be named - ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or - subaccounts of these) - 4. the equity postings’ amounts must exactly match the non-equity - postings’ amounts. - - Multiple such exchanges can coexist within a single transaction. - - When inferring cost, the order of postings matters: the cost is added -to the first of the non-equity postings involved in the exchange, in the -commodity of the last non-equity posting involved in the exchange. If -you don’t want to write your postings in the required order, you can use -explicit cost notation instead. - - –infer-equity and –infer-costs can be used together, if you have a -mixture of both notations in your journal. - - -File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting - -22.5 When to infer cost/equity -============================== - -Inferring equity postings or costs is still fairly new, so not enabled -by default. We’re not sure yet if that should change. Here are two -suggestions to try, experience reports welcome: - - 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal - -B --infer-costs’ - - 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger - --infer-equity --infer-costs"’ - - -File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting - -22.6 How to record conversions -============================== - -Essentially there are four ways to record a conversion transaction in -hledger. Here are all of them, with pros and cons. - -* Menu: - -* Conversion with implicit cost:: -* Conversion with explicit cost:: -* Conversion with equity postings:: -* Conversion with equity postings and explicit cost:: - - -File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions - -22.6.1 Conversion with implicit cost ------------------------------------- - -Let’s assume 100 EUR is converted to 120 USD. You can just record the -outflow (100 EUR) and inflow (120 USD) in the appropriate asset account: - -2021-01-01 - assets:cash -100 EUR - assets:cash 120 USD - - hledger will assume this transaction is balanced, inferring that the -conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate -by using ‘hledger print -x’. - - Pro: - - • Concise, easy - - Con: - - • Less error checking - typos in amounts or commodity symbols may not - be detected - • Conversion rate is not clear - • Disturbs the accounting equation, unless you add the –infer-equity - flag - - You can prevent accidental implicit conversions due to a mistyped -commodity symbol, by using ‘hledger check commodities’. - - You can prevent implicit conversions entirely, by using ‘hledger -check balancednoautoconversion’, or ‘-s/--strict’. - - -File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions - -22.6.2 Conversion with explicit cost ------------------------------------- - -You can add the conversion rate using @ notation: - -2021-01-01 - assets:cash -100 EUR @ 1.20 USD - assets:cash 120 USD - - Now hledger will check that 100 * 1.20 = 120, and would report an -error otherwise. - - Pro: - - • Still concise - • Makes the conversion rate clear - • Provides more error checking - - Con: - - • Disturbs the accounting equation, unless you add the –infer-equity - flag - - -File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions - -22.6.3 Conversion with equity postings --------------------------------------- - -In strict double entry bookkeeping, the above transaction is not -balanced in EUR or in USD, since some EUR disappears, and some USD -appears. This violates the accounting equation (A+L+E=0), and prevents -reports like ‘balancesheetequity’ from showing a zero total. - - The proper way to make it balance is to add a balancing posting for -each commodity, using an equity account: - -2021-01-01 - assets:cash -100 EUR - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - Pro: - - • Preserves the accounting equation - • Keeps track of conversions and related gains/losses in one place - • Standard, works in any double entry accounting system - - Con: - - • More verbose - • Conversion rate is not obvious - • Cost reporting requires adding the –infer-costs flag - - -File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions - -22.6.4 Conversion with equity postings and explicit cost --------------------------------------------------------- - -Here both equity postings and @ notation are used together. - -2021-01-01 - assets:cash -100 EUR @ 1.20 USD - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - Pro: - - • Preserves the accounting equation - • Keeps track of conversions and related gains/losses in one place - • Makes the conversion rate clear - • Provides more error checking - - Con: - - • Most verbose - • Not compatible with ledger - - -File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting - -22.7 Cost tips -============== - - • Recording the cost/conversion rate explicitly is good because it - makes that clear and helps detect errors. - • Recording equity postings is good because it is correct bookkeeping - and preserves the accounting equation. - • Combining these is possible. - • When you want to see the cost (or sale proceeds) of things, use - ‘-B’ (short form of ‘--cost’). - • If you use conversion postings without cost notation, add - ‘--infer-costs’ also. - • If you use cost notation without conversion postings, and you want - to see a balanced balance sheet or print correct journal entries, - use ‘--infer-equity’. - • Conversion to cost is performed before valuation (described next). - - -File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top - -23 Valuation -************ - -Instead of reporting amounts in their original commodity, hledger can -convert them to cost/sale amount (using the conversion rate recorded in -the transaction), and/or to market value (using some market price on a -certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’ -option, which will be described below. We also provide the simpler ‘-V’ -and ‘-X COMMODITY’ options, and often one of these is all you need: - -* Menu: - -* -V Value:: -* -X Value in specified commodity:: -* Valuation date:: -* Finding market price:: -* --infer-market-prices market prices from transactions:: -* Valuation commodity:: -* Simple valuation examples:: -* --value Flexible valuation:: -* More valuation examples:: -* Interaction of valuation and queries:: -* Effect of valuation on reports:: - - -File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation - -23.1 -V: Value -============== - -The ‘-V/--market’ flag converts amounts to market value in their default -_valuation commodity_, using the market prices in effect on the -_valuation date(s)_, if any. More on these in a minute. - - -File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation - -23.2 -X: Value in specified commodity -===================================== - -The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which -currency you want to convert to, and it tries to convert everything to -that. - - -File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation - -23.3 Valuation date -=================== - -Since market prices can change from day to day, market value reports -have a valuation date (or more than one), which determines which market -prices will be used. - - For single period reports, if an explicit report end date is -specified, that will be used as the valuation date; otherwise the -valuation date is the journal’s end date. - - For multiperiod reports, each column/period is valued on the last day -of the period, by default. - - -File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation - -23.4 Finding market price -========================= - -To convert a commodity A to its market value in another commodity B, -hledger looks for a suitable market price (exchange rate) as follows, in -this order of preference : - - 1. A _declared market price_ or _inferred market price_: A’s latest - market price in B on or before the valuation date as declared by a - P directive, or (with the ‘--infer-market-prices’ flag) inferred - from costs. - - 2. A _reverse market price_: the inverse of a declared or inferred - market price from B to A. - - 3. A _forward chain of market prices_: a synthetic price formed by - combining the shortest chain of "forward" (only 1 above) market - prices, leading from A to B. - - 4. _Any chain of market prices_: a chain of any market prices, - including both forward and reverse prices (1 and 2 above), leading - from A to B. - - There is a limit to the length of these price chains; if hledger -reaches that length without finding a complete chain or exhausting all -possibilities, it will give up (with a "gave up" message visible in -‘--debug=2’ output). That limit is currently 1000. - - Amounts for which no suitable market price can be found, are not -converted. - - -File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation - -23.5 –infer-market-prices: market prices from transactions -========================================================== - -Normally, market value in hledger is fully controlled by, and requires, -P directives in your journal. Since adding and updating those can be a -chore, and since transactions usually take place at close to market -value, why not use the recorded costs as additional market prices (as -Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or -‘--value’ enables this. - - So for example, ‘hledger bs -V --infer-market-prices’ will get market -prices both from P directives and from transactions. If both occur on -the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in -confusing/undesired ways by your journal entries. If this happens to -you, read all of this Valuation section carefully, and try adding -‘--debug’ or ‘--debug=2’ to troubleshoot. - - ‘--infer-market-prices’ can infer market prices from: - - • multicommodity transactions with explicit prices (‘@’/‘@@’) - - • multicommodity transactions with implicit prices (no ‘@’, two - commodities, unbalanced). (With these, the order of postings - matters. ‘hledger print -x’ can be useful for troubleshooting.) - - • multicommodity transactions with equity postings, if cost is - inferred with ‘--infer-costs’. - - There is a limitation (bug) currently: when a valuation commodity is -not specified, prices inferred with ‘--infer-market-prices’ do not help -select a default valuation commodity, as ‘P’ prices would. So -conversion might not happen because no valuation commodity was detected -(‘--debug=2’ will show this). To be safe, specify the valuation -commmodity, eg: - - • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’ - • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then - --infer-market-prices’ - - Signed costs and market prices can be confusing. For reference, here -is the current behaviour, since hledger 1.25. (If you think it should -work differently, see #1870.) - -2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - -2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - -2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - -2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - -2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - -2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each -day, the two transactions are considered equivalent). Here are the -market prices inferred for B: - -$ hledger -f- --infer-market-prices prices -P 2022-01-01 B A 1 -P 2022-01-01 B A 1.0 -P 2022-01-02 B A -1 -P 2022-01-02 B A -1.0 -P 2022-01-03 B A -1 -P 2022-01-03 B A -1.0 - - -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation - -23.6 Valuation commodity -======================== - -*When you specify a valuation commodity (‘-X COMM’ or ‘--value -TYPE,COMM’):* -hledger will convert all amounts to COMM, wherever it can find a -suitable market price (including by reversing or chaining prices). - - *When you leave the valuation commodity unspecified (‘-V’ or ‘--value -TYPE’):* -For each commodity A, hledger picks a default valuation commodity as -follows, in this order of preference: - - 1. The price commodity from the latest P-declared market price for A - on or before valuation date. - - 2. The price commodity from the latest P-declared market price for A - on any date. (Allows conversion to proceed when there are inferred - prices before the valuation date.) - - 3. If there are no P directives at all (any commodity or date) and the - ‘--infer-market-prices’ flag is used: the price commodity from the - latest transaction-inferred price for A on or before valuation - date. - - This means: - - • If you have P directives, they determine which commodities ‘-V’ - will convert, and to what. - - • If you have no P directives, and use the ‘--infer-market-prices’ - flag, costs determine it. - - Amounts for which no valuation commodity can be found are not -converted. - - -File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation - -23.7 Simple valuation examples -============================== - -Here are some quick examples of ‘-V’: - -; 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 - - -File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation - -23.8 –value: Flexible valuation -=============================== - -‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option: - - --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. - COMM is an optional commodity symbol. - Shows amounts converted to: - - default valuation commodity (or COMM) using market prices at posting dates - - default valuation commodity (or COMM) using market prices at period end(s) - - default valuation commodity (or COMM) using current market prices - - default valuation commodity (or COMM) using market prices at some date - - The TYPE part selects cost or value and valuation date: - -‘--value=then’ - - Convert amounts to their value in the default valuation commodity, - using market prices on each posting’s date. -‘--value=end’ - - Convert amounts to their value in the default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal’s end date); or in multiperiod reports, - market prices on the last day of each subperiod. -‘--value=now’ - - Convert amounts to their value in the default valuation commodity - using current market prices (as of when report is generated). -‘--value=YYYY-MM-DD’ - - Convert amounts to their value in the default valuation commodity - using market prices on this date. - - To select a different valuation commodity, add the optional ‘,COMM’ -part: a comma, then the target commodity’s symbol. Eg: -*‘--value=now,EUR’*. hledger will do its best to convert amounts to -this commodity, deducing market prices as described above. - - -File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation - -23.9 More valuation examples -============================ - -Here are some examples showing the effect of ‘--value’, as seen with -‘print’: - -P 2000-01-01 A 1 B -P 2000-02-01 A 2 B -P 2000-03-01 A 3 B -P 2000-04-01 A 4 B - -2000-01-01 - (a) 1 A @ 5 B - -2000-02-01 - (a) 1 A @ 6 B - -2000-03-01 - (a) 1 A @ 7 B - - Show the cost of each posting: - -$ hledger -f- print --cost -2000-01-01 - (a) 5 B - -2000-02-01 - (a) 6 B - -2000-03-01 - (a) 7 B - - Show the value as of the last day of the report period (2000-02-29): - -$ hledger -f- print --value=end date:2000/01-2000/03 -2000-01-01 - (a) 2 B - -2000-02-01 - (a) 2 B - - With no report period specified, that shows the value as of the last -day of the journal (2000-03-01): - -$ hledger -f- print --value=end -2000-01-01 - (a) 3 B - -2000-02-01 - (a) 3 B - -2000-03-01 - (a) 3 B - - Show the current value (the 2000-04-01 price is still in effect -today): - -$ hledger -f- print --value=now -2000-01-01 - (a) 4 B - -2000-02-01 - (a) 4 B - -2000-03-01 - (a) 4 B - - Show the value on 2000/01/15: - -$ hledger -f- print --value=2000-01-15 -2000-01-01 - (a) 1 B - -2000-02-01 - (a) 1 B - -2000-03-01 - (a) 1 B - - You may need to explicitly set a commodity’s display style, when -reverse prices are used. Eg this output might be surprising: - -P 2000-01-01 A 2B - -2000-01-01 - a 1B - b - -$ hledger print -x -X A -2000-01-01 - a 0 - b 0 - - Explanation: because there’s no amount or commodity directive -specifying a display style for A, 0.5A gets the default style, which -shows no decimal digits. Because the displayed amount looks like zero, -the commodity symbol and minus sign are not displayed either. Adding a -commodity directive sets a more useful display style for A: - -P 2000-01-01 A 2B -commodity 0.00A - -2000-01-01 - a 1B - b - -$ hledger print -X A -2000-01-01 - a 0.50A - b -0.50A - - -File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation - -23.10 Interaction of valuation and queries -========================================== - -When matching postings based on queries in the presence of valuation, -the following happens. - - 1. The query is separated into two parts: - 1. the currency (‘cur:’) or amount (‘amt:’). - 2. all other parts. - - 2. The postings are matched to the currency and amount queries based - on pre-valued amounts. - 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on - post-valued amounts. - - See: 1625 - - -File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation - -23.11 Effect of valuation on reports -==================================== - -Here is a reference for how valuation is supposed to affect each part of -hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll -sideways.) It may be useful when troubleshooting. If you find -problems, please report them, ideally with a reproducible example. -Related: #329, #1083. - -Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’, -type ‘--cost’ ‘--value=now’ ------------------------------------------------------------------------------- -*print* -posting cost value at value at posting value at value -amounts report end date report or at - or today journal DATE/today - end -balance unchanged unchanged unchanged unchanged unchanged -assertions/assignments -*register* -starting cost value at valued at day value at value -balance report or each historical report or at -(-H) journal posting was made journal DATE/today - end end -starting cost value at valued at day value at value -balance day before each historical day before at -(-H) report or posting was made report or DATE/today -with journal journal -report start start -interval -posting cost value at value at posting value at value -amounts report or date report or at - journal journal DATE/today - end end -summary summarised value at sum of postings value at value -posting cost period in interval, period at -amounts ends valued at ends DATE/today -with interval start -report -interval -running sum/average sum/average sum/average of sum/average sum/average -total/averageof of displayed values of of - displayed displayed displayed displayed - values values values values -*balance -(bs, -bse, cf, -is)* -balance sums of value at value at posting value at value -changes costs report end date report or at - or today journal DATE/today - of sums of end of of - postings sums of sums - postings of - postings -budget like like like balance like like -amounts balance balance changes balances balance -(–budget) changes changes changes -grand sum of sum of sum of displayed sum of sum of -total displayed displayed valued displayed displayed - values values values values -*balance -(bs, -bse, cf, -is) with -report -interval* -starting sums of value at sums of values value at sums -balances costs of report of postings report of -(-H) postings start of before report start of postings - before sums of start at sums of before - report all respective all report - start postings posting dates postings start - before before - report report - start start -balance sums of same as sums of values balance value -changes costs of –value=end of postings in change in at -(bal, postings period at each DATE/today -is, bs in period respective period, of -–change, posting dates valued at sums -cf period of -–change) ends postings -end sums of same as sums of values period end value -balances costs of –value=end of postings from balances, at -(bal -H, postings before period valued at DATE/today -is –H, from start to period period of -bs, cf) before end at ends sums - report respective of - start to posting dates postings - period end -budget like like like balance like like -amounts balance balance changes/end balances balance -(–budget) changes/end changes/end balances changes/end - balances balances balances -row sums, sums, sums, averages sums, sums, -totals, averages averages of displayed averages averages -row of of values of of -averages displayed displayed displayed displayed -(-T, -A) values values values values -column sums of sums of sums of sums of sums -totals displayed displayed displayed values displayed of - values values values displayed - values -grand sum, sum, sum, average of sum, sum, -total, average of average of column totals average of average -grand column column column of -average totals totals totals column - totals - - ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with -a zero starting balance. - - *Glossary:* - -_cost_ - - calculated using price(s) recorded in the transaction(s). -_value_ - - market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. -_report start_ - - the first day of the report period specified with -b or -p or - date:, otherwise today. -_report or journal start_ - - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. -_report end_ - - the last day of the report period specified with -e or -p or date:, - otherwise today. -_report or journal end_ - - the last day of the report period specified with -e or -p or date:, - otherwise the latest transaction date in the journal, otherwise - today. -_report interval_ - - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report’s multi-period mode (whether showing one or many - subperiods). - - -File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top - -24 PART 4: COMMANDS -******************* - -* Menu: - -* Commands overview:: -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* register:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: - - -File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS - -24.1 Commands overview -====================== - -Here are the built-in commands: - -* Menu: - -* DATA ENTRY:: -* DATA CREATION:: -* DATA MANAGEMENT:: -* REPORTS FINANCIAL:: -* REPORTS VERSATILE:: -* REPORTS BASIC:: -* HELP:: -* ADD-ONS:: - - -File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview - -24.1.1 DATA ENTRY ------------------ - -These data entry commands are the only ones which can modify your -journal file. - - • add - add transactions using terminal prompts - • import - add new transactions from other files, eg CSV files - - -File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview - -24.1.2 DATA CREATION --------------------- - - • close - generate balance-zeroing/restoring transactions - • rewrite - generate auto postings, like print –auto - - -File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview - -24.1.3 DATA MANAGEMENT ----------------------- - - • check - check for various kinds of error in the data - • diff - compare account transactions in two journal files - - -File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview - -24.1.4 REPORTS, FINANCIAL -------------------------- - - • aregister (areg) - show transactions in a particular account - • 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 - - -File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview - -24.1.5 REPORTS, VERSATILE -------------------------- - - • balance (bal) - show balance changes, end balances, budgets, - gains.. - • print - show transactions or export journal data - • register (reg) - show postings in one or more accounts & running - total - • roi - show return on investments - - -File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview - -24.1.6 REPORTS, BASIC ---------------------- - - • accounts - show account names - • activity - show bar charts of posting counts per period - • codes - show transaction codes - • commodities - show commodity/currency symbols - • descriptions - show transaction descriptions - • files - show input file paths - • notes - show note parts of transaction descriptions - • payees - show payee parts of transaction descriptions - • prices - show market prices - • stats - show journal statistics - • tags - show tag names - • test - run self tests - - -File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview - -24.1.7 HELP ------------ - - • help - show the hledger manual with info/man/pager - - -File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview - -24.1.8 ADD-ONS --------------- - -And here are some typical add-on commands. Some of these are installed -by the hledger-install script. If installed, they will appear in -hledger’s commands list: - - • ui - run hledger’s terminal UI - • web - run hledger’s web UI - • iadd - add transactions using a TUI (currently hard to build) - • interest - generate interest transactions - • stockquotes - download market prices from AlphaVantage - • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, - pijul, plot, and more.. - - Next, each command is described in detail, in alphabetical order. - - -File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS - -24.2 accounts -============= - -Show account names. - - This command lists account names. By default it shows all known -accounts, either used in transactions or declared with account -directives. - - With query arguments, only matched account names and account names -referenced by matched postings are shown. - - Or it can show just the used accounts (‘--used’/‘-u’), the declared -accounts (‘--declared’/‘-d’), the accounts declared but not used -(‘--unused’), the accounts used but not declared (‘--undeclared’), or -the first account matched by an account name pattern, if any (‘--find’). - - 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’. - - With ‘--types’, it also shows each account’s type, if it’s known. -(See Declaring accounts > Account types.) - - With ‘--positions’, it also shows the file and line number of each -account’s declaration, if any, and the account’s overall declaration -order; these may be useful when troubleshooting account display order. - - With ‘--directives’, it adds the ‘account’ keyword, showing valid -account directives which can be pasted into a journal file. This is -useful together with ‘--undeclared’ when updating your account -declarations to satisfy ‘hledger check accounts’. - - The ‘--find’ flag can be used to look up a single account name, in -the same way that the ‘aregister’ command does. It returns the -alphanumerically-first matched account name, or if none can be found, it -fails with a non-zero exit code. - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - -$ hledger accounts --undeclared --directives >> $LEDGER_FILE -$ hledger check accounts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS - -24.3 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: aregister, Prev: activity, Up: PART 4 COMMANDS - -24.4 add -======== - -Prompt for transactions and add them to the journal. Any arguments will -be used as default inputs for the first N prompts. - - 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 main journal file (which should be -in journal format). Existing transactions are not changed. This is one -of the few hledger commands that writes to the journal file (see also -‘import’). - - 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, - payees/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 go one step - backward. - • Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see https://hledger.org/add.html for a detailed tutorial): - -$ 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 go one step backward. -To end a transaction, enter . when prompted. -To quit, enter . at a date prompt or press control-d or control-c. -Date [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]: $ - - On Microsoft Windows, the add command makes sure that no part of the -file path ends with a period, as that would cause problems (#1056). - - -File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS - -24.5 aregister -============== - -(areg) - - Show the transactions and running historical balance of a single -account, with each transaction displayed as one line. - - ‘aregister’ shows the overall transactions affecting a particular -account (and any subaccounts). Each report line represents one -transaction in this account. Transactions before the report start date -are always included in the running balance (‘--historical’ mode is -always on). - - This is a more "real world", bank-like view than the ‘register’ -command (which shows individual postings, possibly from multiple -accounts, not necessarily in historical mode). As a quick rule of -thumb: - use ‘aregister’ for reviewing and reconciling real-world -asset/liability accounts - use ‘register’ for reviewing detailed -revenues/expenses. - - ‘aregister’ requires one argument: the account to report on. You can -write either the full account name, or a case-insensitive regular -expression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can -be surprising; eg if you have ‘assets:per:checking 1’ and -‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select -‘assets:biz:checking 2’. It’s just a convenience to save typing, so if -in doubt, write the full account name, or a distinctive substring that -matches uniquely. - - Transactions involving subaccounts of this account will also be -shown. ‘aregister’ ignores depth limits, so its final total will always -match a balance report with similar arguments. - - Any additional arguments form a query which will filter the -transactions shown. Note some queries will disturb the running balance, -causing it to be different from the account’s real-world running -balance. - - An example: this shows the transactions and historical running -balance during july, in the first account whose name contains -"checking": - -$ hledger areg checking date:jul - - Each ‘aregister’ line item shows: - - • the transaction’s date (or the relevant posting’s date if - different, see below) - • the names of all the other account(s) involved in this transaction - (probably abbreviated) - • the total change to this account’s balance from this transaction - • the account’s historical running balance after this transaction. - - Transactions making a net change of zero are not shown by default; -add the ‘-E/--empty’ flag to show them. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -‘--align-all’ flag. - - This command also supports the output destination and output format -options. The output formats supported are ‘txt’, ‘csv’, and ‘json’. - -* Menu: - -* aregister and custom posting dates:: - - -File: hledger.info, Node: aregister and custom posting dates, Up: aregister - -24.5.1 aregister and custom posting dates ------------------------------------------ - -Transactions whose date is outside the report period can still be shown, -if they have a posting to this account dated inside the report period. -(And in this case it’s the posting date that is shown.) This ensures -that ‘aregister’ can show an accurate historical running balance, -matching the one shown by ‘register -H’ with the same arguments. - - To filter strictly by transaction date instead, add the ‘--txn-dates’ -flag. If you use this flag and some of your postings have custom dates, -it’s probably best to assume the running balance is wrong. - - -File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS - -24.6 balance -============ - -(bal) - - Show accounts and their balances. - - ‘balance’ is one of hledger’s oldest and most versatile commands, for -listing account balances, balance changes, values, value changes and -more, during one time period or many. Generally it shows a table, with -rows representing accounts, and columns representing periods. - - Note there are some higher-level variants of the ‘balance’ command -with convenient defaults, which can be simpler to use: ‘balancesheet’, -‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need -more control, then use ‘balance’. - -* Menu: - -* balance features:: -* Simple balance report:: -* Balance report line format:: -* Filtered balance report:: -* List or tree mode:: -* Depth limiting:: -* Dropping top-level accounts:: -* Showing declared accounts:: -* Sorting by amount:: -* Percentages:: -* Multi-period balance report:: -* Balance change end balance:: -* Balance report types:: -* Budget report:: -* Data layout:: -* Useful balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -24.6.1 balance features ------------------------ - -Here’s a quick overview of the ‘balance’ command’s features, followed by -more detailed descriptions and examples. Many of these work with the -higher-level commands as well. - - ‘balance’ can show.. - - • accounts as a list (‘-l’) or a tree (‘-t’) - • optionally depth-limited (‘-[1-9]’) - • sorted by declaration order and name, or by amount - - ..and their.. - - • balance changes (the default) - • or actual and planned balance changes (‘--budget’) - • or value of balance changes (‘-V’) - • or change of balance values (‘--valuechange’) - • or unrealised capital gain/loss (‘--gain’) - - ..in.. - - • one time period (the whole journal period by default) - • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’) - - ..either.. - - • per period (the default) - • or accumulated since report start date (‘--cumulative’) - • or accumulated since account creation (‘--historical/-H’) - - ..possibly converted to.. - - • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’) - • or market value, as of transaction dates (‘--value=then[,COMM]’) - • or at period ends (‘--value=end[,COMM]’) - • or now (‘--value=now’) - • or at some other date (‘--value=YYYY-MM-DD’) - - ..with.. - - • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign - (‘--invert’) - • rows and columns swapped (‘--transpose’) - • another field used as account name (‘--pivot’) - • custom-formatted line items (single-period reports only) - (‘--format’) - • commodities displayed on the same line or multiple lines - (‘--layout’) - - This command supports the output destination and output format -options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period -reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal, -negative amounts are shown in red. - - The ‘--related’/‘-r’ flag shows the balance of the _other_ postings -in the transactions of the postings which would normally be shown. - - -File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance - -24.6.2 Simple balance report ----------------------------- - -With no arguments, ‘balance’ shows a list of all accounts and their -change of balance - ie, the sum of posting amounts, both inflows and -outflows - during the entire period of the journal. ("Simple" here -means just one column of numbers, covering a single period. You can -also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end -balance at the end of the journal period; more on this below. - - Accounts are sorted by declaration order if any, and then -alphabetically by account name. For instance (using -examples/sample.journal): - -$ hledger -f examples/sample.journal bal - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - Accounts with a zero balance (and no non-zero subaccounts, in tree -mode - see below) are hidden by default. Use ‘-E/--empty’ to show them -(revealing ‘assets:bank:checking’ here): - -$ hledger -f examples/sample.journal bal -E - 0 assets:bank:checking - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - The total of the amounts displayed is shown as the last line, unless -‘-N’/‘--no-total’ is used. - - -File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance - -24.6.3 Balance report line format ---------------------------------- - -For single-period balance reports displayed in the terminal (only), you -can use ‘--format FMT’ to customise the format and content of each line. -Eg: - -$ hledger -f examples/sample.journal 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 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: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance - -24.6.4 Filtered balance report ------------------------------- - -You can show fewer accounts, a different time period, totals from -cleared transactions only, etc. by using query arguments or options to -limit the postings being matched. Eg: - -$ hledger -f examples/sample.journal bal --cleared assets date:200806 - $-2 assets:cash --------------------- - $-2 - - -File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance - -24.6.5 List or tree mode ------------------------- - -By default, or with ‘-l/--flat’, accounts are shown as a flat list with -their full names visible, as in the examples above. - - With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’ -"leaf" names indented below their parent: - -$ hledger -f examples/sample.journal balance - $-1 assets - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts --------------------- - 0 - - Notes: - - • "Boring" accounts are combined with their subaccount for more - compact output, unless ‘--no-elide’ is used. Boring accounts have - no balance of their own and just one subaccount (eg ‘assets:bank’ - and ‘liabilities’ above). - - • All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, - which requires explanation when sharing reports with - non-plaintextaccounting-users. A tree mode report’s final total is - the sum of the top-level balances shown, not of all the balances - shown. - - • Each group of sibling accounts (ie, under a common parent) is - sorted separately. - - -File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance - -24.6.6 Depth limiting ---------------------- - -With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg: -‘-3’) balance reports will show accounts only to the specified depth, -hiding the deeper subaccounts. This can be useful for getting an -overview without too much detail. - - Account balances at the depth limit always include the balances from -any deeper subaccounts (even in list mode). Eg, limiting to depth 1: - -$ hledger -f examples/sample.journal balance -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities --------------------- - 0 - - -File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance - -24.6.7 Dropping top-level accounts ----------------------------------- - -You can also hide one or more top-level account name parts, using -‘--drop NUM’. This can be useful for hiding repetitive top-level -account names: - -$ hledger -f examples/sample.journal bal expenses --drop 1 - $1 food - $1 supplies --------------------- - $2 - - -File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance - -24.6.8 Showing declared accounts --------------------------------- - -With ‘--declared’, accounts which have been declared with an account -directive will be included in the balance report, even if they have no -transactions. (Since they will have a zero balance, you will also need -‘-E/--empty’ to see them.) - - More precisely, _leaf_ declared accounts (with no subaccounts) will -be included, since those are usually the more useful in reports. - - The idea of this is to be able to see a useful "complete" balance -report, even when you don’t have transactions in all of your declared -accounts yet. - - -File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance - -24.6.9 Sorting by amount ------------------------- - -With ‘-S/--sort-amount’, accounts with the largest (most positive) -balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your -biggest averaged monthly expenses first. When more than one commodity -is present, they will be sorted by the alphabetically earliest commodity -first, and then by subsequent commodities (if an amount is missing a -commodity, it is treated as 0). - - Revenues and liability balances are typically negative, however, so -‘-S’ shows these in reverse order. To work around this, you can add -‘--invert’ to flip the signs. (Or, use one of the higher-level reports, -which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’). - - -File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance - -24.6.10 Percentages -------------------- - -With ‘-%/--percent’, balance reports show each account’s value expressed -as a percentage of the (column) total. - - Note it is not useful to calculate percentages if the amounts in a -column have mixed signs. In this case, make a separate report for each -sign, eg: - -$ hledger bal -% amt:`>0` -$ hledger bal -% amt:`<0` - - Similarly, if the amounts in a column have mixed commodities, convert -them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a -separate report for each commodity: - -$ hledger bal -% cur:\\$ -$ hledger bal -% cur:€ - - -File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance - -24.6.11 Multi-period balance report ------------------------------------ - -With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’, -‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag), -‘balance’ shows a tabular report, with columns representing successive -time periods (and a title): - -$ hledger -f examples/sample.journal bal --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 - - Notes: - - • The report’s start/end dates will be expanded, if necessary, to - fully encompass the displayed subperiods (so that the first and - last subperiods have the same duration as the others). - • Leading and trailing periods (columns) containing all zeroes are - not shown, unless ‘-E/--empty’ is used. - • Accounts (rows) containing all zeroes are not shown, unless - ‘-E/--empty’ is used. - • Amounts with many commodities are shown in abbreviated form, unless - ‘--no-elide’ is used. _(experimental)_ - • Average and/or total columns can be added with the ‘-A/--average’ - and ‘-T/--row-total’ flags. - • The ‘--transpose’ flag can be used to exchange rows and columns. - • The ‘--pivot FIELD’ option causes a different transaction field to - be used as "account name". See PIVOTING. - - Multi-period reports with many periods can be too wide for easy -viewing in the terminal. Here are some ways to handle that: - - • Hide the totals row with ‘-N/--no-total’ - • Convert to a single currency with ‘-V’ - • Maximize the terminal window - • Reduce the terminal’s font size - • View with a pager like less, eg: ‘hledger bal -D --color=yes | less - -RS’ - • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D - -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or - a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’) - • Output as HTML and view with a browser: ‘hledger bal -D -o a.html - && open a.html’ - - -File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance - -24.6.12 Balance change, end balance ------------------------------------ - -It’s important to be clear on the meaning of the numbers shown in -balance reports. Here is some terminology we use: - - A *_balance change_* is the net amount added to, or removed from, an -account during some period. - - An *_end balance_* is the amount accumulated in an account as of some -date (and some time, but hledger doesn’t store that; assume end of day -in your timezone). It is the sum of previous balance changes. - - We call it a *_historical end balance_* if it includes all balance -changes since the account was created. For a real world account, this -means it will match the "historical record", eg the balances reported in -your bank statements or bank web UI. (If they are correct!) - - In general, balance changes are what you want to see when reviewing -revenues and expenses, and historical end balances are what you want to -see when reviewing or reconciling asset, liability and equity accounts. - - ‘balance’ shows balance changes by default. To see accurate -historical end balances: - - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the - journal covers the account’s full lifetime. - - 2. Include all of of the account’s prior postings in the report, by - not specifying a report start date, or by using the - ‘-H/--historical’ flag. (‘-H’ causes report start date to be - ignored when summing postings.) - - -File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance - -24.6.13 Balance report types ----------------------------- - -The balance command is quite flexible; here is the full detail on how to -control what it reports. If the following seems complicated, don’t -worry - this is for advanced reporting, and it does typically take some -time and experimentation to get clear on all these report modes. - - There are three important option groups: - - ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] -...’ - -* Menu: - -* Calculation type:: -* Accumulation type:: -* Valuation type:: -* Combining balance report types:: - - -File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types - -24.6.13.1 Calculation type -.......................... - -The basic calculation to perform for each table cell. It is one of: - - • ‘--sum’ : sum the posting amounts (*default*) - • ‘--budget’ : sum the amounts, but also show the budget goal amount - (for each account/period) - • ‘--valuechange’ : show the change in period-end historical balance - values (caused by deposits, withdrawals, and/or market price - fluctuations) - • ‘--gain’ : show the unrealised capital gain/loss, (the current - valued balance minus each amount’s original cost) - - -File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types - -24.6.13.2 Accumulation type -........................... - -How amounts should accumulate across report periods. Another way to say -it: which time period’s postings should contribute to each cell’s -calculation. It is one of: - - • ‘--change’ : calculate with postings from column start to column - end, ie "just this column". Typically used to see - revenues/expenses. (*default for balance, incomestatement*) - - • ‘--cumulative’ : calculate with postings from report start to - column end, ie "previous columns plus this column". Typically used - to show changes accumulated since the report’s start date. Not - often used. - - • ‘--historical/-H’ : calculate with postings from journal start to - column end, ie "all postings from before report start date until - this column’s end". Typically used to see historical end balances - of assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) - - -File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types - -24.6.13.3 Valuation type -........................ - -Which kind of value or cost conversion should be applied, if any, before -displaying the report. It is one of: - - • no valuation type : don’t convert to cost or value (*default*) - • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to - some other commodity) - • ‘--value=then[,COMM]’ : convert amounts to market value on - transaction dates - • ‘--value=end[,COMM]’ : convert amounts to market value on period - end date(s) - (*default with ‘--valuechange’, ‘--gain’*) - • ‘--value=now[,COMM]’ : convert amounts to market value on today’s - date - • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on - another date - - or one of the equivalent simpler flags: - - • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are - independent options which can both be used at once) - • ‘-V/--market’ : like –value=end - • ‘-X COMM/--exchange COMM’ : like –value=end,COMM - - See Cost reporting and Valuation for more about these. - - -File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types - -24.6.13.4 Combining balance report types -........................................ - -Most combinations of these options should produce reasonable reports, -but if you find any that seem wrong or misleading, let us know. The -following restrictions are applied: - - • ‘--valuechange’ implies ‘--value=end’ - • ‘--valuechange’ makes ‘--change’ the default when used with the - ‘balancesheet’/‘balancesheetequity’ commands - • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’ - - For reference, here is what the combinations of accumulation and -valuation show: - -Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value= -Accumulation:v YYYY-MM-DD - /now’ ------------------------------------------------------------------------------ -‘--change’change in sum of period-end DATE-value - period posting-date value of of change in - market values change in period - in period period -‘--cumulative’change from sum of period-end DATE-value - report start to posting-date value of of change - period end market values change from from report - from report report start start to - start to period to period end period end - end -‘--historicalchange from sum of period-end DATE-value -/-H’ journal start posting-date value of of change - to period end market values change from from journal - (historical end from journal journal start start to - balance) start to period to period end period end - end - - -File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance - -24.6.14 Budget report ---------------------- - -The ‘--budget’ report type activates extra columns showing any budget -goals for each account and period. The budget goals are defined by -periodic transactions. This is useful for comparing planned and actual -income, expenses, time usage, etc. - - 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] - - This is different from a normal balance report in several ways: - - • Only accounts with budget goals during the report period are shown, - by default. - - • In each column, in square brackets after the actual amount, budget - goal amounts are shown, and the actual/goal percentage. (Note: - budget goals should be in the same commodity as the actual amount.) - - • All parent accounts are always shown, even in list mode. Eg - assets, assets:bank, and expenses above. - - • Amounts always include all subaccounts, budgeted or unbudgeted, - even in list mode. - - This means that the numbers displayed will not always add up! Eg -above, the ‘expenses’ actual amount includes the gifts and supplies -transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts -are not shown, as they have no budget amounts declared. - - This can be confusing. When you need to make things clearer, use the -‘-E/--empty’ flag, which will reveal all accounts including unbudgeted -ones, giving the full picture. Eg: - -$ 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] - - It’s common to limit budgets/budget reports to just expenses - -hledger bal -M --budget expenses - - or just revenues and expenses (eg, using account types): - -hledger bal -M --budget type:rx - - It’s also common to limit or convert them to a single currency -(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple -currencies, ‘--layout bare’ or ‘--layout tall’ can help. - - For more examples and notes, see Budgeting. - -* Menu: - -* Budget report start date:: -* Budgets and subaccounts:: -* Selecting budget goals:: -* Budget vs forecast:: - - -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report - -24.6.14.1 Budget report start date -.................................. - -This might be a bug, but for now: when making budget reports, it’s a -good idea to explicitly set the report’s start date to the first day of -a reporting period, because a periodic rule like ‘~ monthly’ generates -its transactions on the 1st of each month, and if your journal has no -regular transactions on the 1st, the default report start date could -exclude that budget goal, which can be a little surprising. Eg here the -default report period is just the day of 2020-01-15: - -~ monthly in 2020 - (expenses:food) $500 - -2020-01-15 - expenses:food $400 - assets:checking - -$ hledger bal expenses --budget -Budget performance in 2020-01-15: - - || 2020-01-15 -==============++============ - || $400 ---------------++------------ - || $400 - - To avoid this, specify the budget report’s period, or at least the -start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the -budget goal transactions (periodic transactions) that you want. Eg, -adding ‘-b 2020/1/1’ to the above: - -$ hledger bal expenses --budget -b 2020/1/1 -Budget performance in 2020-01-01..2020-01-15: - - || 2020-01-01..2020-01-15 -===============++======================== - expenses:food || $400 [80% of $500] ----------------++------------------------ - || $400 [80% of $500] - - -File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report - -24.6.14.2 Budgets and subaccounts -................................. - -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 implicitly -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] - - -File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report - -24.6.14.3 Selecting budget goals -................................ - -The budget report evaluates periodic transaction rules to generate -special "goal transactions", which generate the goal amounts for each -account in each report subperiod. When troubleshooting, you can use -‘print --forecast’ to show these as forecasted transactions: - -$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated - - By default, the budget report uses all available periodic transaction -rules to generate goals. This includes rules with a different report -interval from your report. Eg if you have daily, weekly and monthly -periodic rules, all of these will contribute to the goals in a monthly -budget report. - - You can select a subset of periodic rules by providing an argument to -the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules -whose description contains DESCPAT, a case-insensitive substring (not a -regular expression or query). This means you can give your periodic -rules descriptions (remember that two spaces are needed), and then -select from multiple budgets defined in your journal. - - -File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report - -24.6.14.4 Budget vs forecast -............................ - -‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate -features, though both of them use the periodic transaction rules defined -in the journal, and both of them generate temporary transactions for -reporting purposes ("forecast transactions" and "budget goal -transactions", respectively). You can use both features at the same -time if you want. Here are some differences between them, as of hledger -1.29: - - CLI: - - • –forecast is a general hledger option, usable with any command - • –budget is a ‘balance’ command option, usable only with that - command. - - Visibility of generated transactions: - - • forecast transactions are visible in any report, like ordinary - transactions - • budget goal transactions are invisible except for the goal amounts - they produce in –budget reports. - - Periodic transaction rules: - - • –forecast uses all available periodic transaction rules - • –budget uses all periodic rules (‘--budget’) or a selected subset - (‘--budget=DESCPAT’) - - Period of generated transactions: - - • –forecast generates forecast transactions - • from after the last regular transaction to the end of the - report period (‘--forecast’) - • or, during a specified period (‘--forecast=PERIODEXPR’) - • possibly further restricted by a period specified in the - periodic transaction rule - • and always restricted within the bounds of the report period - - • –budget generates budget goal transactions - • throughout the report period - • possibly restricted by a period specified in the periodic - transaction rule. - - -File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance - -24.6.15 Data layout -------------------- - -The ‘--layout’ option affects how balance reports show multi-commodity -amounts and commodity symbols, which can improve readability. It can -also normalise the data for easy consumption by other programs. It has -four possible values: - - • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line, - optionally elided to WIDTH - • ‘--layout=tall’: each commodity is shown on a separate line - • ‘--layout=bare’: commodity symbols are in their own column, amounts - are bare numbers - • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form, - with one row per data value - - Here are the ‘--layout’ modes supported by each output format; note -only CSV output supports all of them: - -- txt csv html json sql ---------------------------------------- -wide Y Y Y -tall Y Y Y -bare Y Y Y -tidy Y - - Examples: - - • Wide layout. With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - • Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - • Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - • Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - • Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - • Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here’s how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - -File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance - -24.6.16 Useful balance reports ------------------------------- - -Some frequently used ‘balance’ options/reports are: - - • ‘bal -M revenues expenses’ - Show revenues/expenses in each month. Also available as the - ‘incomestatement’ command. - - • ‘bal -M -H assets liabilities’ - Show historical asset/liability balances at each month end. Also - available as the ‘balancesheet’ command. - - • ‘bal -M -H assets liabilities equity’ - Show historical asset/liability/equity balances at each month end. - Also available as the ‘balancesheetequity’ command. - - • ‘bal -M assets not:receivable’ - Show changes to liquid assets in each month. Also available as the - ‘cashflow’ command. - - Also: - - • ‘bal -M expenses -2 -SA’ - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - • ‘bal -M --budget expenses’ - Show monthly expenses and budget goals. - - • ‘bal -M --valuechange investments’ - Show monthly change in market value of investment assets. - - • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert]’ - Show top gainers [or losers] last week - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS - -24.7 balancesheet -================= - -(bs) - - This command displays a balance sheet, showing historical ending -balances of asset and liability accounts. (To see equity as well, use -the balancesheetequity command.) Amounts are shown with normal positive -sign, as in conventional financial statements. - - This report shows accounts declared with the ‘Asset’, ‘Cash’ or -‘Liability’ type (see account types). Or if no such accounts are -declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case -insensitive, plurals allowed) and their subaccounts. - - Example: - -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance -H assets liabilities’, but with -smarter account detection, and liabilities displayed with their sign -flipped. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS - -24.8 balancesheetequity -======================= - -(bse) - - This command displays a balance sheet, showing historical ending -balances of asset, liability and equity accounts. Amounts are shown -with normal positive sign, as in conventional financial statements. - - This report shows accounts declared with the ‘Asset’, ‘Cash’, -‘Liability’ or ‘Equity’ type (see account types). Or if no such -accounts are declared, it shows top-level accounts named ‘asset’, -‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their -subaccounts. - - 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 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance -H assets liabilities equity’, but -with smarter account detection, and liabilities/equity displayed with -their sign flipped. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS - -24.9 cashflow -============= - -(cf) - - This command displays a cashflow statement, showing the inflows and -outflows affecting "cash" (ie, liquid, easily convertible) assets. -Amounts are shown with normal positive sign, as in conventional -financial statements. - - This report shows accounts declared with the ‘Cash’ type (see account -types). Or if no such accounts are declared, it shows accounts - - • under a top-level account named ‘asset’ (case insensitive, plural - allowed) - • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or - ‘saving’. - - More precisely: all accounts matching this case insensitive regular -expression: - - ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’ - - and their subaccounts. - - An example cashflow report: - -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance assets not:fixed not:investment -not:receivable’, but with smarter account detection. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS - -24.10 check -=========== - -Check for various kinds of errors in your data. - - hledger provides a number of built-in error checks to help prevent -problems in your data. Some of these are run automatically; or, you can -use this ‘check’ command to run them on demand, with no output and a -zero exit code if all is well. Specify their names (or a prefix) as -argument(s). - - Some examples: - -hledger check # basic checks -hledger check -s # basic + strict checks -hledger check ordereddates payees # basic + two other checks - - If you are an Emacs user, you can also configure flycheck-hledger to -run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available: - -* Menu: - -* Basic checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: -* More about specific checks:: - - -File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check - -24.10.1 Basic checks --------------------- - -These checks are always run automatically, by (almost) all hledger -commands, including ‘check’: - - • *parseable* - data files are well-formed and can be successfully - parsed - - • *balancedwithautoconversion* - all transactions are balanced, - inferring missing amounts where necessary, and possibly converting - commodities using costs or automatically-inferred costs - - • *assertions* - all balance assertions in the journal are passing. - (This check can be disabled with ‘-I’/‘--ignore-assertions’.) - - -File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check - -24.10.2 Strict checks ---------------------- - -These additional checks are run when the ‘-s’/‘--strict’ (strict mode) -flag is used. Or, they can be run by giving their names as arguments to -‘check’: - - • *accounts* - all account names used by transactions have been - declared - - • *commodities* - all commodity symbols used have been declared - - • *balancednoautoconversion* - transactions are balanced, possibly - using explicit costs but not inferred ones - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -24.10.3 Other checks --------------------- - -These checks can be run only by giving their names as arguments to -‘check’. They are more specialised and not desirable for everyone, -therefore optional: - - • *ordereddates* - transactions are ordered by date within each file - - • *payees* - all payees used by transactions have been declared - - • *recentassertions* - all accounts with balance assertions have a - balance assertion no more than 7 days before their latest posting - - • *tags* - all tags used by transactions have been declared - - • *uniqueleafnames* - all account leaf names are unique - - -File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check - -24.10.4 Custom checks ---------------------- - -A few more checks are are available as separate add-on commands, in -https://github.com/simonmichael/hledger/tree/master/bin: - - • *hledger-check-tagfiles* - all tag values containing / (a forward - slash) exist as file paths - - • *hledger-check-fancyassertions* - more complex balance assertions - are passing - - You could make similar scripts to perform your own custom checks. -See: Cookbook -> Scripting. - - -File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check - -24.10.5 More about specific checks ----------------------------------- - -‘hledger check recentassertions’ will complain if any balance-asserted -account does not have a balance assertion within 7 days before its -latest posting. This aims to prevent the situation where you are -regularly updating your journal, but forgetting to check your balances -against the real world, then one day must dig back through months of -data to find an error. It assumes that adding a balance assertion -requires/reminds you to check the real-world balance. That may not be -true if you auto-generate balance assertions from bank data; in that -case, I recommend to import transactions uncleared, then use the -manual-review-and-mark-cleared phase as a reminder to check the latest -assertions against real-world balances. - - -File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS - -24.11 close -=========== - -‘close [--retain | --migrate | --open] [QUERY]’ - - By default: prints a transaction that zeroes out ("closes") all -accounts, transferring their balances to an equity account. Query -arguments can be added to override the accounts selection. Three other -modes are supported: - - ‘--retain’: prints a transaction closing revenue and expense -balances. This is traditionally done by businesses at the end of each -accounting period; it is less necessary in personal and computer-based -accounting, but it can help balance the accounting equation A=L+E. - - ‘--migrate’: prints a transaction to close asset, liability and most -equity balances, and another transaction to re-open them. This can be -useful when starting a new file (for performance or data protection). -Adding the closing transaction to the old file allows old and new files -to be combined. - - ‘--open’: as above, but prints just the opening transaction. This -can be useful for starting a new file, leaving the old file unchanged. -Similar to Ledger’s equity command. - - You can change the equity account name with ‘--close-acct ACCT’. It -defaults to ‘equity:retained earnings’ with ‘--retain’, or -‘equity:opening/closing balances’ otherwise. - - You can change the transaction description(s) with ‘--close-desc -'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with -‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise. - - Just one posting to the equity account will be used by default, with -an implicit amount. - - With ‘--x/--explicit’ the amount will be shown explicitly, and if it -involves multiple commodities, a separate posting will be generated for -each commodity. - - With ‘--interleaved’, each equity posting is shown next to the -corresponding source/destination posting. - - The default closing date is yesterday or the journal’s end date, -whichever is later. You can change this by specifying a report end -date; the last day of the report period will be the closing date. Eg -‘-e 2022’ means "close on 2022-12-31". - - The default closing date is yesterday, or the journal’s end date, -whichever is later. You can change this by specifying a report end -date; (The report start date does not matter.) The last day of the -report period will be the closing date; eg ‘-e 2022’ means "close on -2022-12-31". The opening date is always the day after the closing date. - -* Menu: - -* close and costs:: -* close and balance assertions:: -* Example retain earnings:: -* Example migrate balances to a new file:: -* Example excluding closing/opening transactions:: - - -File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close - -24.11.1 close and costs ------------------------ - -With ‘--show-costs’, any amount costs are shown, with separate postings -for each cost. (This currently the best way to view investment assets, -showing lots and cost bases.) If you have many currency conversion or -investment transactions, it can generate very large journal entries. - - -File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close - -24.11.2 close and balance assertions ------------------------------------- - -Balance assertions will be generated, verifying that the accounts have -been reset to zero (and then restored to their previous balances, if -there is an opening transaction). - - These provide useful error checking, but you can ignore them -temporarily with ‘-I’, or remove them if you prefer. - - You probably should avoid filtering transactions by status or -realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’), -with this command, since the balance assertions would depend on these. - - Note custom posting dates spanning the file boundary will disrupt the -balance assertions: - -2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve that you can transfer the money to and from a temporary -account, in effect splitting the multi-day transaction into two -single-day transactions: - -; in 2022.journal: -2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - -; in 2023.journal: -2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - -File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close - -24.11.3 Example: retain earnings --------------------------------- - -Record 2022’s revenues/expenses as retained earnings on 2022-12-31, -appending the generated transaction to the journal: - -$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - Now 2022’s income statement will show only zeroes. To see it again, -exclude the retain transaction. Eg: - -$ hledger -f 2022.journal is not:desc:'retain earnings' - - -File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close - -24.11.4 Example: migrate balances to a new file ------------------------------------------------ - -Close assets/liabilities/equity on 2022-12-31 and re-open them on -2023-01-01: - -$ hledger close --migrate -f 2022.journal -p 2022 -# copy/paste the closing transaction to the end of 2022.journal -# copy/paste the opening transaction to the start of 2023.journal - - Now 2022’s balance sheet will show only zeroes, indicating a balanced -accounting equation. (Unless you are using @/@@ notation - in that -case, try adding –infer-equity.) To see it again, exclude the closing -transaction. Eg: - -$ hledger -f 2022.journal bs not:desc:'closing balances' - - -File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close - -24.11.5 Example: excluding closing/opening transactions -------------------------------------------------------- - -When combining many files for multi-year reports, the closing/opening -transactions cause some noise in reports like ‘print’ and ‘register’. -You can exclude them as shown above, but ‘not:desc:...’ could be -fragile, and also you will need to avoid excluding the very first -opening transaction, which can be awkward. Here is a way to do it, -using tags: add ‘clopen:’ tags to all opening/closing balances -transactions except the first, like this: - -; 2021.journal -2021-06-01 first opening balances -... -2021-12-31 closing balances ; clopen:2022 -... - -; 2022.journal -2022-01-01 opening balances ; clopen:2022 -... -2022-12-31 closing balances ; clopen:2023 -... - -; 2023.journal -2023-01-01 opening balances ; clopen:2023 -... - - Now, assuming a combined journal like: - -; all.journal -include 2021.journal -include 2022.journal -include 2023.journal - - The ‘clopen:’ tag can exclude all but the first opening transaction. -To show a clean multi-year checking register: - -$ hledger -f all.journal areg checking not:tag:clopen - - And the year values allow more precision. To show 2022’s year-end -balance sheet: - -$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 - - -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS - -24.12 codes -=========== - -List the codes seen in transactions, in the order parsed. - - This command prints the value of each transaction’s code field, in -the order transactions were parsed. The transaction code is an optional -value written in parentheses between the date and description, often -used to store a cheque number, order number or similar. - - Transactions aren’t required to have a code, and missing or empty -codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they -will be printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - -2022/1/1 (123) Supermarket - Food $5.00 - Checking - -2022/1/2 (124) Post Office - Postage $8.32 - Checking - -2022/1/3 Supermarket - Food $11.23 - Checking - -2022/1/4 (126) Post Office - Postage $3.21 - Checking - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - -126 - - -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS - -24.13 commodities -================= - -List all commodity/currency symbols used or declared in the journal. - - -File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS - -24.14 descriptions -================== - -List the unique descriptions that appear in transactions. - - This command lists the unique descriptions that appear in -transactions, in alphabetic order. You can add a query to select a -subset of transactions. - - Example: - -$ hledger descriptions -Store Name -Gas Station | Petrol -Person A - - -File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS - -24.15 diff -========== - -Compares a particular account’s transactions in two input files. It -shows any transactions to this account which are in one file but not in -the other. - - More precisely, for each posting affecting this account in either -file, it looks for a corresponding posting in the other file which posts -the same amount to the same account (ignoring date, description, etc.) -Since postings not transactions are compared, this also works when -multiple bank transactions have been combined into a single journal -entry. - - This is useful eg if you have downloaded an account’s transactions -from your bank (eg as CSV data). When hledger and your bank disagree -about the account balance, you can compare the bank data with your -journal to find out the cause. - - Examples: - -$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only: - -2014/01/01 Opening Balances - assets:bank:giro EUR ... - ... - equity:opening balances EUR -... - -These transactions are in the second file only: - - -File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS - -24.16 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: PART 4 COMMANDS - -24.17 help -========== - -Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a -pager. With a TOPIC argument, open it at that topic if possible. TOPIC -can be any heading in the manual, or a heading prefix, case insensitive. -Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto -postings"’. - - This command shows the hledger manual built in to your hledger -version. It can be useful when offline, or when you prefer the terminal -to a web browser, or when the appropriate hledger manual or viewing -tools are not installed on your system. - - By default it chooses the best viewer found in $PATH (preferring info -since the hledger manual is large). You can select a particular viewer -with the ‘-i’, ‘-m’, or ‘-p’ flags. - - Examples - -$ hledger help --help # show how the help command works -$ hledger help # show the hledger manual with info, man or $PAGER -$ hledger help journal # show the journal topic in the hledger manual - - -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS - -24.18 import -============ - -Read new transactions added to each FILE since last run, and add them to -the journal. Or with –dry-run, just print the transactions that would -be added. Or with –catchup, just mark all of the FILEs’ transactions as -imported, without actually importing any. - - This command may append new transactions to the main journal file -(which should be in journal format). Existing transactions are not -changed. This is one of the few hledger commands that writes to the -journal file (see also ‘add’). - - Unlike other hledger commands, with ‘import’ the journal file is an -output file, and will be modified, though only by appending (existing -data will not be changed). The input files are specified as arguments, -so to import one or more CSV files to your main journal, you will run -‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’. - - Note you can import from any file format, though CSV files are the -most common import source, and these docs focus on that case. - -* Menu: - -* Deduplication:: -* Import testing:: -* Importing balance assignments:: -* Commodity display styles:: - - -File: hledger.info, Node: Deduplication, Next: Import testing, Up: import - -24.18.1 Deduplication ---------------------- - -As a convenience ‘import’ does _deduplication_ while reading -transactions. This does not mean "ignore transactions that look the -same", but rather "ignore transactions that have been seen before". -This is intended for when you are periodically importing foreign data -which may contain already-imported transactions. So eg, if every day -you download bank CSV files containing redundant data, you can safely -run ‘hledger import bank.csv’ and only new transactions will be -imported. (‘import’ is idempotent.) - - Since the items being read (CSV records, eg) often do not come with -unique identifiers, hledger detects new transactions by date, assuming -that: - - 1. new items always have the newest dates - 2. item dates do not change across reads - 3. and items with the same date remain in the same relative order - across reads. - - These are often true of CSV files representing transactions, or true -enough so that it works pretty well in practice. 1 is important, but -violations of 2 and 3 amongst the old transactions won’t matter (and if -you import often, the new transactions will be few, so less likely to be -the ones affected). - - hledger remembers the latest date processed in each input file by -saving a hidden ".latest" state file in the same directory. Eg when -reading ‘finance/bank.csv’, it will look for and update the -‘finance/.latest.bank.csv’ state file. The format is simple: one or -more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I -have processed transactions up to this date, and this many of them on -that date." Normally you won’t see or manipulate these state files -yourself. But if needed, you can delete them to reset the state (making -all transactions "new"), or you can construct them to "catch up" to a -certain date. - - Note deduplication (and updating of state files) can also be done by -‘print --new’, but this is less often used. - - -File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import - -24.18.2 Import testing ----------------------- - -With ‘--dry-run’, the transactions that will be imported are printed to -the terminal, without updating your journal or state files. The output -is valid journal format, like the print command, so you can re-parse it. -Eg, to see any importable transactions which CSV rules have not -categorised: - -$ hledger import --dry bank.csv | hledger -f- -I print unknown - - or (live updating): - -$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' - - Note: when importing from multiple files at once, it’s currently -possible for some .latest files to be updated successfully, while the -actual import fails because of a problem in one of the files, leaving -them out of sync (and causing some transactions to be missed). To -prevent this, do a –dry-run first and fix any problems before the real -import. - - -File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import - -24.18.3 Importing balance assignments -------------------------------------- - -Entries added by import will have their posting amounts made explicit -(like ‘hledger print -x’). This means that any balance assignments in -imported files must be evaluated; but, imported files don’t get to see -the main file’s account balances. As a result, importing entries with -balance assignments (eg from an institution that provides only balances -and not posting amounts) will probably generate incorrect posting -amounts. To avoid this problem, use print instead of import: - -$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - - (If you think import should leave amounts implicit like print does, -please test it and send a pull request.) - - -File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import - -24.18.4 Commodity display styles --------------------------------- - -Imported amounts will be formatted according to the canonical commodity -styles (declared or inferred) in the main journal file. - - -File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS - -24.19 incomestatement -===================== - -(is) - - This command displays an income statement, showing revenues and -expenses during one or more periods. Amounts are shown with normal -positive sign, as in conventional financial statements. - - This report shows accounts declared with the ‘Revenue’ or ‘Expense’ -type (see account types). Or if no such accounts are declared, it shows -top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case -insensitive, plurals allowed) and their subaccounts. - - Example: - -$ hledger incomestatement -Income Statement - -Revenues: - $-2 income - $-1 gifts - $-1 salary --------------------- - $-2 - -Expenses: - $2 expenses - $1 food - $1 supplies --------------------- - $2 - -Total: --------------------- - 0 - - This command is a higher-level variant of the ‘balance’ command, and -supports many of that command’s features, such as multi-period reports. -It is similar to ‘hledger balance '(revenues|income)' expenses’, but -with smarter account detection, and revenues/income displayed with their -sign flipped. - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, ‘html’, and -(experimental) ‘json’. - - -File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS - -24.20 notes -=========== - -List the unique notes that appear in transactions. - - This command lists the unique notes that appear in transactions, in -alphabetic order. You can add a query to select a subset of -transactions. The note is the part of the transaction description after -a | character (or if there is no |, the whole description). - - Example: - -$ hledger notes -Petrol -Snacks - - -File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS - -24.21 payees -============ - -List the unique payee/payer names that appear in transactions. - - This command lists unique payee/payer names which have been declared -with payee directives (–declared), used in transaction descriptions -(–used), or both (the default). - - The payee/payer is the part of the transaction description before a | -character (or if there is no |, the whole description). - - You can add query arguments to select a subset of transactions. This -implies –used. - - Example: - -$ hledger payees -Store Name -Gas Station -Person A - - -File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS - -24.22 prices -============ - -Print market price directives from the journal. With -–infer-market-prices, generate additional market prices from costs. -With –infer-reverse-prices, also generate market prices by inverting -known prices. Prices can be filtered by a query. Price amounts are -displayed with their full precision. - - -File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS - -24.23 print -=========== - -Show transaction journal entries, sorted by date. - - The print command displays full journal entries (transactions) from -the journal file, sorted by date (or with ‘--date2’, by secondary date). - - Amounts are shown mostly normalised to commodity display style, eg -the placement of commodity symbols will be consistent. All of their -decimal places are shown, as in the original journal entry (with one -alteration: in some cases trailing zeroes are added.) - - Amounts are shown right-aligned within each transaction (but not -across all transactions). - - Directives and inter-transaction comments are not shown, currently. -This means the print command is somewhat lossy, and if you are using it -to reformat your journal you should take care to also copy over the -directives and file-level comments. - - Eg: - -$ 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 - - print’s output is usually a valid hledger journal, and you can -process it again with a second hledger command. This can be useful for -certain kinds of search, eg: - -# Show running total of food expenses paid from cash. -# -f- reads from stdin. -I/--ignore-assertions is sometimes needed. -$ hledger print assets:cash | hledger -f- -I reg expenses:food - - There are some situations where print’s output can become -unparseable: - - • Valuation affects posting amounts but not balance assertion or - balance assignment amounts, potentially causing those to fail. - • Auto postings can generate postings with too many missing amounts. - • Account aliases can generate bad account names. - - Normally, the journal entry’s explicit or implicit amount style is -preserved. For example, when an amount is omitted in the journal, it -will not appear in the output. Similarly, when a cost is implied but -not written, it will not appear in the output. You can use the -‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can -be useful for troubleshooting or for making your journal more readable -and robust against data entry errors. ‘-x’ is also implied by using any -of ‘-B’,‘-V’,‘-X’,‘--value’. - - Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity -amount (these can arise when a multi-commodity transaction has an -implicit amount) to be split into multiple single-commodity postings, -keeping the output parseable. - - With ‘-B’/‘--cost’, amounts with costs are converted to cost using -that price. This can be used for troubleshooting. - - With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one -recent transaction whose description is most similar to DESC. DESC -should contain at least two characters. If there is no similar-enough -match, no transaction will be shown and the program exit code will be -non-zero. - - With ‘--new’, hledger prints only transactions it has not seen on a -previous run. This uses the same deduplication system as the ‘import’ -command. (See import’s docs for details.) - - This command also supports the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, and -(experimental) ‘json’ and ‘sql’. - - 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: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS - -24.24 register -============== - -(reg) - - Show postings and their running total. - - The register command displays matched postings, across all accounts, -in date order, with their running total or running historical balance. -(See also the ‘aregister’ command, which shows matched transactions in a -specific account.) - - register normally shows line per posting, but note that -multi-commodity amounts will occupy multiple lines (one line per -commodity). - - It 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. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -‘--align-all’ flag. - - 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. - - The ‘--invert’ flag negates all amounts. For example, it can be used -on an income account where amounts are normally displayed as negative -numbers. It’s also useful to show postings on the checking account -together with the related account: - -$ hledger register --related --invert assets:checking - - 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. - - With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one -recent posting whose description is most similar to DESC. DESC should -contain at least two characters. If there is no similar-enough match, -no posting will be shown and the program exit code will be non-zero. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -24.24.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 the output destination and output format -options The output formats supported are ‘txt’, ‘csv’, and -(experimental) ‘json’. - - -File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS - -24.25 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:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -24.25.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. - - -File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite - -24.25.2 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: rewrite - -24.25.3 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: PART 4 COMMANDS - -24.26 roi -========= - -Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on -your investments. - - At a minimum, you need to supply a query (which could be just an -account name) to select your investment(s) with ‘--inv’, and another -query to identify your profit and loss transactions with ‘--pnl’. - - If you do not record changes in the value of your investment -manually, or do not require computation of time-weighted return (TWR), -‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’ -does not match any of your accounts). - - This command 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. - - Price directives will be taken into account if you supply appropriate -‘--cost’ or ‘--value’ flags (see VALUATION). - - Note, in some cases this report can fail, for these reasons: - - • Error (NotBracketed): No solution for Internal Rate of Return - (IRR). Possible causes: IRR is huge (>1000000%), balance of - investment becomes negative at some point in time. - • Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or - converges too slowly. - - Examples: - - • Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger - - • Cookbook > Return on Investment: https://hledger.org/roi.html - -* Menu: - -* Spaces and special characters in --inv and --pnl:: -* Semantics of --inv and --pnl:: -* IRR and TWR explained:: - - -File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi - -24.26.1 Spaces and special characters in ‘--inv’ and ----------------------------------------------------- - -‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries -could have several space-separated terms (see QUERIES). - - To indicate that all search terms form single command-line argument, -you will need to put them in quotes (see Special characters): - -$ hledger roi --inv 'term1 term2 term3 ...' - - If any query terms contain spaces themselves, you will need an extra -level of nested quoting, eg: - -$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" - - -File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi - -24.26.2 Semantics of ‘--inv’ and ‘--pnl’ ----------------------------------------- - -Query supplied to ‘--inv’ has to match all transactions that are related -to your investment. Transactions not matching ‘--inv’ will be ignored. - - In these transactions, ROI will conside postings that match ‘--inv’ -to be "investment postings" and other postings (not matching ‘--inv’) -will be sorted into two categories: "cash flow" and "profit and loss", -as ROI needs to know which part of the investment value is your -contributions and which is due to the return on investment. - - • "Cash flow" is depositing or withdrawing money, buying or selling - assets, or otherwise converting between your investment commodity - and any other commodity. Example: - - 2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil - - 2020-01-01 Selling my Snake Oil - assets:cash $10 - investment:snake oil = 0 - - • "Profit and loss" is change in the value of your investment: - - 2019-06-01 Snake Oil falls in value - investment:snake oil = $57 - equity:unrealized profit or loss - - All non-investment postings are assumed to be "cash flow", unless -they match ‘--pnl’ query. Changes in value of your investment due to -"profit and loss" postings will be considered as part of your investment -return. - - Example: if you use ‘--inv snake --pnl equity:unrealized’, then -postings in the example below would be classifed as: - -2019-01-01 Snake Oil #1 - assets:cash -$100 ; cash flow posting - investment:snake oil ; investment posting - -2019-03-01 Snake Oil #2 - equity:unrealized pnl -$100 ; profit and loss posting - snake oil ; investment posting - -2019-07-01 Snake Oil #3 - equity:unrealized pnl ; profit and loss posting - cash -$100 ; cash flow posting - snake oil $50 ; investment posting - - -File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi - -24.26.3 IRR and TWR explained ------------------------------ - -"ROI" stands for "return on investment". Traditionally this was -computed as a difference between current value of investment and its -initial value, expressed in percentage of the initial value. - - However, this approach is only practical in simple cases, where -investments receives no in-flows or out-flows of money, and where rate -of growth is fixed over time. For more complex scenarios you need -different ways to compute rate of return, and this command implements -two of them: IRR and TWR. - - Internal rate of return, or "IRR" (also called "money-weighted rate -of return") takes into account effects of in-flows and out-flows. -Naively, if you are withdrawing from your investment, your future gains -would be smaller (in absolute numbers), and will be a smaller percentage -of your initial investment, and if you are adding to your investment, -you will receive bigger absolute gains (but probably at the same rate of -return). IRR is a way to compute rate of return for each period between -in-flow or out-flow of money, and then combine them in a way that gives -you a compound annual rate of return that investment is expected to -generate. - - As mentioned before, in-flows and out-flows would be any cash that -you personally put in or withdraw, and for the "roi" command, these are -the postings that match the query in the‘--inv’ argument and NOT match -the query in the‘--pnl’ argument. - - If you manually record changes in the value of your investment as -transactions that balance them against "profit and loss" (or "unrealized -gains") account or use price directives, then in order for IRR to -compute the precise effect of your in-flows and out-flows on the rate of -return, you will need to record the value of your investement on or -close to the days when in- or out-flows occur. - - In technical terms, IRR uses the same approach as computation of net -present value, and tries to find a discount rate that makes net present -value of all the cash flows of your investment to add up to zero. This -could be hard to wrap your head around, especially if you haven’t done -discounted cash flow analysis before. Implementation of IRR in hledger -should produce results that match the ‘XIRR’ formula in Excel. - - Second way to compute rate of return that ‘roi’ command implements is -called "time-weighted rate of return" or "TWR". Like IRR, it will also -break the history of your investment into periods between in-flows, -out-flows and value changes, to compute rate of return per each period -and then a compound rate of return. However, internal workings of TWR -are quite different. - - TWR represents your investment as an imaginary "unit fund" where -in-flows/ out-flows lead to buying or selling "units" of your investment -and changes in its value change the value of "investment unit". Change -in "unit price" over the reporting period gives you rate of return of -your investment. - - References: - - • Explanation of rate of return - • Explanation of IRR - • Explanation of TWR - • Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS - -24.27 stats -=========== - -Show journal and performance 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. - - At the end, it shows (in the terminal) the overall run time and -number of transactions processed per second. Note these are approximate -and will vary based on machine, current load, data size, hledger -version, haskell lib versions, GHC version.. but they may be of -interest. The ‘stats’ command’s run time is similar to that of a -single-column balance report. - - Example: - -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s - - This command supports the -o/–output-file option (but not --O/–output-format selection). - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS - -24.28 tags -========== - -List the tags used in the journal, or their values. - - This command lists the tag names used in the journal, whether on -transactions, postings, or account declarations. - - With a TAGREGEX argument, only tag names matching this regular -expression (case insensitive, infix matched) are shown. - - With QUERY arguments, only transactions and accounts matching this -query are considered. If the query involves transaction fields (date:, -desc:, amt:, ...), the search is restricted to the matched transactions -and their accounts. - - With the –values flag, the tags’ unique non-empty values are listed -instead. With -E/–empty, blank/empty values are also shown. - - With –parsed, tags or values are shown in the order they were parsed, -with duplicates included. (Except, tags from account declarations are -always shown first.) - - Tip: remember, accounts also acquire tags from their parents, -postings also acquire tags from their account and transaction, -transactions also acquire tags from their postings. - - -File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS - -24.29 test -========== - -Run built-in unit tests. - - This command runs the unit tests built in to hledger and hledger-lib, -printing the results on stdout. If any test fails, the exit code will -be non-zero. - - This is mainly used by hledger developers, but you can also use it to -sanity-check the installed hledger executable on your platform. All -tests are expected to pass - if you ever see a failure, please report as -a bug! - - This command also accepts tasty test runner options, written after a -– (double hyphen). Eg to run only the tests in Hledger.Data.Amount, -with ANSI colour codes disabled: - -$ hledger test -- -pData.Amount --color=never - - For help on these, see https://github.com/feuerbach/tasty#options -(‘-- --help’ currently doesn’t show them). - - -File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top - -25 PART 5: COMMON TASKS -*********************** - -Here are some quick examples of how to do some basic tasks with hledger. - -* Menu: - -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: - - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS - -25.1 Getting help -================= - -Here’s how to list commands and view options and command docs: - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version’s manual in several formats by -using the help command. Eg: - -$ hledger help # show the hledger manual with info, man or $PAGER (best available) -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit -https://hledger.org. Chat and mail list support and discussion archives -can be found at https://hledger.org/support. - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS - -25.2 Constructing command lines -=============================== - -hledger has a flexible command line interface. We strive to keep it -simple and ergonomic, but if you run into one of the sharp edges -described in OPTIONS, here are some tips that might help: - - • command-specific options must go after the command (it’s fine to - put common options there too: ‘hledger CMD OPTS ARGS’) - • running add-on executables directly simplifies command line parsing - (‘hledger-ui OPTS ARGS’) - • enclose "problematic" args in single quotes - • if needed, also add a backslash to hide regular expression - metacharacters from the shell - • to see how a misbehaving command line is being parsed, add - ‘--debug=2’. - - -File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS - -25.3 Starting a journal file -============================ - -hledger looks for your accounting data in a journal file, -‘$HOME/.hledger.journal’ by default: - -$ hledger stats -The hledger journal file "/Users/simon/.hledger.journal" was not found. -Please create it first, eg with "hledger add" or a text editor. -Or, specify an existing journal file with -f or LEDGER_FILE. - - You can override this by setting the ‘LEDGER_FILE’ environment -variable. It’s a good practice to keep this important file under -version control, and to start a new file each year. So you could do -something like this: - -$ mkdir ~/finance -$ cd ~/finance -$ git init -Initialized empty Git repository in /Users/simon/finance/.git/ -$ touch 2020.journal -$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc -$ source ~/.bashrc -$ hledger stats -Main file : /Users/simon/finance/2020.journal -Included files : -Transactions span : to (0 days) -Last transaction : none -Transactions : 0 (0.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 0 -Accounts : 0 (depth 0) -Commodities : 0 () -Market prices : 0 () - - -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS - -25.4 Setting opening balances -============================= - -Pick a starting date for which you can look up the balances of some -real-world assets (bank accounts, wallet..) and liabilities (credit -cards..). - - To avoid a lot of data entry, you may want to start with just one or -two accounts, like your checking account or cash wallet; and pick a -recent starting date, like today or the start of the week. You can -always come back later and add more accounts and older transactions, eg -going back to january 1st. - - Add an opening balances transaction to the journal, declaring the -balances on this date. Here are two ways to do it: - - • The first way: open the journal in any text editor and save an - entry like this: - - 2020-01-01 * opening balances - assets:bank:checking $1000 = $1000 - assets:bank:savings $2000 = $2000 - assets:cash $100 = $100 - liabilities:creditcard $-50 = $-50 - equity:opening/closing balances - - These are start-of-day balances, ie whatever was in the account at - the end of the previous day. - - The * after the date is an optional status flag. Here it means - "cleared & confirmed". - - The currency symbols are optional, but usually a good idea as - you’ll be dealing with multiple currencies sooner or later. - - The = amounts are optional balance assertions, providing extra - error checking. - - • The second way: run ‘hledger add’ and follow the prompts to record - a similar transaction: - - $ hledger add - Adding transactions to journal file /Users/simon/finance/2020.journal - 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 go one step backward. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2020-02-07]: 2020-01-01 - Description: * opening balances - Account 1: assets:bank:checking - Amount 1: $1000 - Account 2: assets:bank:savings - Amount 2 [$-1000]: $2000 - Account 3: assets:cash - Amount 3 [$-3000]: $100 - Account 4: liabilities:creditcard - Amount 4 [$-3100]: $-50 - Account 5: equity:opening/closing balances - Amount 5 [$-3050]: - Account 6 (or . or enter to finish this transaction): . - 2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2020-01-01]: . - - If you’re using version control, this could be a good time to commit -the journal. Eg: - -$ git commit -m 'initial balances' 2020.journal - - -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS - -25.5 Recording transactions -=========================== - -As you spend or receive money, you can record these transactions using -one of the methods above (text editor, hledger add) or by using the -hledger-iadd or hledger-web add-ons, or by using the import command to -convert CSV data downloaded from your bank. - - Here are some simple transactions, see the hledger_journal(5) manual -and hledger.org for more ideas: - -2020/1/10 * gift received - assets:cash $20 - income:gifts - -2020.1.12 * farmers market - expenses:food $13 - assets:cash - -2020-01-15 paycheck - income:salary - assets:bank:checking $1000 - - -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS - -25.6 Reconciling -================ - -Periodically you should reconcile - compare your hledger-reported -balances against external sources of truth, like bank statements or your -bank’s website - to be sure that your ledger accurately represents the -real-world balances (and, that the real-world institutions have not made -a mistake!). This gets easy and fast with (1) practice and (2) -frequency. If you do it daily, it can take 2-10 minutes. If you let it -pile up, expect it to take longer as you hunt down errors and -discrepancies. - - A typical workflow: - - 1. Reconcile cash. Count what’s in your wallet. Compare with what - hledger reports (‘hledger bal cash’). If they are different, try - to remember the missing transaction, or look for the error in the - already-recorded transactions. A register report can be helpful - (‘hledger reg cash’). If you can’t find the error, add an - adjustment transaction. Eg if you have $105 after the above, and - can’t explain the missing $2, it could be: - - 2020-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - 2. Reconcile checking. Log in to your bank’s website. Compare - today’s (cleared) balance with hledger’s cleared balance (‘hledger - bal checking -C’). If they are different, track down the error or - record the missing transaction(s) or add an adjustment transaction, - similar to the above. Unlike the cash case, you can usually - compare the transaction history and running balance from your bank - with the one reported by ‘hledger reg checking -C’. This will be - easier if you generally record transaction dates quite similar to - your bank’s clearing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a -live-updating register while you edit the journal: ‘hledger-ui --watch ---register checking -C’ - - After reconciling, it could be a good time to mark the reconciled -transactions’ status as "cleared and confirmed", if you want to track -that, by adding the ‘*’ marker. Eg in the paycheck transaction above, -insert ‘*’ between ‘2020-01-15’ and ‘paycheck’ - - If you’re using version control, this can be another good time to -commit: - -$ git commit -m 'txns' 2020.journal - - -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS - -25.7 Reporting -============== - -Here are some basic reports. - - Show all transactions: - -$ hledger print -2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -2020-01-10 * gift received - assets:cash $20 - income:gifts - -2020-01-12 * farmers market - expenses:food $13 - assets:cash - -2020-01-15 * paycheck - income:salary - assets:bank:checking $1000 - -2020-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - -$ hledger accounts --tree -assets - bank - checking - savings - cash -equity - opening/closing balances -expenses - food - misc -income - gifts - salary -liabilities - creditcard - - Show all account totals: - -$ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard --------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to -depth 2: - -$ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard --------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple -balance sheet: - -$ hledger bs -2 -Balance Sheet 2020-01-16 - - || 2020-01-16 -========================++============ - Assets || -------------------------++------------ - assets:bank || $4000 - assets:cash || $105 -------------------------++------------ - || $4105 -========================++============ - Liabilities || -------------------------++------------ - liabilities:creditcard || $50 -------------------------++------------ - || $50 -========================++============ - Net: || $4055 - - The final total is your "net worth" on the end date. (Or use ‘bse’ -for a full balance sheet with equity.) - - Show income and expense totals, formatted as an income statement: - -hledger is -Income Statement 2020-01-01-2020-01-16 - - || 2020-01-01-2020-01-16 -===============++======================= - Revenues || ----------------++----------------------- - income:gifts || $20 - income:salary || $1000 ----------------++----------------------- - || $1020 -===============++======================= - Expenses || ----------------++----------------------- - expenses:food || $13 - expenses:misc || $2 ----------------++----------------------- - || $15 -===============++======================= - Net: || $1005 - - The final total is your net income during this period. - - Show transactions affecting your wallet, with running total: - -$ hledger register cash -2020-01-01 opening balances assets:cash $100 $100 -2020-01-10 gift received assets:cash $20 $120 -2020-01-12 farmers market assets:cash $-13 $107 -2020-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - -$ hledger activity -W -2019-12-30 ***** -2020-01-06 **** -2020-01-13 **** - - -File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS - -25.8 Migrating to a new file -============================ - -At the end of the year, you may want to continue your journal in a new -file, so that old transactions don’t slow down or clutter your reports, -and to help ensure the integrity of your accounting history. See the -close command. - - If using version control, don’t forget to ‘git add’ the new file. - - -Tag Table: -Node: Top210 -Node: PART 1 USER INTERFACE3944 -Ref: #part-1-user-interface4085 -Node: Options4085 -Ref: #options4204 -Node: General options4346 -Ref: #general-options4471 -Node: Command options8921 -Ref: #command-options9072 -Node: Command arguments9488 -Ref: #command-arguments9646 -Node: Special characters10548 -Ref: #special-characters10711 -Node: Single escaping shell metacharacters10874 -Ref: #single-escaping-shell-metacharacters11115 -Node: Double escaping regular expression metacharacters11750 -Ref: #double-escaping-regular-expression-metacharacters12061 -Node: Triple escaping for add-on commands12631 -Ref: #triple-escaping-for-add-on-commands12891 -Node: Less escaping13559 -Ref: #less-escaping13713 -Node: Unicode characters14051 -Ref: #unicode-characters14216 -Node: Regular expressions15648 -Ref: #regular-expressions15788 -Node: Environment17642 -Ref: #environment17753 -Node: Input19364 -Ref: #input19464 -Node: Data formats20027 -Ref: #data-formats20140 -Node: Multiple files21592 -Ref: #multiple-files21729 -Node: Strict mode22214 -Ref: #strict-mode22324 -Node: Commands23078 -Ref: #commands23179 -Node: Add-on commands23663 -Ref: #add-on-commands23765 -Node: Output24932 -Ref: #output25035 -Node: Output destination25151 -Ref: #output-destination25282 -Node: Output format25711 -Ref: #output-format25857 -Node: CSV output27429 -Ref: #csv-output27545 -Node: HTML output27650 -Ref: #html-output27788 -Node: JSON output27888 -Ref: #json-output28026 -Node: SQL output28958 -Ref: #sql-output29074 -Node: Commodity styles29597 -Ref: #commodity-styles29737 -Node: Colour30344 -Ref: #colour30462 -Node: Box-drawing30896 -Ref: #box-drawing31020 -Node: Debug output31334 -Ref: #debug-output31445 -Node: Limitations32120 -Ref: #limitations32240 -Node: Troubleshooting33015 -Ref: #troubleshooting33156 -Node: PART 2 DATA FORMATS35678 -Ref: #part-2-data-formats35825 -Node: Journal35825 -Ref: #journal35936 -Node: Journal cheatsheet36579 -Ref: #journal-cheatsheet36720 -Node: About journal format40708 -Ref: #about-journal-format40870 -Node: Comments42408 -Ref: #comments42540 -Node: Transactions43394 -Ref: #transactions43519 -Node: Dates44553 -Ref: #dates44662 -Node: Simple dates44707 -Ref: #simple-dates44825 -Node: Posting dates45357 -Ref: #posting-dates45477 -Node: Status46460 -Ref: #status46563 -Node: Code48315 -Ref: #code48420 -Node: Description48652 -Ref: #description48785 -Node: Payee and note49107 -Ref: #payee-and-note49215 -Node: Transaction comments49562 -Ref: #transaction-comments49717 -Node: Postings50088 -Ref: #postings50223 -Node: Account names51232 -Ref: #account-names51364 -Node: Amounts53066 -Ref: #amounts53183 -Node: Decimal marks digit group marks54172 -Ref: #decimal-marks-digit-group-marks54349 -Node: Commodity55373 -Ref: #commodity55562 -Node: Directives influencing number parsing and display56544 -Ref: #directives-influencing-number-parsing-and-display56805 -Node: Commodity display style57267 -Ref: #commodity-display-style57475 -Node: Rounding59686 -Ref: #rounding59806 -Node: Costs60107 -Ref: #costs60225 -Node: Other cost/lot notations62256 -Ref: #other-costlot-notations62390 -Node: Balance assertions65143 -Ref: #balance-assertions65296 -Node: Assertions and ordering66389 -Ref: #assertions-and-ordering66580 -Node: Assertions and multiple included files67282 -Ref: #assertions-and-multiple-included-files67544 -Node: Assertions and multiple -f files68052 -Ref: #assertions-and-multiple--f-files68305 -Node: Assertions and commodities68714 -Ref: #assertions-and-commodities68938 -Node: Assertions and prices70128 -Ref: #assertions-and-prices70336 -Node: Assertions and subaccounts70767 -Ref: #assertions-and-subaccounts70990 -Node: Assertions and virtual postings71332 -Ref: #assertions-and-virtual-postings71572 -Node: Assertions and auto postings71712 -Ref: #assertions-and-auto-postings71944 -Node: Assertions and precision72615 -Ref: #assertions-and-precision72799 -Node: Posting comments73066 -Ref: #posting-comments73214 -Node: Tags73599 -Ref: #tags73715 -Node: Tag values74920 -Ref: #tag-values75011 -Node: Directives75784 -Ref: #directives75913 -Node: Directive effects77781 -Ref: #directive-effects77937 -Node: Directives and multiple files81020 -Ref: #directives-and-multiple-files81200 -Node: account directive81910 -Ref: #account-directive82072 -Node: Account comments83492 -Ref: #account-comments83644 -Node: Account subdirectives84164 -Ref: #account-subdirectives84357 -Node: Account error checking84499 -Ref: #account-error-checking84699 -Node: Account display order85918 -Ref: #account-display-order86108 -Node: Account types87247 -Ref: #account-types87390 -Node: alias directive91125 -Ref: #alias-directive91292 -Node: Basic aliases92352 -Ref: #basic-aliases92485 -Node: Regex aliases93239 -Ref: #regex-aliases93398 -Node: Combining aliases94292 -Ref: #combining-aliases94472 -Node: Aliases and multiple files95766 -Ref: #aliases-and-multiple-files95972 -Node: end aliases directive96557 -Ref: #end-aliases-directive96782 -Node: Aliases can generate bad account names96931 -Ref: #aliases-can-generate-bad-account-names97181 -Node: Aliases and account types97778 -Ref: #aliases-and-account-types97972 -Node: commodity directive98674 -Ref: #commodity-directive98854 -Node: Commodity error checking101458 -Ref: #commodity-error-checking101606 -Node: decimal-mark directive102135 -Ref: #decimal-mark-directive102323 -Node: include directive102724 -Ref: #include-directive102894 -Node: P directive103842 -Ref: #p-directive103993 -Node: payee directive104892 -Ref: #payee-directive105047 -Node: tag directive105367 -Ref: #tag-directive105528 -Node: Periodic transactions106000 -Ref: #periodic-transactions106166 -Node: Periodic rule syntax107904 -Ref: #periodic-rule-syntax108084 -Node: Periodic rules and relative dates108739 -Ref: #periodic-rules-and-relative-dates109007 -Node: Two spaces between period expression and description!109546 -Ref: #two-spaces-between-period-expression-and-description109825 -Node: Other syntax110515 -Ref: #other-syntax110641 -Node: Auto postings111286 -Ref: #auto-postings111422 -Node: Auto postings and multiple files113933 -Ref: #auto-postings-and-multiple-files114135 -Node: Auto postings and dates114352 -Ref: #auto-postings-and-dates114624 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions114799 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115138 -Node: Auto posting tags115645 -Ref: #auto-posting-tags115858 -Node: Balance assignments116520 -Ref: #balance-assignments116700 -Node: Balance assignments and prices118034 -Ref: #balance-assignments-and-prices118204 -Node: Bracketed posting dates118415 -Ref: #bracketed-posting-dates118601 -Node: D directive119145 -Ref: #d-directive119319 -Node: apply account directive120987 -Ref: #apply-account-directive121173 -Node: Y directive121872 -Ref: #y-directive122038 -Node: Secondary dates122882 -Ref: #secondary-dates123038 -Node: Star comments123870 -Ref: #star-comments124032 -Node: Valuation expressions124572 -Ref: #valuation-expressions124751 -Node: Virtual postings124873 -Ref: #virtual-postings125054 -Node: Other Ledger directives126626 -Ref: #other-ledger-directives126791 -Node: CSV127361 -Ref: #csv127454 -Node: CSV rules cheatsheet129557 -Ref: #csv-rules-cheatsheet129689 -Node: separator131457 -Ref: #separator131588 -Node: skip132166 -Ref: #skip132278 -Node: date-format132861 -Ref: #date-format132986 -Node: timezone133732 -Ref: #timezone133859 -Node: newest-first134892 -Ref: #newest-first135034 -Node: intra-day-reversed135618 -Ref: #intra-day-reversed135776 -Node: decimal-mark136273 -Ref: #decimal-mark136418 -Node: fields list136757 -Ref: #fields-list136898 -Node: Field assignment138621 -Ref: #field-assignment138765 -Node: Field names139814 -Ref: #field-names139945 -Node: date field141166 -Ref: #date-field141284 -Node: date2 field141336 -Ref: #date2-field141477 -Node: status field141539 -Ref: #status-field141682 -Node: code field141737 -Ref: #code-field141882 -Node: description field141933 -Ref: #description-field142093 -Node: comment field142158 -Ref: #comment-field142313 -Node: account field142626 -Ref: #account-field142776 -Node: amount field143372 -Ref: #amount-field143521 -Node: currency field145626 -Ref: #currency-field145779 -Node: balance field146048 -Ref: #balance-field146180 -Node: if block146568 -Ref: #if-block146693 -Node: Matchers148117 -Ref: #matchers148231 -Node: if table149761 -Ref: #if-table149887 -Node: balance-type151323 -Ref: #balance-type151456 -Node: include152164 -Ref: #include152295 -Node: Working with CSV152745 -Ref: #working-with-csv152892 -Node: Rapid feedback153263 -Ref: #rapid-feedback153396 -Node: Valid CSV153852 -Ref: #valid-csv153998 -Node: File Extension154752 -Ref: #file-extension154925 -Node: Reading CSV from standard input155515 -Ref: #reading-csv-from-standard-input155739 -Node: Reading multiple CSV files155905 -Ref: #reading-multiple-csv-files156123 -Node: Valid transactions156372 -Ref: #valid-transactions156566 -Node: Deduplicating importing157194 -Ref: #deduplicating-importing157389 -Node: Setting amounts158435 -Ref: #setting-amounts158606 -Node: Amount signs161129 -Ref: #amount-signs161297 -Node: Setting currency/commodity162036 -Ref: #setting-currencycommodity162240 -Node: Amount decimal places163432 -Ref: #amount-decimal-places163638 -Node: Referencing other fields163956 -Ref: #referencing-other-fields164169 -Node: How CSV rules are evaluated165072 -Ref: #how-csv-rules-are-evaluated165289 -Node: Well factored rules166802 -Ref: #well-factored-rules166970 -Node: CSV rules examples167308 -Ref: #csv-rules-examples167443 -Node: Bank of Ireland167508 -Ref: #bank-of-ireland167645 -Node: Coinbase169113 -Ref: #coinbase169251 -Node: Amazon170304 -Ref: #amazon170429 -Node: Paypal172154 -Ref: #paypal172262 -Node: Timeclock179908 -Ref: #timeclock180013 -Node: Timedot182181 -Ref: #timedot182304 -Node: PART 3 REPORTING CONCEPTS187155 -Ref: #part-3-reporting-concepts187319 -Node: Time periods187319 -Ref: #time-periods187453 -Node: Report start & end date187571 -Ref: #report-start-end-date187723 -Node: Smart dates189456 -Ref: #smart-dates189609 -Node: Report intervals191569 -Ref: #report-intervals191724 -Node: Date adjustment192176 -Ref: #date-adjustment192336 -Node: Period expressions193668 -Ref: #period-expressions193809 -Node: Period expressions with a report interval195645 -Ref: #period-expressions-with-a-report-interval195879 -Node: More complex report intervals196109 -Ref: #more-complex-report-intervals196354 -Node: Multiple weekday intervals198283 -Ref: #multiple-weekday-intervals198472 -Node: Depth199336 -Ref: #depth199438 -Node: Queries199758 -Ref: #queries199860 -Node: Query types200805 -Ref: #query-types200926 -Node: Combining query terms204266 -Ref: #combining-query-terms204443 -Node: Queries and command options205541 -Ref: #queries-and-command-options205740 -Node: Queries and valuation206005 -Ref: #queries-and-valuation206200 -Node: Querying with account aliases206439 -Ref: #querying-with-account-aliases206650 -Node: Querying with cost or value206792 -Ref: #querying-with-cost-or-value206969 -Node: Pivoting207278 -Ref: #pivoting207392 -Node: Generating data208880 -Ref: #generating-data209012 -Node: Forecasting209510 -Ref: #forecasting209635 -Node: Budgeting212522 -Ref: #budgeting212642 -Node: Cost reporting212913 -Ref: #cost-reporting213041 -Node: -B Convert to cost214156 -Ref: #b-convert-to-cost214312 -Node: Equity conversion postings215720 -Ref: #equity-conversion-postings215934 -Node: Inferring equity postings from cost216829 -Ref: #inferring-equity-postings-from-cost217078 -Node: Inferring cost from equity postings217897 -Ref: #inferring-cost-from-equity-postings218145 -Node: When to infer cost/equity219954 -Ref: #when-to-infer-costequity220172 -Node: How to record conversions220580 -Ref: #how-to-record-conversions220772 -Node: Conversion with implicit cost221063 -Ref: #conversion-with-implicit-cost221268 -Node: Conversion with explicit cost222173 -Ref: #conversion-with-explicit-cost222418 -Node: Conversion with equity postings222845 -Ref: #conversion-with-equity-postings223114 -Node: Conversion with equity postings and explicit cost223951 -Ref: #conversion-with-equity-postings-and-explicit-cost224218 -Node: Cost tips224692 -Ref: #cost-tips224818 -Node: Valuation225554 -Ref: #valuation225678 -Node: -V Value226464 -Ref: #v-value226590 -Node: -X Value in specified commodity226789 -Ref: #x-value-in-specified-commodity226984 -Node: Valuation date227141 -Ref: #valuation-date227312 -Node: Finding market price227751 -Ref: #finding-market-price227956 -Node: --infer-market-prices market prices from transactions229136 -Ref: #infer-market-prices-market-prices-from-transactions229414 -Node: Valuation commodity232260 -Ref: #valuation-commodity232473 -Node: Simple valuation examples233718 -Ref: #simple-valuation-examples233916 -Node: --value Flexible valuation234579 -Ref: #value-flexible-valuation234785 -Node: More valuation examples236471 -Ref: #more-valuation-examples236680 -Node: Interaction of valuation and queries238691 -Ref: #interaction-of-valuation-and-queries238932 -Node: Effect of valuation on reports239412 -Ref: #effect-of-valuation-on-reports239609 -Node: PART 4 COMMANDS247368 -Ref: #part-4-commands247511 -Node: Commands overview247881 -Ref: #commands-overview248015 -Node: DATA ENTRY248194 -Ref: #data-entry248318 -Node: DATA CREATION248521 -Ref: #data-creation248675 -Node: DATA MANAGEMENT248799 -Ref: #data-management248964 -Node: REPORTS FINANCIAL249089 -Ref: #reports-financial249264 -Node: REPORTS VERSATILE249579 -Ref: #reports-versatile249752 -Node: REPORTS BASIC250013 -Ref: #reports-basic250165 -Node: HELP250698 -Ref: #help250820 -Node: ADD-ONS250879 -Ref: #add-ons250985 -Node: accounts251582 -Ref: #accounts251715 -Node: activity253690 -Ref: #activity253809 -Node: add254183 -Ref: #add254293 -Node: aregister257154 -Ref: #aregister257275 -Node: aregister and custom posting dates260251 -Ref: #aregister-and-custom-posting-dates260417 -Node: balance260985 -Ref: #balance261111 -Node: balance features262116 -Ref: #balance-features262256 -Node: Simple balance report264386 -Ref: #simple-balance-report264571 -Node: Balance report line format266216 -Ref: #balance-report-line-format266418 -Node: Filtered balance report268668 -Ref: #filtered-balance-report268860 -Node: List or tree mode269187 -Ref: #list-or-tree-mode269355 -Node: Depth limiting270730 -Ref: #depth-limiting270896 -Node: Dropping top-level accounts271513 -Ref: #dropping-top-level-accounts271713 -Node: Showing declared accounts272027 -Ref: #showing-declared-accounts272226 -Node: Sorting by amount272767 -Ref: #sorting-by-amount272934 -Node: Percentages273624 -Ref: #percentages273783 -Node: Multi-period balance report274353 -Ref: #multi-period-balance-report274553 -Node: Balance change end balance276946 -Ref: #balance-change-end-balance277155 -Node: Balance report types278603 -Ref: #balance-report-types278784 -Node: Calculation type279300 -Ref: #calculation-type279455 -Node: Accumulation type279986 -Ref: #accumulation-type280166 -Node: Valuation type281094 -Ref: #valuation-type281282 -Node: Combining balance report types282349 -Ref: #combining-balance-report-types282543 -Node: Budget report284447 -Ref: #budget-report284599 -Node: Budget report start date290333 -Ref: #budget-report-start-date290511 -Node: Budgets and subaccounts291873 -Ref: #budgets-and-subaccounts292080 -Node: Selecting budget goals295566 -Ref: #selecting-budget-goals295765 -Node: Budget vs forecast296812 -Ref: #budget-vs-forecast296971 -Node: Data layout298671 -Ref: #data-layout298821 -Node: Useful balance reports306762 -Ref: #useful-balance-reports306912 -Node: balancesheet308065 -Ref: #balancesheet308210 -Node: balancesheetequity309576 -Ref: #balancesheetequity309734 -Node: cashflow311177 -Ref: #cashflow311308 -Node: check312794 -Ref: #check312908 -Node: Basic checks313714 -Ref: #basic-checks313834 -Node: Strict checks314372 -Ref: #strict-checks314515 -Node: Other checks314956 -Ref: #other-checks315098 -Node: Custom checks315675 -Ref: #custom-checks315832 -Node: More about specific checks316253 -Ref: #more-about-specific-checks316415 -Node: close317147 -Ref: #close317258 -Node: close and costs319896 -Ref: #close-and-costs320040 -Node: close and balance assertions320329 -Ref: #close-and-balance-assertions320531 -Node: Example retain earnings321702 -Ref: #example-retain-earnings321919 -Node: Example migrate balances to a new file322277 -Ref: #example-migrate-balances-to-a-new-file322542 -Node: Example excluding closing/opening transactions323095 -Ref: #example-excluding-closingopening-transactions323344 -Node: codes324522 -Ref: #codes324639 -Node: commodities325515 -Ref: #commodities325651 -Node: descriptions325721 -Ref: #descriptions325858 -Node: diff326149 -Ref: #diff326264 -Node: files327310 -Ref: #files327419 -Node: help327560 -Ref: #help-1327669 -Node: import328659 -Ref: #import328782 -Node: Deduplication329890 -Ref: #deduplication330015 -Node: Import testing331937 -Ref: #import-testing332102 -Node: Importing balance assignments332953 -Ref: #importing-balance-assignments333159 -Node: Commodity display styles333816 -Ref: #commodity-display-styles333989 -Node: incomestatement334118 -Ref: #incomestatement334260 -Node: notes335627 -Ref: #notes335749 -Node: payees336111 -Ref: #payees336226 -Node: prices336751 -Ref: #prices336866 -Node: print337168 -Ref: #print337283 -Node: register342729 -Ref: #register342851 -Node: Custom register output347960 -Ref: #custom-register-output348091 -Node: rewrite349466 -Ref: #rewrite349584 -Node: Re-write rules in a file351496 -Ref: #re-write-rules-in-a-file351659 -Node: Diff output format352812 -Ref: #diff-output-format352995 -Node: rewrite vs print --auto354107 -Ref: #rewrite-vs.-print---auto354269 -Node: roi354843 -Ref: #roi354950 -Node: Spaces and special characters in --inv and --pnl356711 -Ref: #spaces-and-special-characters-in---inv-and---pnl356959 -Node: Semantics of --inv and --pnl357457 -Ref: #semantics-of---inv-and---pnl357704 -Node: IRR and TWR explained359582 -Ref: #irr-and-twr-explained359742 -Node: stats362854 -Ref: #stats362962 -Node: tags364359 -Ref: #tags-1364466 -Node: test365483 -Ref: #test365576 -Node: PART 5 COMMON TASKS366326 -Ref: #part-5-common-tasks366459 -Node: Getting help366733 -Ref: #getting-help366874 -Node: Constructing command lines367638 -Ref: #constructing-command-lines367839 -Node: Starting a journal file368520 -Ref: #starting-a-journal-file368727 -Node: Setting opening balances369925 -Ref: #setting-opening-balances370130 -Node: Recording transactions373283 -Ref: #recording-transactions373472 -Node: Reconciling374028 -Ref: #reconciling374180 -Node: Reporting376493 -Ref: #reporting376642 -Node: Migrating to a new file380631 -Ref: #migrating-to-a-new-file380788 + This manual is for hledger’s command line interface, version 1.29.1. +It also describes the common options, file formats and concepts used by +all hledger programs. It might accidentally teach you some +bookkeeping/accounting as well! You don’t need to know everything in +here to use hledger productively, but when you have a question about +functionality, this doc should answer it. It is detailed, so do skip +ahead or skim when needed. You can read it on hledger.org, or as an +info manual or man page on your system. You can also get it from +hledger itself with +‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’. + + The main function of the hledger CLI is to read plain text files +describing financial transactions, crunch the numbers, and print a +useful report on the terminal (or save it as HTML, CSV, JSON or SQL). +Many reports are available, as subcommands. hledger will also detect +other ‘hledger-*’ executables as extra subcommands. + + hledger reads data from one or more files in journal, timeclock, +timedot, or CSV format. The default file is ‘.hledger.journal’ in your +home directory; this can be overridden with one or more ‘-f FILE’ +options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can +also read from stdin with ‘-f-’; more on that below. + + Here is a small but valid hledger journal file describing one +transaction: + +2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more +_accounts_: bank accounts, your wallet, revenue/expense categories, +people, etc. You can choose any account names you wish, using ‘:’ to +indicate subaccounts. There must be at least two spaces between account +name and amount. Positive amounts are inflow to that account (_debit_), +negatives are outflow from it (_credit_). (Some reports show revenue, +liability and equity account balances as negative numbers as a result; +this is normal.) + + hledger’s add command can help you add transactions, or you can +install other data entry UIs like hledger-web or hledger-iadd. For more +extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM ++ vim-ledger, or VS Code + hledger-vscode are some good choices (see +https://hledger.org/editors.html). + + To get started, run ‘hledger add’ and follow the prompts, or save +some entries like the above in ‘$HOME/.hledger.journal’, then try +commands like: +‘hledger print -x’ +‘hledger aregister assets’ +‘hledger balance’ +‘hledger balancesheet’ +‘hledger incomestatement’. +Run ‘hledger’ to list the commands. See also the "Starting a journal +file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +* Menu: + +* PART 1 USER INTERFACE:: +* Options:: +* Environment:: +* Input:: +* Commands:: +* Output:: +* Limitations:: +* Troubleshooting:: +* PART 2 DATA FORMATS:: +* Journal:: +* CSV:: +* Timeclock:: +* Timedot:: +* PART 3 REPORTING CONCEPTS:: +* Time periods:: +* Depth:: +* Queries:: +* Pivoting:: +* Generating data:: +* Forecasting:: +* Budgeting:: +* Cost reporting:: +* Valuation:: +* PART 4 COMMANDS:: +* PART 5 COMMON TASKS:: + + +File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top + +1 PART 1: USER INTERFACE +************************ + + +File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top + +2 Options +********* + +* Menu: + +* General options:: +* Command options:: +* Command arguments:: +* Special characters:: +* Unicode characters:: +* 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 or COMMAND help +‘--man’ + + show general or COMMAND user manual with man +‘--info’ + + show general or COMMAND user manual with info +‘--version’ + + show general or ADDONCMD version +‘--debug[=N]’ + + show debug output (levels 1-9, default: 1) + + General input options: + +‘-f FILE --file=FILE’ + + use a different input file. For stdin, use - (default: + ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’) +‘--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’ + + disable balance assertion checks (note: does not disable balance + assignments) +‘-s --strict’ + + do extra error checking (check that all posted accounts are + declared) + + General reporting options: + +‘-b --begin=DATE’ + + include postings/txns on or after this date (will be adjusted to + preceding subperiod start when using a report interval) +‘-e --end=DATE’ + + include postings/txns before this date (will be adjusted to + following subperiod end when using a report interval) +‘-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 +‘--date2’ + + match the secondary date instead (see command help for other + effects) +‘--today=DATE’ + + override today’s date (affects relative smart dates, for + tests/examples) +‘-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/selling amount at transaction time +‘-V --market’ + + convert amounts to their market value in default valuation + commodities +‘-X --exchange=COMM’ + + convert amounts to their market value in commodity COMM +‘--value’ + + convert amounts to cost or market value, more flexibly than + -B/-V/-X +‘--infer-market-prices’ + + use transaction prices (recorded with @ or @@) as additional market + prices, as if they were P directives +‘--auto’ + + apply automated posting rules to modify transactions. +‘--forecast’ + + generate future transactions from periodic transaction rules, for + the next 6 months or till report end date. In hledger-ui, also + make ordinary future transactions visible. +‘--commodity-style’ + + Override the commodity style in the output for the specified + commodity. For example ’EUR1.000,00’. +‘--color=WHEN (or --colour=WHEN)’ + + Should color-supporting commands use ANSI color codes in text + output. ’auto’ (default): whenever stdout seems to be a + color-supporting terminal. ’always’ or ’yes’: always, useful eg + when piping output into ’less -R’. ’never’ or ’no’: never. A + NO_COLOR environment variable overrides this. +‘--pretty[=WHEN]’ + + Show prettier output, e.g. using unicode box-drawing characters. + Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’ + also work). If you provide an argument you must use ’=’, e.g. + ’–pretty=yes’. + + When a reporting option appears more than once in the command line, +the 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 add-on, you may need to put its +options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can +run the add-on executable directly: ‘hledger-ui --watch’. + + +File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options + +2.3 Command arguments +===================== + +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. + + You can save a set of command line options/arguments in a file, and +then reuse them by writing ‘@FILENAME’ as a command line argument. Eg: +‘hledger bal @foo.args’. (To prevent this, eg if you have an argument +that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal +-- @ARG’). + + Inside the argument file, each line should contain just one option or +argument. Avoid the use of spaces, except inside quotes (or you’ll see +a confusing error). Between a flag and its argument, use = (or +nothing). Bad: + +assets depth:2 +-X USD + + Good: + +assets +depth:2 +-X=USD + + For special characters (see below), use one less level of quoting +than you would at the command prompt. Bad: + +-X"$" + + Good: + +-X$ + + See also: Save frequently used options. + + +File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options + +2.4 Special characters +====================== + +* Menu: + +* Single escaping shell metacharacters:: +* Double escaping regular expression metacharacters:: +* Triple escaping for add-on commands:: +* Less escaping:: + + +File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters + +2.4.1 Single escaping (shell metacharacters) +-------------------------------------------- + +In shell command lines, characters significant to your shell - such as +spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped" +if you want hledger to see them. This is done by enclosing them in +single or double quotes, or by writing a backslash before them. Eg to +match an account name containing a space: + +$ hledger register 'credit card' + + or: + +$ hledger register credit\ card + + Windows users should keep in mind that ‘cmd’ treats single quote as a +regular character, so you should be using double quotes exclusively. +PowerShell treats both single and double quotes as quotes. + + +File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters + +2.4.2 Double escaping (regular expression metacharacters) +--------------------------------------------------------- + +Characters significant in regular expressions (described below) - such +as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be +"regex-escaped" if you don’t want them to be interpreted by hledger’s +regular expression engine. This is done by writing backslashes before +them, but since backslash is typically also a shell metacharacter, both +shell-escaping and regex-escaping will be needed. Eg to match a literal +‘$’ sign while using the bash shell: + +$ hledger balance cur:'\$' + + or: + +$ hledger balance cur:\\$ + + +File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters + +2.4.3 Triple escaping (for add-on commands) +------------------------------------------- + +When you use hledger to run an external add-on command (described +below), one level of shell-escaping is lost from any options or +arguments intended for by the add-on command, so those need an extra +level of shell-escaping. Eg to match a literal ‘$’ sign while using the +bash shell and running an add-on command (‘ui’): + +$ hledger ui cur:'\\$' + + or: + +$ hledger ui cur:\\\\$ + + If you wondered why _four_ backslashes, perhaps this helps: + +unescaped: ‘$’ +escaped: ‘\$’ +double-escaped: ‘\\$’ +triple-escaped: ‘\\\\$’ + + Or, you can avoid the extra escaping by running the add-on executable +directly: + +$ hledger-ui cur:\\$ + + +File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters + +2.4.4 Less escaping +------------------- + +Options and arguments are sometimes used in places other than the shell +command line, where shell-escaping is not needed, so there you should +use one less level of escaping. Those places include: + + • an @argumentfile + • hledger-ui’s filter field + • hledger-web’s search form + • GHCI’s prompt (used by developers). + + +File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options + +2.5 Unicode characters +====================== + +hledger is expected to handle non-ascii characters correctly: + + • they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web’s + search/add/edit forms, etc.) + + • they should be displayed correctly by all hledger tools, and + on-screen alignment should be preserved. + + This requires a well-configured environment. Here are some tips: + + • A system locale must be configured, and it must be one that can + decode the characters being used. In bash, you can set a locale + like this: ‘export LANG=en_US.UTF-8’. There are some more details + in Troubleshooting. This step is essential - without it, hledger + will quit on encountering a non-ascii character (as with all + GHC-compiled programs). + + • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode + + • the terminal must be using a font which includes the required + unicode glyphs + + • the terminal should be configured to display wide characters as + double width (for report alignment) + + • on Windows, for best results you should run hledger in the same + kind of environment in which it was built. Eg hledger built in the + standard CMD.EXE environment (like the binaries on our download + page) might show display problems when run in a cygwin or msys + terminal, and vice versa. (See eg #961). + + +File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options + +2.6 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 directive and ‘--alias’ option: ‘alias /REGEX/ = + REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’ + + hledger’s regular expressions come from the regex-tdfa library. If +they’re not doing what you expect, it’s important to know exactly what +they support: + + 1. they are case insensitive + 2. they are infix matching (they do not need to match the entire thing + being matched) + 3. they are POSIX ERE (extended regular expressions) + 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’) + 5. they do not support backreferences; if you write ‘\1’, it will + match the digit ‘1’. Except when doing text replacement, eg in + account aliases, where backreferences can be used in the + replacement string to reference capturing groups in the search + regexp. + 6. they do not support mode modifiers (‘(?s)’), character classes + (‘\w’, ‘\d’), or anything else not mentioned above. + + 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: Environment, Next: Input, Prev: Options, Up: Top + +3 Environment +************* + +*LEDGER_FILE* The journal file path when not specified with ‘-f’. + + On unix computers, the default value is: ‘~/.hledger.journal’. + + A more typical value is something like ‘~/finance/YYYY.journal’, +where ‘~/finance’ is a version-controlled finance directory and YYYY is +the current year. Or, ‘~/finance/current.journal’, where +current.journal is a symbolic link to YYYY.journal. + + The usual way to set this permanently is to add a command to one of +your shell’s startup files (eg ‘~/.profile’): + +export LEDGER_FILE=~/finance/current.journal` + + On some Mac computers, there is a more thorough way to set +environment variables, that will also affect applications started from +the GUI (eg, Emacs started from a dock icon): In +‘~/.MacOSX/environment.plist’, add an entry like: + +{ + "LEDGER_FILE" : "~/finance/current.journal" +} + + For this to take effect you might need to ‘killall Dock’, or reboot. + + On Windows computers, the default value is probably +‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a +command like this in a powershell window (let us know if you need to be +an Administrator, and if this persists across a reboot): + +> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" + + Or, change it in settings: see +https://www.java.com/en/download/help/path.html. + + *COLUMNS* The screen width used by the register command. Default: +the full terminal width. + + *NO_COLOR* If this variable exists with any value, hledger will not +use ANSI color codes in terminal output. This is overriden by the +–color/–colour option. + + +File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top + +4 Input +******* + +hledger reads transactions from one or more data files. The default +data file is ‘$HOME/.hledger.journal’ (or on Windows, something like +‘C:\Users\YOURNAME\.hledger.journal’). + + You can override this with the ‘$LEDGER_FILE’ environment variable: + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with one or more ‘-f/--file’ options: + +$ hledger -f /some/file -f another_file stats + + The file name ‘-’ means standard input: + +$ cat some.journal | hledger -f- + +* Menu: + +* Data formats:: +* Multiple files:: +* Strict mode:: + + +File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input + +4.1 Data formats +================ + +Usually the data file is in hledger’s journal format, but it can be in +any of the supported file formats, which currently are: + +Reader: Reads: Used for file + extensions: +-------------------------------------------------------------------------- +‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’ + journals, for transactions ‘.hledger’ ‘.ledger’ +‘timeclock’timeclock files, for precise time ‘.timeclock’ + logging +‘timedot’timedot files, for approximate time ‘.timedot’ + logging +‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’ + values, for data import + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions +shown above. If it can’t recognise the file extension, it assumes +‘journal’ format. So for non-journal files, it’s important to use a +recognised file extension, so as to either read successfully or to show +relevant error messages. + + You can also force a specific reader/format by prefixing the file +path with the format and a colon. Eg, to read a .dat file as csv +format: + +$ hledger -f csv:/some/csv-file.dat stats + + Or to read stdin (‘-’) as timeclock format: + +$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- + + +File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input + +4.2 Multiple files +================== + +You can specify multiple ‘-f’ options, to read multiple files as one big +journal. There are some limitations with this: + + • most directives do not affect sibling files + • balance assertions will not see any account balances from previous + files + + If you need either of those things, you can + + • use a single parent file which includes the others + • or concatenate the files into one before reading, eg: ‘cat + a.journal b.journal | hledger -f- CMD’. + + +File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input + +4.3 Strict mode +=============== + +hledger checks input files for valid data. By default, the most +important errors are detected, while still accepting easy journal files +without a lot of declarations: + + • Are the input files parseable, with valid syntax ? + • Are all transactions balanced ? + • Do all balance assertions pass ? + + With the ‘-s’/‘--strict’ flag, additional checks are performed: + + • Are all accounts posted to, declared with an ‘account’ directive ? + (Account error checking) + • Are all commodities declared with a ‘commodity’ directive ? + (Commodity error checking) + • Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks – the ones +listed above and some more. + + +File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top + +5 Commands +********** + +hledger provides a number of built-in subcommands (described below). +Most of these read your data without changing it, and display a report. +A few assist with data entry and management. + + Run ‘hledger’ with no arguments to list the commands available, and +‘hledger CMD’ to run a command. CMD can be the full command name, or +its standard abbreviation shown in the commands list, or any unambiguous +prefix of the name. Eg: ‘hledger bal’. + +* Menu: + +* Add-on commands:: + + +File: hledger.info, Node: Add-on commands, Up: Commands + +5.1 Add-on commands +=================== + +Add-on commands are extra subcommands provided by programs or scripts in +your PATH + + • whose name starts with ‘hledger-’ + • whose name ends with a recognised file extension: + ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’ + or none + • and (on unix, mac) which are executable by the current user. + + Addons can be written in any language, but haskell scripts or +programs have a big advantage: they can use hledger’s library code, for +command-line options, parsing and reporting. + + Several add-on commands are installed by the hledger-install script. +See https://hledger.org/scripts.html for more details. + + Note in a hledger command line, add-on command flags must have a +double dash (‘--’) preceding them. Eg you must write: + +$ hledger web -- --serve + + and not: + +$ hledger web --serve + + (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’). + + The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’. + + If you have any trouble with this, remember you can always run the +add-on program directly, eg: + +$ hledger-web --serve + + +File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top + +6 Output +******** + +* Menu: + +* Output destination:: +* Output format:: +* Commodity styles:: +* Colour:: +* Box-drawing:: +* Debug output:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: Output + +6.1 Output destination +====================== + +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: + +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the ‘-o/--output-file’ option, which does the same thing without +needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) + + +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output + +6.2 Output format +================= + +Some commands offer other kinds of output, not just text on the +terminal. Here are those commands and the formats currently supported: + +- txt csv html json sql +----------------------------------------------------------------------------- +aregister Y Y Y Y +balance Y _1_ Y _1_ Y _1,2_ Y +balancesheet Y _1_ Y _1_ Y _1_ Y +balancesheetequity Y _1_ Y _1_ Y _1_ Y +cashflow Y _1_ Y _1_ Y _1_ Y +incomestatement Y _1_ Y _1_ Y _1_ Y +print Y Y Y Y +register Y Y Y + + • _1 Also affected by the balance commands’ ‘--layout’ option._ + • _2 ‘balance’ does not support html output without a report interval + or with ‘--budget’._ + + The output format is selected by the ‘-O/--output-format=FMT’ option: + +$ hledger print -O csv # print CSV on stdout + + or by the filename extension of an output file specified with the +‘-o/--output-file=FILE.FMT’ option: + +$ hledger balancesheet -o foo.csv # write CSV to foo.csv + + The ‘-O’ option can be combined with ‘-o’ to override the file +extension, if needed: + +$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt + + Some notes about the various output formats: + +* Menu: + +* CSV output:: +* HTML output:: +* JSON output:: +* SQL output:: + + +File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format + +6.2.1 CSV output +---------------- + + • In CSV output, digit group marks (such as thousands separators) are + disabled automatically. + + +File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format + +6.2.2 HTML output +----------------- + + • HTML output can be styled by an optional ‘hledger.css’ file in the + same directory. + + +File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format + +6.2.3 JSON output +----------------- + + • This is not yet much used; real-world feedback is welcome. + + • Our JSON is rather large and verbose, since it is a faithful + representation of hledger’s internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + + • hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction + prices), and would break most JSON consumers. So in JSON, we show + quantities as simple Numbers with at most 10 decimal places. We + don’t limit the number of integer digits, but that part is under + your control. We hope this approach will not cause problems in + practice; if you find otherwise, please let us know. (Cf #1195) + + +File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format + +6.2.4 SQL output +---------------- + + • This is not yet much used; real-world feedback is welcome. + + • SQL output is expected to work with sqlite, MySQL and PostgreSQL + + • SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables + created via SQL output of hledger, you would probably want to + either clear tables of existing data (via ‘delete’ or ‘truncate’ + SQL statements) or drop tables completely as otherwise your + postings will be duped. + + +File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output + +6.3 Commodity styles +==================== + +When displaying amounts, hledger infers a standard display style for +each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a ‘-c/--commodity-style’ option +(except for cost amounts and amounts displayed by the ‘print’ command, +which are always displayed with all decimal digits). For example, the +following will force dollar amounts to be displayed as shown: + +$ hledger print -c '$1.000,0' + + This option can repeated to set the display style for multiple +commodities/currencies. Its argument is as described in the commodity +directive. + + +File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output + +6.4 Colour +========== + +In terminal output, some commands can produce colour when the terminal +supports it: + + • if the ‘--color/--colour’ option is given a value of ‘yes’ or + ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used; + • otherwise, if the ‘NO_COLOR’ environment variable is set, colour + will not be used; + • otherwise, colour will be used if the output (terminal or file) + supports it. + + +File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output + +6.5 Box-drawing +=============== + +In terminal output, you can enable unicode box-drawing characters to +render prettier tables: + + • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or + ‘no’ or ‘never’), unicode characters will (or will not) be used; + • otherwise, unicode characters will not be used. + + +File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output + +6.6 Debug output +================ + +We intend hledger to be relatively easy to troubleshoot, introspect and +develop. You can add ‘--debug[=N]’ to any hledger command line to see +additional debug output. N ranges from 1 (least output, the default) to +9 (maximum output). Typically you would start with 1 and increase until +you are seeing enough. Debug output goes to stderr, and is not affected +by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg: +‘2>&1’). It will be interleaved with normal output, which can help +reveal when parts of the code are evaluated. To capture debug output in +a log file instead, you can usually redirect stderr, eg: + +hledger bal --debug=3 2>hledger.log + + +File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top + +7 Limitations +************* + +The need to precede add-on 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. + + On Windows, non-ascii characters may not display correctly when +running a hledger built in CMD in MSYS/CYGWIN, or vice-versa. + + 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 hledger +and Ledger > Differences > journal format. + + On large data files, hledger is slower and uses more memory than +Ledger. + + +File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top + +8 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. + + *Getting errors like "Illegal byte sequence" or "Invalid or +incomplete multibyte or wide character" or "commitAndReleaseBuffer: +invalid argument (invalid character)"* +Programs compiled with GHC (hledger, haskell build tools, etc.) need to +have a UTF-8-aware locale configured in the environment, otherwise they +will fail with these kinds of errors when they encounter non-ascii +characters. + + To fix it, set the LANG environment variable to some locale which +supports UTF-8. The locale you choose must be installed on your system. + + Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux: + +$ file my.journal +my.journal: UTF-8 Unicode text # the file is UTF8-encoded +$ echo $LANG +C # LANG is set to the default locale, which does not support UTF8 +$ locale -a # which locales are installed ? +C +en_US.utf8 # here's a UTF8-aware one we can use +POSIX +$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command + + If available, ‘C.UTF-8’ will also work. If your preferred locale +isn’t listed by ‘locale -a’, you might need to install it. Eg on +Ubuntu/Debian: + +$ 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 + + Here’s how you could set it permanently, if you use a bash shell: + +$ echo "export LANG=en_US.utf8" >>~/.bash_profile +$ bash --login + + Exact spelling and capitalisation may be important. Note the +difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu) +allow variant spellings, but others (eg macos) require it to be exact: + +$ locale -a | grep -iE en_us.*utf +en_US.UTF-8 +$ LANG=en_US.UTF-8 hledger -f my.journal print + + +File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top + +9 PART 2: DATA FORMATS +********************** + + +File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top + +10 Journal +********** + +hledger’s default file format, representing a General Journal. Here’s a +cheatsheet/mini-tutorial, or you can skip ahead to About journal format. + +* Menu: + +* Journal cheatsheet:: +* About journal format:: +* Comments:: +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Transaction comments:: +* Postings:: +* Account names:: +* Amounts:: +* Costs:: +* Balance assertions:: +* Posting comments:: +* Tags:: +* Directives:: +* account directive:: +* alias directive:: +* commodity directive:: +* decimal-mark directive:: +* include directive:: +* P directive:: +* payee directive:: +* tag directive:: +* Periodic transactions:: +* Other syntax:: + + +File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal + +10.1 Journal cheatsheet +======================= + +# Here is the main syntax of hledger's journal format +# (omitting extra Ledger compatibility syntax). +# hledger journals contain comments, directives, and transactions, in any order: + +############################################################################### +# 1. Comment lines are for notes or temporarily disabling things. +# They begin with #, ;, or a line containing the word "comment". + +# hash comment line +; semicolon comment line +comment +These lines +are commented. +end comment + +# Some but not all hledger entries can have same-line comments attached to them, +# from ; (semicolon) to end of line. + +############################################################################### +# 2. Directives modify parsing or reports in some way. +# They begin with a word or letter (or symbol). + +account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. +account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) +alias chkg = assets:checking +commodity $0.00 +decimal-mark . +include /dev/null +payee Whole Foods +P 2022-01-01 AAAA $1.40 +~ monthly budget goals ; <- 2+ spaces between period expression and description + expenses:food $400 + expenses:home $1000 + budgeted + +############################################################################### +# 3. Transactions are what it's all about; they are dated events, +# usually describing movements of money. +# They begin with a date. + +# DATE DESCRIPTION ; This is a transaction comment. +# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. +# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. +# ; ^^ At least 2 spaces between account and amount. +# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). + +2022-01-01 opening balances are declared this way + assets:checking $1000 ; Account names can be anything. lower case is easy to type. + assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. + assets:cash:wallet $100 ; : indicates subaccounts. + liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. + equity ; One amount can be left blank; $-1900 is inferred here. + +2022-04-15 * (#12345) pay taxes + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a transaction code (text in parentheses) after the date/status. + ; Amounts' sign represents direction of flow, or credit/debit: + assets:checking $-500 ; minus means removed from this account (credit) + expenses:tax:us:2021 $500 ; plus means added to this account (debit) + ; revenue/expense categories are also "accounts" + +Kv +2022-01-01 ; The description is optional. + ; Any currency/commodity symbols are allowed, on either side. + assets:cash:wallet GBP -10 + expenses:clothing GBP 10 + assets:gringotts -10 gold + assets:pouch 10 gold + revenues:gifts -2 "Liquorice Wands" ; Complex symbols + assets:bag 2 "Liquorice Wands" ; must be double-quoted. + +2022-01-01 Cost in another commodity can be noted with @ or @@ + assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments 3.0 AAAA @@ $4 ; @@ means total cost + assets:checking $-7.00 + +2022-01-02 assert balances + ; Balances can be asserted for extra error checking, in any transaction. + assets:investments 0 AAAA = 5.0 AAAA + assets:pouch 0 gold = 10 gold + assets:savings $0 = $1000 + +1999-12-31 Ordering transactions by date is recommended but not required. + ; Postings are not required. + +2022.01.01 These date +2022/1/1 formats are +12/31 also allowed (but consistent YYYY-MM-DD is recommended). + + +File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal + +10.2 About journal format +========================= + +hledger’s usual data source is a plain text file containing journal +entries in hledger journal format. This file represents a standard +accounting general journal. I use file names ending in ‘.journal’, but +that’s not required. The journal file contains a number of transaction +entries, each describing a transfer of money (or any commodity) between +two or more named accounts, in a simple format readable by both hledger +and humans. + + hledger’s journal format is a compatible subset, mostly, of ledger’s +journal format, so hledger can work with compatible ledger journal files +as well. It’s safe, and encouraged, to run both hledger and ledger on +the same journal file, eg to validate the results you’re getting. + + You can use hledger without learning any more about this file; just +use the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and +track changes with a version control system such as git. Editor addons +such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and +hledger-vscode for Visual Studio Code, make this easier, adding colour, +formatting, tab completion, and useful commands. See Editor +configuration at hledger.org for the full list. + + Here’s a description of each part of the file format (and hledger’s +data model). + + A hledger journal file can contain three kinds of thing: file +comments, transactions, and/or directives (counting periodic transaction +rules and auto posting rules as directives). + + +File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal + +10.3 Comments +============= + +Lines in the journal will be ignored if they begin with a hash (‘#’) or +a semicolon (‘;’). (See also Other syntax.) hledger will also ignore +regions beginning with a ‘comment’ line and ending with an ‘end comment’ +line (or file end). Here’s a suggestion for choosing between them: + + • ‘#’ for top-level notes + • ‘;’ for commenting out things temporarily + • ‘comment’ for quickly commenting large regions (remember it’s + there, or you might get confused) + + Eg: + +# a comment line +; another commentline +comment +A multi-line comment block, +continuing until "end comment" directive +or the end of the current file. +end comment + + Some hledger entries can have same-line comments attached to them, +from ; (semicolon) to end of line. See Transaction comments, Posting +comments, and Account comments below. + + +File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal + +10.4 Transactions +================= + +Transactions are the main unit of information in a journal file. They +represent events, typically a movement of some quantity of commodities +between two or more named accounts. + + Each transaction is recorded as a journal entry, beginning with a +simple date in column 0. This can be followed by any of the following +optional fields, separated by spaces: + + • a status character (empty, ‘!’, or ‘*’) + • a code (any short number or text, enclosed in parentheses) + • a description (any remaining text until end of line or a semicolon) + • a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + • 0 or more indented _posting_ lines, describing what was transferred + and the accounts involved (indented comment lines are also allowed, + but not blank lines or non-indented lines). + + Here’s a simple journal file containing one transaction: + +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + +File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal + +10.5 Dates +========== + +* Menu: + +* Simple dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates + +10.5.1 Simple dates +------------------- + +Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or +‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may +be omitted, in which case it will be inferred from the context: the +current transaction, the default year set with a ‘Y’ directive, or the +current date when the command is run. Some examples: ‘2010-01-31’, +‘2010/01/31’, ‘2010.1.31’, ‘1/31’. + + (The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.) + + +File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates + +10.5.2 Posting dates +-------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like ‘date:DATE’. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction’s date. +The ‘date:’ tag must have a valid simple date value if it is present, eg +a ‘date:’ tag with no value is not allowed. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal + +10.6 Status +=========== + +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +‘!’ pending +‘*’ cleared + + When reporting, you can filter by status with the ‘-U/--unmarked’, +‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’, +and ‘status:*’ queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" +state is called "uncleared". As of hledger 1.3 we have renamed it to +unmarked for clarity. + + To replicate Ledger and old hledger’s behaviour of also matching +pending, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here’s one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use ‘-PC’ to see the current balance at +your bank, ‘-U’ to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal + +10.7 Code +========= + +After the status mark, but before the description, you can optionally +write a transaction "code", enclosed in parentheses. This is a good +place to record a check number, or some other important transaction id +or reference number. + + +File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal + +10.8 Description +================ + +A transaction’s description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +10.8.1 Payee and note +--------------------- + +You can optionally include a ‘|’ (pipe) character in descriptions to +subdivide the description into separate fields for payee/payer name on +the left (up to the first ‘|’) and an additional note field on the right +(after the first ‘|’). This may be worthwhile if you need to do more +precise querying and pivoting by payee or by note. + + +File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal + +10.9 Transaction comments +========================= + +Text following ‘;’, after a transaction description, and/or on indented +lines immediately below it, form comments for that transaction. They +are reproduced by ‘print’ but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal + +10.10 Postings +============== + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + • (optional) a status character (empty, ‘!’, or ‘*’), followed by a + space + • (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + • (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, one amount may be left blank; it will be inferred so as to +balance the transaction. + + Be sure to note the unusual two-space delimiter between account name +and amount. This makes it easy to write account names containing +spaces. But if you accidentally leave only one space (or tab) before +the amount, the amount will be considered part of the account name. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal + +10.11 Account names +=================== + +Accounts are the main way of categorising things in hledger. As in +Double Entry Bookkeeping, they can represent real world accounts (such +as a bank account), or more abstract categories such as "money borrowed +from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the +traditional accounting categories, which in english are ‘assets’, +‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these +referred to as A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts +into more detailed subaccounts, by writing a full colon between account +name parts. For example, from the account names ‘assets:bank:checking’ +and ‘expenses:food’, hledger will infer this hierarchy of five accounts: + +assets +assets:bank +assets:bank:checking +expenses +expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + +assets + bank + checking +expenses + food + + hledger reports can summarise the account tree to any depth, so you +can go as deep as you like with subcategories, but keeping your account +names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, +numbers, symbols, or single spaces. Note, when an account name and an +amount are written on the same line, they must be separated by *two or +more spaces* (or tabs). + + Parentheses or brackets enclosing the full account name indicate +virtual postings, described below. Parentheses or brackets internal to +the account name have no special meaning. + + Account names can be altered temporarily or permanently by account +aliases. + + +File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal + +10.12 Amounts +============= + +After the account name, there is usually an amount. (Important: between +account name and amount, there must be *two or more spaces*.) + + hledger’s amount format is flexible, supporting several international +formats. Here are some examples. Amounts have a number (the +"quantity"): + +1 + + ..and usually a currency symbol or commodity name (more on this +below), to the left or right of the quantity, with or without a +separating space: + +$1 +4000 AAPL +3 "green apples" + + Amounts can be preceded by a minus sign (or a plus sign, though plus +is the default), The sign can be written before or after a left-side +commodity symbol: + +-$1 +$-1 + + One or more spaces between the sign and the number are acceptable +when parsing (but they won’t be displayed in output): + ++ $1 +$- 1 + + Scientific E notation is allowed: + +1E-6 +EUR 1E3 + +* Menu: + +* Decimal marks digit group marks:: +* Commodity:: +* Directives influencing number parsing and display:: +* Commodity display style:: +* Rounding:: + + +File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts + +10.12.1 Decimal marks, digit group marks +---------------------------------------- + +A _decimal mark_ can be written as a period or a comma: + +1.23 +1,23456780000009 + + In the integer part of the quantity (left of the decimal mark), +groups of digits can optionally be separated by a _digit group mark_ - a +space, comma, or period (different from the decimal mark): + + $1,000,000.00 + EUR 2.000.000,00 +INR 9,99,99,999.00 + 1 000 000.9455 + + Note, a number containing a single digit group mark and no decimal +mark is ambiguous. Are these digit group marks or decimal marks ? + +1,000 +1.000 + + If you don’t tell it otherwise, hledger will assume both of the above +are decimal marks, parsing both numbers as 1. + + To prevent confusing parsing mistakes and undetected typos, +especially if your data contains digit group marks (eg, thousands +separators), we recommend explicitly declaring the decimal mark +character in each journal file, using a directive at the top of the +file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’ +directives will also work. These are described below. + + +File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts + +10.12.2 Commodity +----------------- + +Amounts in hledger have both a "quantity", which is a signed decimal +number, and a "commodity", which is a currency symbol, stock ticker, or +any word or phrase describing something you are tracking. + + If the commodity name contains non-letters (spaces, numbers, or +punctuation), you must always write it inside double quotes (‘"green +apples"’, ‘"ABC123"’). + + If you write just a bare number, that too will have a commodity, with +name ‘""’; we call that the "no-symbol commodity". + + Actually, hledger combines these single-commodity amounts into more +powerful multi-commodity amounts, which are what it works with most of +the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456 +TSLA’. In practice, you will only see multi-commodity amounts in +hledger’s output; you can’t write them directly in the journal file. + + (If you are writing scripts or working with hledger’s internals, +these are the ‘Amount’ and ‘MixedAmount’ types.) + + +File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts + +10.12.3 Directives influencing number parsing and display +--------------------------------------------------------- + +You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to +declare and control these things more explicitly and precisely. These +are described below, but here’s a quick example: + +# the decimal mark character used by all amounts in this file (all commodities) +decimal-mark . + +# display styles for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 + + +File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts + +10.12.4 Commodity display style +------------------------------- + +For the amounts in each commodity, hledger chooses a consistent display +style to use in most reports. (Exceptions: price amounts, and all +amounts displayed by the ‘print’ command, are displayed with all of +their decimal digits visible.) + + A commodity’s display style is inferred as follows. + + First, if a default commodity is declared with ‘D’, this commodity +and its style is applied to any no-symbol amounts in the journal. + + Then each commodity’s style is inferred from one of the following, in +order of preference: + + • The commodity directive for that commodity (including the no-symbol + commodity), if any. + • The amounts in that commodity seen in the journal’s transactions. + (Posting amounts only; prices and periodic or auto rules are + ignored, currently.) + • The built-in fallback style, which looks like this: ‘$1000.00’. + (Symbol on the left, period decimal mark, two decimal places.) + + A style is inferred from journal amounts as follows: + + • Use the general style (decimal mark, symbol placement) of the first + amount + • Use the first-seen digit group style (digit group mark, digit group + sizes), if any + • Use the maximum number of decimal places of all. + + Cost amounts don’t affect the commodity display style directly, but +occasionally they can do so indirectly (eg when a posting’s amount is +inferred using a cost). If you find this causing problems, use a +commodity directive to fix the display style. + + To summarise: each commodity’s amounts will be normalised to (a) the +style declared by a ‘commodity’ directive, or (b) the style of the first +posting amount in the journal, with the first-seen digit group style and +the maximum-seen number of decimal places. So if your reports are +showing amounts in a way you don’t like, eg with too many decimal +places, use a commodity directive. Some examples: + +# declare euro, dollar, bitcoin and no-symbol commodities and set their +# input number formats and output display styles: +commodity EUR 1.000, +commodity $1000.00 +commodity 1000.00000000 BTC +commodity 1 000. + + The inferred commodity style can be overridden by supplying a command +line option. + + +File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts + +10.12.5 Rounding +---------------- + +Amounts are stored internally as decimal numbers with up to 255 decimal +places, and displayed with the number of decimal places specified by the +commodity display style. Note, hledger uses banker’s rounding: it +rounds to the nearest even number, eg 0.5 displayed with zero decimal +places is "0"). + + +File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal + +10.13 Costs +=========== + +After a posting amount, you can note its cost (when buying) or selling +price (when selling) in another commodity, by writing either ‘@ +UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion +transaction, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, +discussions, or code; that term was directionally neutral and reminded +that it is a price specific to a transaction, but we now just call it +"cost", with the understanding that the transaction could be a purchase +or a sale.) + + Costs are usually written explicitly with ‘@’ or ‘@@’, but can also +be inferred automatically for simple multi-commodity transactions. +Note, if costs are inferred, the order of postings is significant; the +first posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign +currency in hledger, using the cost notation either explicitly or +implicitly: + + 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction. + Note the effect of posting order: the price is added to first + posting, making it ‘€100 @@ $135’, as in example 2: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the ‘-B/--cost’ +flag; this is discussed more in the ˜COST REPORTING section. + +* Menu: + +* Other cost/lot notations:: + + +File: hledger.info, Node: Other cost/lot notations, Up: Costs + +10.13.1 Other cost/lot notations +-------------------------------- + +A slight digression for Ledger and Beancount users. Ledger has a number +of cost/lot-related notations: + + • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ + • expresses a conversion rate, as in hledger + • when buying, also creates a lot than can be selected at + selling time + + • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost) + • like the above, but also means "this cost was exceptional, + don’t use it when inferring market prices". + + Currently, hledger treats the above like ‘@’ and ‘@@’; the +parentheses are ignored. + + • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price) + • when buying, means "this cost is also the fixed price, don’t + let it fluctuate in value reports" + + • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price) + • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’, + also creates a lot + • when selling, combined with ‘@ ...’, specifies an investment + lot by its cost basis; does not check if that lot is present + + • and related: ‘[YYYY/MM/DD]’ (lot date) + • when buying, attaches this acquisition date to the lot + • when selling, selects a lot by its acquisition date + + • ‘(SOME TEXT)’ (lot note) + • when buying, attaches this note to the lot + • when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after +the posting amount, but ignores them. (This can break transaction +balancing.) + + For Beancount users, the notation and behaviour is different: + + • ‘@ UNITCOST’ and ‘@@ TOTALCOST’ + • expresses a cost without creating a lot, as in hledger + • when buying (augmenting) or selling (reducing) a lot, combined + with ‘{...}’: documents the cost/selling price (not used for + transaction balancing) + + • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ + • when buying (augmenting), expresses the cost for transaction + balancing, and also creates a lot with this cost basis + attached + • when selling (reducing), + • selects a lot by its cost basis + • raises an error if that lot is not present or can not be + selected unambiguously (depending on booking method + configured) + • expresses the selling price for transaction balancing + + Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation +but ignores it. + + • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST, + "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc. + + Currently, hledger rejects these. + + +File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal + +10.14 Balance assertions +======================== + +hledger supports Ledger-style balance assertions in journal files. +These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s +amount. Eg here we assert the expected dollar balance in accounts a and +b after each posting: + +2013/1/1 + a $1 =$1 + b =$-1 + +2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the ‘-I/--ignore-assertions’ flag, which can be useful for +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, described below). + +* Menu: + +* Assertions and ordering:: +* Assertions and multiple included files:: +* Assertions and multiple -f files:: +* Assertions and commodities:: +* Assertions and prices:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: +* Assertions and auto postings:: +* Assertions and precision:: + + +File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions + +10.14.1 Assertions and ordering +------------------------------- + +hledger sorts an account’s postings and assertions first by date and +then (for postings on the same day) by parse order. Note this is +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder +differently-dated transactions within the journal. But if you reorder +same-dated transactions or postings, assertions might break and require +updating. This order dependence does bring an advantage: precise +control over the order of postings and assertions within a day, so you +can assert intra-day balances. + + +File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions + +10.14.2 Assertions and multiple included files +---------------------------------------------- + +Multiple files included with the ‘include’ directive are processed as if +concatenated into one file, preserving their order and the posting order +within each file. It means that balance assertions in later files will +see balance from earlier files. + + And if you have multiple postings to an account on the same day, +split across multiple files, and you want to assert the account’s +balance on that day, you’ll need to put the assertion in the right file +- the last one in the sequence, probably. + + +File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions + +10.14.3 Assertions and multiple -f files +---------------------------------------- + +Unlike ‘include’, when multiple files are specified on the command line +with multiple ‘-f/--file’ options, balance assertions will not see +balance from earlier files. This can be useful when you do not want +problems in earlier files to disrupt valid assertions in later files. + + If you do want assertions to see balance from earlier files, use +‘include’, or concatenate the files temporarily. + + +File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions + +10.14.4 Assertions and commodities +---------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity’s balance within the +(possibly multi-commodity) account balance. This is how assertions work +in Ledger also. We could call this a "partial" balance assertion. + + To assert the balance of more than one commodity in an account, you +can write multiple postings, each asserting one commodity’s balance. + + You can make a stronger "total" balance assertion by writing a double +equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no +other commodities in the account besides the asserted one (or at least, +that their balance is 0). + +2013/1/1 + a $1 + a 1€ + b $-1 + c -1€ + +2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1€ + b 0 == $-1 + c 0 == -1€ + +2013/1/3 ; This assertion fails as 'a' also contains 1€ + a 0 == $1 + + It’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: + +2013/1/1 + a:usd $1 + a:euro 1€ + b + +2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1€ + + +File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions + +10.14.5 Assertions and prices +----------------------------- + +Balance assertions ignore costs, 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.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions + +10.14.6 Assertions and subaccounts +---------------------------------- + +The balance assertions above (‘=’ and ‘==’) do not count the balance +from subaccounts; they check the account’s exclusive balance only. You +can assert the balance including subaccounts by writing ‘=*’ or ‘==*’, +eg: + +2019/1/1 + equity:opening balances + checking:a 5 + checking:b 5 + checking 1 ==* 11 + + +File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions + +10.14.7 Assertions and virtual postings +--------------------------------------- + +Balance assertions always consider both real and virtual postings; they +are not affected by the ‘--real/-R’ flag or ‘real:’ query. + + +File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions + +10.14.8 Assertions and auto postings +------------------------------------ + +Balance assertions _are_ affected by the ‘--auto’ flag, which generates +auto postings, which can alter account balances. Because auto postings +are optional in hledger, accounts affected by them effectively have two +balances. But balance assertions can only test one or the other of +these. So to avoid making fragile assertions, either: + + • assert the balance calculated with ‘--auto’, and always use + ‘--auto’ with that file + • or assert the balance calculated without ‘--auto’, and never use + ‘--auto’ with that file + • or avoid balance assertions on accounts affected by auto postings + (or avoid auto postings entirely). + + +File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions + +10.14.9 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.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal + +10.15 Posting comments +====================== + +Text following ‘;’, at the end of a posting line, and/or on indented +lines immediately below it, form comments for that posting. They are +reproduced by ‘print’ but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + +File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal + +10.16 Tags +========== + +Tags are a way to add extra labels or labelled data to transactions, +postings, or accounts, which you can then search or pivot on. + + They are written as a word (optionally hyphenated) immediately +followed by a full colon, in a transaction or posting or account +directive’s comment. (This is an exception to the usual rule that +things in comments are ignored.) Eg, here four different tags are +recorded: one on the checking account, two on the transaction, and one +on the expenses posting: + +account assets:checking ; accounttag: + +2017/1/16 bought groceries ; transactiontag-1: + ; transactiontag-2: + assets:checking $-1 + expenses:food $1 ; postingtag: + + Postings also inherit tags from their transaction and their account. +And transactions also acquire tags from their postings (and postings’ +accounts). So in the example above, the expenses posting effectively +has all four tags (by inheriting from account and transaction), and the +transaction also has all four tags (by acquiring from the expenses +posting). + + You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by +tag name with a ‘tag:NAMEREGEX’ query. + +* Menu: + +* Tag values:: + + +File: hledger.info, Node: Tag values, Up: Tags + +10.16.1 Tag values +------------------ + +Tags can have a value, which is any text after the colon up until a +comma or end of line (with surrounding whitespace removed). Note this +means that hledger tag values can not contain commas. Eg in the +following posting, the three tags’ values are "value 1", "value 2", and +"" (empty) respectively: + + expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz + + Note that tags can be repeated, and are additive rather than +overriding: when the same tag name is seen again with a new value, the +new name:value pair is added to the tags. (It is not possible to +override a tag’s value or remove a tag.) + + You can list a tag’s values with ‘hledger tags TAGNAME --values’, or +match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query. + + +File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal + +10.17 Directives +================ + +A directive is a line in the journal beginning with a special keyword, +that influences how the journal is processed, how things are displayed, +and so on. hledger’s directives are based on (a subset of) Ledger’s, +but there are many differences, and also some differences between +hledger versions. Here are some more definitions: + + • _subdirective_ - Some directives support subdirectives, written + indented below the parent directive. + + • _decimal mark_ - The character to interpret as a decimal mark + (period or comma) when parsing amounts of a commodity. + + • _display style_ - How to display amounts of a commodity in output: + symbol side and spacing, digit groups, decimal mark, and number of + decimal places. + + Directives are not required when starting out with hledger, but you +will probably want to add some as your needs grow. Here some key +directives for particular needs: + +purpose directives +-------------------------------------------------------------------------- +*READING DATA:* +Declare file’s decimal mark to help parse ‘decimal-mark’ +amounts accurately +Rewrite account names ‘alias’ +Comment out sections of the data ‘comment’ +Include extra data files ‘include’ +*GENERATING DATA:* +Generate recurring transactions or budget ‘~’ +goals +Generate extra postings on transactions ‘=’ +*CHECKING FOR ERRORS:* +Define valid entities to provide more ‘account’, ‘commodity’, +error checking ‘payee’ +*REPORTING:* +Declare accounts’ type and display order ‘account’ +Declare commodity display styles ‘commodity’ +Declare market prices ‘P’ + +* Menu: + +* Directive effects:: +* Directives and multiple files:: + + +File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives + +10.17.1 Directive effects +------------------------- + +And here is what each directive does, and which files and journal +entries (transactions) it affects: + +directivewhat it does ends + at + file + end? +--------------------------------------------------------------------------- +*‘account’*Declares an account, for checking all entries in all files; andN + its display order and type. Subdirectives: any text, ignored. +*‘alias’*Rewrites account names, in following entries until end of Y + current file or ‘end aliases’. Command line equivalent: + ‘--alias’ +*‘comment’*Ignores part of the journal file, until end of current file orY + ‘end comment’. +*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N + all amounts in all files 2. the decimal mark for parsing + amounts of this commodity, in the following entries until end of + current file (if there is no ‘decimal-mark’ directive) 3. and + the display style for amounts of this commodity 4. which is + also the precision to use for balanced-transaction checking in + this commodity. Takes precedence over ‘D’. Subdirectives: + ‘format’ (Ledger-compatible syntax). Command line equivalent: + ‘-c/--commodity-style’ +*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y + commodities in following entries until next ‘decimal-mark’ or + end of current file. Included files can override. Takes + precedence over ‘commodity’ and ‘D’. +*‘include’*Includes entries and directives from another file, as if theyN + were written inline. Command line alternative: multiple + ‘-f/--file’ +*‘payee’*Declares a payee name, for checking all entries in all files. N +*‘P’*Declares the market price of a commodity on some date, for value N + reports. +*‘~’*Declares a periodic transaction rule that generates future N +(tilde)transactions with ‘--forecast’ and budget goals with ‘balance + --budget’. +Other +syntax: +*‘applyPrepends a common parent account to all account names, in Y +account’*following entries until end of current file or ‘end apply + account’. +*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no ‘commodity’ directive for this commodity: its + decimal mark, balancing precision, and display style, as above. +*‘Y’*Sets a default year to use for any yearless dates, in following Y + entries until end of current file. +*‘=’*Declares an auto posting rule that generates extra postings on partly +(equals)matched transactions with ‘--auto’, in current, parent, and + child files (but not sibling files, see #1212). +*OtherOther directives from Ledger’s file format are accepted but +Ledgerignored. +directives* + + +File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives + +10.17.2 Directives and multiple files +------------------------------------- + +If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive, +hledger will process multiple input files. But directives which affect +input typically have effect only until the end of the file in which they +occur (and on any included files in that region). + + This may seem inconvenient, but it’s intentional; it makes reports +stable and deterministic, independent of the order of input. Otherwise +you could see different numbers if you happened to write -f options in a +different order, or if you moved includes around while cleaning up your +files. + + It can be surprising though; for example, it means that ‘alias’ +directives do not affect parent or sibling files (see below). + + +File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal + +10.18 ‘account’ directive +========================= + +‘account’ directives can be used to declare accounts (ie, the places +that amounts are transferred from and to). Though not required, these +declarations can provide several benefits: + + • They can document your intended chart of accounts, providing a + reference. + • In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + • They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + • They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + • They can store additional account information as comments, or as + tags which can be used to filter or pivot reports. + • They can help hledger know your accounts’ types (asset, liability, + equity, revenue, expense), affecting reports like balancesheet and + incomestatement. + + They are written as the word ‘account’ followed by a hledger-style +account name, eg: + +account assets:bank:checking + + Note, however, that accounts declared in account directives are not +allowed to have surrounding brackets and parentheses, unlike accounts +used in postings. So the following journal will not parse: + +account (assets:bank:checking) + +* Menu: + +* Account comments:: +* Account subdirectives:: +* Account error checking:: +* Account display order:: +* Account types:: + + +File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive + +10.18.1 Account comments +------------------------ + +Text following *two or more spaces* and ‘;’ at the end of an account +directive line, and/or following ‘;’ on indented lines immediately below +it, form comments for that account. They are ignored except they may +contain tags, which are not ignored. + + The two-space requirement for same-line account comments is because +‘;’ is allowed in account names. + +account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + +File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive + +10.18.2 Account subdirectives +----------------------------- + +Ledger-style indented subdirectives are also accepted, but currently +ignored: + +account assets:bank:checking + format subdirective is ignored + + +File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive + +10.18.3 Account error checking +------------------------------ + +By default, accounts need not be declared; they come into existence when +a posting references them. This is convenient, but it means hledger +can’t warn you when you mis-spell an account name in the journal. +Usually you’ll find that error later, as an extra account in balance +reports, or an incorrect balance when reconciling. + + In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will +report an error if any transaction uses an account name that has not +been declared by an account directive. Some notes: + + • The declaration is case-sensitive; transactions must use the + correct account name capitalisation. + • The account directive’s scope is "whole file and below" (see + directives). This means it affects all of the current file, and + any files it includes, but not parent or sibling files. The + position of account directives within the file does not matter, + though it’s usual to put them at the top. + • Accounts can only be declared in ‘journal’ files, but will affect + included files of all types. + • It’s currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + +File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive + +10.18.4 Account display order +----------------------------- + +The order in which account directives are written influences the order +in which accounts appear in reports, hledger-ui, hledger-web etc. By +default accounts appear in alphabetical order, but if you add these +account directives to the journal file: + +account assets +account liabilities +account equity +account revenues +account expenses + + those accounts will be displayed in declaration order: + +$ hledger accounts -1 +assets +liabilities +equity +revenues +expenses + + Any undeclared accounts are displayed last, in alphabetical order. + + 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 + • sibling accounts stay together (you couldn’t display ‘x:y’ in + between ‘a:b’ and ‘a:c’). + + +File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive + +10.18.5 Account types +--------------------- + +hledger knows that accounts come in several types: assets, liabilities, +expenses and so on. This enables easy reports like balancesheet and +incomestatement, and filtering by account type with the ‘type:’ query. + + As a convenience, hledger will detect these account types +automatically if you are using common english-language top-level account +names (described below). But generally we recommend you declare types +explicitly, by adding a ‘type:’ tag to your top-level account +directives. Subaccounts will inherit the type of their parent. The +tag’s value should be one of the five main account types: + + • ‘A’ or ‘Asset’ (things you own) + • ‘L’ or ‘Liability’ (things you owe) + • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of + assets & liabilities) + • ‘R’ or ‘Revenue’ (what you received money from, AKA income; + technically part of Equity) + • ‘X’ or ‘Expense’ (what you spend money on; technically part of + Equity) + + or, it can be (these are used less often): + + • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the + cashflow report) + • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST + REPORTING).) + + Here is a typical set of account type declarations: + +account assets ; type: A +account liabilities ; type: L +account equity ; type: E +account revenues ; type: R +account expenses ; type: X + +account assets:bank ; type: C +account assets:cash ; type: C + +account equity:conversion ; type: V + + Here are some tips for working with account types. + + • The rules for inferring types from account names are as follows. + These are just a convenience that sometimes help new users get + going; if they don’t work for you, just ignore them and declare + your account types. See also Regular expressions. + + If account's name contains this (CI) regular expression: | its type is: + --------------------------------------------------------------------|------------- + ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash + ^assets?(:|$) | Asset + ^(debts?|liabilit(y|ies))(:|$) | Liability + ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion + ^equity(:|$) | Equity + ^(income|revenue)s?(:|$) | Revenue + ^expenses?(:|$) | Expense + + • If you declare any account types, it’s a good idea to declare an + account for all of the account types, because a mixture of declared + and name-inferred types can disrupt certain reports. + + • Certain uses of account aliases can disrupt account types. See + Rewriting accounts > Aliases and account types. + + • As mentioned above, subaccounts will inherit a type from their + parent account. More precisely, an account’s type is decided by + the first of these that exists: + + 1. A ‘type:’ declaration for this account. + 2. A ‘type:’ declaration in the parent accounts above it, + preferring the nearest. + 3. An account type inferred from this account’s name. + 4. An account type inferred from a parent account’s name, + preferring the nearest parent. + 5. Otherwise, it will have no type. + + • For troubleshooting, you can list accounts and their types with: + + $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] + + +File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal + +10.19 ‘alias’ directive +======================= + +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. This can be useful for: + + • expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + • adapting old journals to your current chart of accounts + • experimenting with new account organisations, like a new hierarchy + • combining two accounts into one, eg to see their sum or difference + on one line + • customising reports + + Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger-web. + + Account aliases are very powerful. They are generally easy to use +correctly, but you can also generate invalid account names with them; +more on this below. + + See also Rewrite account names. + +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Combining aliases:: +* Aliases and multiple files:: +* end aliases directive:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive + +10.19.1 Basic aliases +--------------------- + +To set an account alias, use the ‘alias’ directive in your journal file. +This affects all subsequent journal entries in the current file or its +included files (but note: not sibling or parent files). The spaces +around the = are optional: + +alias OLD = NEW + + Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line. +This affects all entries. It’s useful for trying out aliases +interactively. + + OLD and NEW are case sensitive full account names. hledger will +replace any occurrence of the old account name with the new one. +Subaccounts are also affected. Eg: + +alias checking = assets:bank:wells fargo:checking +; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + +File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive + +10.19.2 Regex aliases +--------------------- + +There is also a more powerful variant that uses a regular expression, +indicated by wrapping the pattern in forward slashes. (This is the only +place where hledger requires forward slashes around a regular +expression.) + + Eg: + +alias /REGEX/ = REPLACEMENT + + or: + +$ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by +REPLACEMENT. REGEX is case-insensitive as usual. + + If you need to match a forward slash, escape it with a backslash, eg +‘/\/=:’. + + If REGEX contains parenthesised match groups, these can be referenced +by the usual backslash and number in REPLACEMENT: + +alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 +; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + REPLACEMENT continues to the end of line (or on command line, to end +of option argument), so it can contain trailing whitespace. + + +File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive + +10.19.3 Combining aliases +------------------------- + +You can define as many aliases as you like, using journal directives +and/or command line options. + + Recursive aliases - where an account name is rewritten by one alias, +then by another alias, and so on - are allowed. Each alias sees the +effect of previously applied aliases. + + In such cases it can be important to understand which aliases will be +applied and in which order. For (each account name in) each journal +entry, we apply: + + 1. ‘alias’ directives preceding the journal entry, most recently + parsed first (ie, reading upward from the journal entry, bottom to + top) + 2. ‘--alias’ options, in the order they appeared on the command line + (left to right). + + In other words, for (an account name in) a given journal entry: + + • the nearest alias declaration before/above the entry is applied + first + • the next alias before/above that will be be applied next, and so on + • aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps +provide semantic stability - aliases will keep working the same way +independent of which files are being read and in which order. + + In case of trouble, adding ‘--debug=6’ to the command line will show +which aliases are being applied when. + + +File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive + +10.19.4 Aliases and multiple files +---------------------------------- + +As explained at Directives and multiple files, ‘alias’ directives do not +affect parent or sibling files. Eg in this command, + +hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn’t work either: + +include a.aliases + +2020-01-01 ; not affected by a.aliases + foo 1 + bar + + This means that account aliases should usually be declared at the +start of your top-most file, like this: + +alias foo=Foo +alias bar=Bar + +2020-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected + + +File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive + +10.19.5 ‘end aliases’ directive +------------------------------- + +You can clear (forget) all currently defined aliases (seen in the +journal so far, or defined on the command line) with this directive: + +end aliases + + +File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive + +10.19.6 Aliases can generate bad account names +---------------------------------------------- + +Be aware that account aliases can produce malformed account names, which +could cause confusing reports or invalid ‘print’ output. For example, +you could erase all account names: + +2021-01-01 + a:aa 1 + b + +$ hledger print --alias '/.*/=' +2021-01-01 + 1 + + The above ‘print’ output is not a valid journal. Or you could insert +an illegal double space, causing ‘print’ output that would give a +different journal when reparsed: + +2021-01-01 + old 1 + other + +$ hledger print --alias old="new USD" | hledger -f- print +2021-01-01 + new USD 1 + other + + +File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive + +10.19.7 Aliases and account types +--------------------------------- + +If an account with a type declaration (see Declaring accounts > Account +types) is renamed by an alias, normally the account type remains in +effect. + + However, renaming in a way that reshapes the account tree (eg +renaming parent accounts but not their children, or vice versa) could +prevent child accounts from inheriting the account type of their +parents. + + Secondly, if an account’s type is being inferred from its name, +renaming it by an alias could prevent or alter that. + + If you are using account aliases and the ‘type:’ query is not +matching accounts as you expect, try troubleshooting with the accounts +command, eg something like: + +$ hledger accounts --alias assets=bassetts type:a + + +File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal + +10.20 ‘commodity’ directive +=========================== + +You can use ‘commodity’ directives to declare your commodities. In fact +the ‘commodity’ directive performs several functions at once: + + 1. It declares commodities which may be used in the journal. This can + optionally be enforced, providing useful error checking. (Cf + Commodity error checking) + + 2. It declares which decimal mark character (period or comma), to + expect when parsing input - useful to disambiguate international + number formats in your data. Without this, hledger will parse both + ‘1,000’ and ‘1.000’ as 1. (Cf Amounts) + + 3. It declares how to render the commodity’s amounts when displaying + output - the decimal mark, any digit group marks, the number of + decimal places, symbol placement and so on. (Cf Commodity display + style) + + You will run into one of the problems solved by commodity directives +sooner or later, so we recommend using them, for robust and predictable +parsing and display. + + Generally you should put them at the top of your journal file (since +for function 2, they affect only following amounts, cf #793). + + A commodity directive is just the word ‘commodity’ followed by a +sample amount, like this: + +;commodity SAMPLEAMOUNT + +commodity $1000.00 +commodity 1,000.0000 AAAA ; optional same-line comment + + It may also be written on multiple lines, and use the ‘format’ +subdirective, as in Ledger. Note in this case the commodity symbol +appears twice; it must be the same in both places: + +;commodity SYMBOL +; format SAMPLEAMOUNT + +; display indian rupees with currency name on the left, +; thousands, lakhs and crores comma-separated, +; period as decimal point, and two decimal places. +commodity INR + format INR 1,00,00,000.00 + + Other indented subdirectives are currently ignored. + + Remember that if the commodity symbol contains spaces, numbers, or +punctuation, it must be enclosed in double quotes (cf Commodity). + + The amount’s quantity does not matter; only the format is +significant. It must include a decimal mark - either a period or a +comma - followed by 0 or more decimal digits. + + A few more examples: + +# number formats for $, EUR, INR and the no-symbol commodity: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.0 +commodity 1 000 000. + + Note hledger normally uses banker’s rounding, so 0.5 displayed with +zero decimal digits is "0". (More at Commodity display style.) + + Even in the presence of commodity directives, the commodity display +style can still be overridden by supplying a command line option. + +* Menu: + +* Commodity error checking:: + + +File: hledger.info, Node: Commodity error checking, Up: commodity directive + +10.20.1 Commodity error checking +-------------------------------- + +In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will +report an error if a commodity symbol is used that has not been declared +by a ‘commodity’ directive. This works similarly to account error +checking, see the notes there for more details. + + Note, this disallows amounts without a commodity symbol, because +currently it’s not possible (?) to declare the "no-symbol" commodity +with a directive. This is one exception for convenience: zero amounts +are always allowed to have no commodity symbol. + + +File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal + +10.21 ‘decimal-mark’ directive +============================== + +You can use a ‘decimal-mark’ directive - usually one per file, at the +top of the file - to declare which character represents a decimal mark +when parsing amounts in this file. It can look like + +decimal-mark . + + or + +decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we +recommend it, especially if the file contains digit group marks (eg +thousands separators). + + +File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal + +10.22 ‘include’ directive +========================= + +You can pull in the content of additional files by writing an include +directive, like this: + +include FILEPATH + + Only journal files can include, and only journal, timeclock or +timedot files can be included (not CSV files, currently). + + If the file path does not begin with a slash, it is relative to the +current file’s folder. + + A tilde means home directory, eg: ‘include ~/main.journal’. + + The path may contain glob patterns to match multiple files, eg: +‘include *.journal’. + + There is limited support for recursive wildcards: ‘**/’ (the slash is +required) matches 0 or more subdirectories. It’s not super convenient +since you have to avoid include cycles and including directories, but +this can be done, eg: ‘include */**/*.journal’. + + The path may also be prefixed to force a specific file format, +overriding the file extension (as described in hledger.1 -> Input +files): ‘include timedot:~/notes/2020*.md’. + + +File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal + +10.23 ‘P’ directive +=================== + +The ‘P’ directive declares a market price, which is a conversion rate +between two commodities on a certain date. This allows value reports to +convert amounts of one commodity to their value in another, on or after +that date. These prices are often obtained from a stock exchange, +cryptocurrency exchange, the or foreign exchange market. + + The format is: + +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the +commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and +quantity) of commodity 2 that one unit of commodity 1 is worth on this +date. Examples: + +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 € $1.35 + +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 € $1.40 + + The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show +amount values in another commodity. See Valuation. + + +File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal + +10.24 ‘payee’ directive +======================= + +‘payee PAYEE NAME’ + + This directive can be used to declare a limited set of payees which +may appear in transaction descriptions. The "payees" check will report +an error if any transaction refers to a payee that has not been +declared. Eg: + +payee Whole Foods + + Any indented subdirectives are currently ignored. + + +File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal + +10.25 ‘tag’ directive +===================== + +‘tag TAGNAME’ + + This directive can be used to declare a limited set of tag names +allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + +tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is +used. It is quite easy to accidentally create a tag through normal use +of colons in comments(#comments]; if you want to prevent this, you can +declare and check your tags . + + +File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal + +10.26 Periodic transactions +=========================== + +The ‘~’ directive declares recurring transactions. Such directives +allow hledger to generate temporary future transactions (visible in +reports, not in the journal file) to help with forecasting or budgeting. + + Periodic transactions can be a little tricky, so before you use them, +read this whole section, or at least these tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + 2. For troubleshooting, show the generated transactions with ‘hledger + print --forecast tag:generated’ or ‘hledger register --forecast + tag:generated’. + 3. Forecasted transactions will begin only after the last + non-forecasted transaction’s date. + 4. Forecasted transactions will end 6 months from today, by default. + See below for the exact start/end rules. + 5. period expressions can be tricky. Their documentation needs + improvement, but is worth studying. + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in ‘weekly from DATE’, DATE + must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give + an error. + 7. Other period expressions with an interval are automatically + expanded to cover a whole number of that interval. (This is done + to improve reports, but it also affects periodic transactions. + Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th + day of month from 2020/01’, which is equivalent to ‘~ every 10th + day of month from 2020/01/01’, will be adjusted to start on + 2019/12/10. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +10.26.1 Periodic rule syntax +---------------------------- + +A periodic transaction rule looks like a normal journal entry, with the +date replaced by a tilde (‘~’) followed by a period expression +(mnemonic: ‘~’ looks like a recurring sine wave.): + +# every first of month +~ monthly + expenses:rent $2000 + assets:bank:checking + +# every 15th of month in 2023's first quarter: +~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying +multi-period reports, just interpreted differently; there, it specifies +report periods; here it specifies recurrence dates (the periods’ start +dates). + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +10.26.2 Periodic rules and relative dates +----------------------------------------- + +Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’, +‘next quarter’) are usually not recommended in periodic rules, since the +results will change as time passes. If used, they will be interpreted +relative to, in order of preference: + + 1. the first day of the default year specified by a recent ‘Y’ + directive + 2. or the date specified with ‘--today’ + 3. or the date on which you are running the report. + + They will not be affected at all by report period or forecast period +dates. + + +File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions + +10.26.3 Two spaces between period expression and description! +------------------------------------------------------------- + +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 + + So, + + • Do write two spaces between your period expression and your + transaction description, if any. + • Don’t accidentally write two spaces in the middle of your period + expression. + + +File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal + +10.27 Other syntax +================== + +hledger journal format supports quite a few other features, mainly to +make interoperating with or converting from Ledger easier. Note some of +the features below are powerful and can be useful in special cases, but +in general, features in this section are considered less important or +even not recommended for most users. Downsides are mentioned to help +you decide if you want to use them. + +* Menu: + +* Auto postings:: +* Balance assignments:: +* Bracketed posting dates:: +* D directive:: +* apply account directive:: +* Y directive:: +* Secondary dates:: +* Star comments:: +* Valuation expressions:: +* Virtual postings:: +* Other Ledger directives:: + + +File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax + +10.27.1 Auto postings +--------------------- + +The ‘=’ directive declares a rule for automatically adding temporary +extra postings (visible in reports, not in the journal file) to all +transactions matched by a certain query, when you use the ‘--auto’ flag. + + Downsides: depending on generated data for your reports makes your +financial data less portable, less future-proof, and less trustworthy in +an audit. Also, because the feature is optional, other features like +balance assertions can break depending on whether it is on or off. + + An auto posting rule looks a bit like a transaction: + += QUERY + ACCOUNT AMOUNT + ... + ACCOUNT [AMOUNT] + + except the first line is an equals sign (mnemonic: ‘=’ suggests +matching), followed by a query (which matches existing postings), and +each "posting" line describes a posting to be generated, and the posting +amounts can be: + + • a normal amount with a commodity symbol, eg ‘$2’. This will be + used as-is. + • a number, eg ‘2’. The commodity symbol (if any) from the matched + posting will be added to this. + • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The + matched posting’s amount (and total price, if any) will be + multiplied by N. + • a multiplier with a commodity symbol, eg ‘*$2’ (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. + + Any query term containing spaces must be enclosed in single or double +quotes, as on the command line. Eg, note the quotes around the second +query term below: + += expenses:groceries 'expenses:dining out' + (budget:funds:dining out) *-1 + + Some examples: + +; every time I buy food, schedule a dollar donation += expenses:food + (liabilities:charity) $-1 + +; when I buy a gift, also deduct that amount from a budget envelope subaccount += expenses:gifts + assets:checking:gifts *-1 + assets:checking *1 + +2017/12/1 + expenses:food $10 + assets:checking + +2017/12/14 + expenses:gifts $20 + assets:checking + +$ hledger print --auto +2017-12-01 + expenses:food $10 + assets:checking + (liabilities:charity) $-1 + +2017-12-14 + expenses:gifts $20 + assets:checking + assets:checking:gifts -$20 + assets:checking $20 + +* Menu: + +* Auto postings and multiple files:: +* Auto postings and dates:: +* Auto postings and transaction balancing / inferred amounts / balance assertions:: +* Auto posting tags:: + + +File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings + +10.27.1.1 Auto postings and multiple files +.......................................... + +An auto posting rule can affect any transaction in the current file, or +in any parent file or child file. Note, currently it will not affect +sibling files (when multiple ‘-f’/‘--file’ are used - see #1212). + + +File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings + +10.27.1.2 Auto postings and dates +................................. + +A posting date (or secondary date) in the matched posting, or (taking +precedence) a posting date in the auto posting rule itself, will also be +used in the generated posting. + + +File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings + +10.27.1.3 Auto postings and transaction balancing / inferred +............................................................ + +amounts / balance assertions Currently, 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. + + This also means that you cannot have more than one auto-posting with +a missing amount applied to a given transaction, as it will be unable to +infer amounts. + + +File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings + +10.27.1.4 Auto posting tags +........................... + +Automated postings will have some extra tags: + + • ‘generated-posting:= QUERY’ - shows this was generated by an auto + posting rule, and the query + • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear + in hledger’s output. This can be used to match postings generated + "just now", rather than generated in the past and saved to the + journal. + + Also, any transaction that has been changed by auto posting rules +will have these tags added: + + • ‘modified:’ - this transaction was modified + • ‘_modified:’ - a hidden tag not appearing in the comment; this + transaction was modified "just now". + + +File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax + +10.27.2 Balance assignments +--------------------------- + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account’s balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). + + Downsides: using balance assignments makes your journal less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. Also balance +assignments’ forcing of balances can hide errors. These things make +your financial data less portable, less future-proof, and less +trustworthy in an audit. + +* Menu: + +* Balance assignments and prices:: + + +File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments + +10.27.2.1 Balance assignments and prices +........................................ + +A cost 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.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax + +10.27.3 Bracketed posting dates +------------------------------- + +For setting posting dates and secondary posting dates, Ledger’s +bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or +‘[=DATE2]’ in posting comments. hledger will attempt to parse any +square-bracketed sequence of the ‘0123456789/-.=’ characters in this +way. With this syntax, DATE infers its year from the transaction and +DATE2 infers its year from DATE. + + Downsides: another syntax to learn, redundant with hledger’s +‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date +syntax. + + +File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax + +10.27.4 ‘D’ directive +--------------------- + +‘D AMOUNT’ + + This directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. This effect lasts until the next ‘D’ directive, or the end +of the journal. + + For compatibility/historical reasons, ‘D’ also acts like a +‘commodity’ directive (setting the commodity’s decimal mark for parsing +and display style for output). So its argument is not just a commodity +symbol, but a full amount demonstrating the style. The amount must +include a decimal mark (either period or comma). Eg: + +; commodity-less amounts should be treated as dollars +; (and displayed with the dollar sign on the left, thousands separators and two decimal places) +D $1,000.00 + +1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity’s display style, a ‘commodity’ directive has +highest priority, then a ‘D’ directive. + + For detecting a commodity’s decimal mark during parsing, +‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’. + + For checking commodity symbols with the check command, a ‘commodity’ +directive is required (‘hledger check commodities’ ignores ‘D’ +directives). + + Downsides: omitting commodity symbols makes your financial data less +explicit, less portable, and less trustworthy in an audit. It is +usually an unsustainable shortcut; sooner or later you will want to +track multiple commodities. D is overloaded with functions redundant +with ‘commodity’ and ‘decimal-mark’. And it works differently from +Ledger’s ‘D’. + + +File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax + +10.27.5 ‘apply account’ directive +--------------------------------- + +This directive sets a default parent account, which will be prepended to +all accounts in following entries, until an ‘end apply account’ +directive or end of current file. Eg: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + ‘account’ directives are also affected, and so is any ‘include’d +content. + + Account names entered via hledger add or hledger-web are not +affected. + + Account aliases, if any, are applied after the parent account is +prepended. + + Downsides: this can make your financial data less explicit, less +portable, and less trustworthy in an audit. + + +File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax + +10.27.6 ‘Y’ directive +--------------------- + +‘Y YEAR’ + + or (deprecated backward-compatible forms): + + ‘year YEAR’ ‘apply year YEAR’ + + The space is optional. This sets a default year to be used for +subsequent dates which don’t specify a year. Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +year 2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at +least) makes your financial data less explicit, less portable, and less +trustworthy in an audit. Such dates can get separated from their +corresponding Y directive, eg when evaluating a region of the journal in +your editor. A missing Y directive makes reports dependent on today’s +date. + + +File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax + +10.27.7 Secondary dates +----------------------- + +A secondary date is written after the primary date, following an equals +sign. If the year is omitted, the primary date’s year is assumed. When +running reports, the primary (left) date is used by default, but with +the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary +(right) date will be used instead. + + The meaning of secondary dates is up to you, but it’s best to follow +a consistent rule. Eg "primary = the bank’s clearing date, secondary = +date the transaction was initiated, if different". + + Downsides: makes your financial data more complicated, less portable, +and less trustworthy in an audit. Keeping the meaning of the two dates +consistent requires discipline, and you have to remember which reporting +mode is appropriate for a given report. Posting dates are simpler and +better. + + +File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax + +10.27.8 Star comments +--------------------- + +Lines beginning with ‘*’ (star/asterisk) are also comment lines. This +feature allows Emacs users to insert org headings in their journal, +allowing them to fold/unfold/navigate it like an outline when viewed +with org mode. + + Downsides: another, unconventional comment syntax to learn. +Decreases your journal’s portability. And switching to Emacs org mode +just for folding/unfolding meant losing the benefits of ledger mode; +nowadays you can add outshine mode to ledger mode to get folding without +losing ledger mode’s features. + + +File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax + +10.27.9 Valuation expressions +----------------------------- + +Ledger allows a valuation function or value to be written in double +parentheses after an amount. hledger ignores these. + + +File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax + +10.27.10 Virtual postings +------------------------- + +A posting with parentheses around the account name is called a _virtual +posting_ or _unbalanced posting_, which means it is exempt from the +usual rule that a transaction’s postings must balance add up to zero. + + This is not part of double entry bookkeeping, so you might choose to +avoid this feature. Or you can use it sparingly for certain special +cases where it can be convenient. Eg, you could set opening balances +without using a balancing equity account: + +2022-01-01 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with brackets around the account name is called a _balanced +virtual posting_. The balanced virtual postings in a transaction must +add up to zero (separately from other postings). Eg: + +2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Postings whose account names are neither parenthesised nor bracketed +are called _real postings_. You can exclude virtual postings from +reports with the ‘-R/--real’ flag or a ‘real:1’ query. + + Downsides: violates double entry bookkeeping, can be used to avoid +figuring out correct entries, makes your financial data less portable +and less trustworthy in an audit. + + +File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax + +10.27.11 Other Ledger directives +-------------------------------- + +These other Ledger directives are currently accepted but ignored. This +allows hledger to read more Ledger files, but be aware that hledger’s +reports may differ from Ledger’s if you use these. + +apply fixed COMM AMT +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR +end apply fixed +end apply tag +end apply year +end tag +eval / expr EXPR +python + PYTHONCODE +tag NAME +value EXPR +--command-line-flags + + See also https://hledger.org/ledger.html for a detailed +hledger/Ledger syntax comparison. + + +File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top + +11 CSV +****** + +hledger can read CSV files (Character Separated Value - usually comma, +semicolon, or tab) containing dated records, automatically converting +each record into a transaction. + + (To learn about _writing_ CSV, see CSV output.) + + For best error messages when reading CSV/TSV/SSV files, make sure +they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use +a hledger file prefix (see File Extension below). + + Each CSV file must be described by a corresponding _rules file_. +This contains rules describing the CSV data (header line, fields layout, +date format etc.), how to construct hledger transactions from it, and +how to categorise transactions based on description or other attributes. + + By default hledger looks for a rules file named like the CSV file +with an extra ‘.rules’ extension, in the same directory. Eg when asked +to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can +specify a different rules file with the ‘--rules-file’ option. If no +rules file is found, hledger will create a sample rules file, which +you’ll need to adjust. + + At minimum, the rules file must identify the date and amount fields, +and often it also specifies the date format and how many header lines +there are. Here’s a simple CSV file and a rules file for it: + +Date, Description, Id, Amount +12/11/2019, Foo, 123, 10.23 + +# basic.csv.rules +skip 1 +fields date, description, , amount +date-format %d/%m/%Y + +$ hledger print -f basic.csv +2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There’s an introductory Importing CSV data tutorial on hledger.org, +and more CSV rules examples below, and a larger collection at +https://github.com/simonmichael/hledger/tree/master/examples/csv. + +* Menu: + +* CSV rules cheatsheet:: +* separator:: +* skip:: +* date-format:: +* timezone:: +* newest-first:: +* intra-day-reversed:: +* decimal-mark:: +* fields list:: +* Field assignment:: +* Field names:: +* if block:: +* Matchers:: +* if table:: +* balance-type:: +* include:: +* Working with CSV:: +* CSV rules examples:: + + +File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV + +11.1 CSV rules cheatsheet +========================= + +The following kinds of rule can appear in the rules file, in any order. +(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.) + +*‘separator’* declare the field separator, instead of + relying on file extension +*‘skip’* skip one or more header lines at start of file +*‘date-format’* declare how to parse CSV dates/date-times +*‘timezone’* declare the time zone of ambiguous CSV + date-times +*‘newest-first’* improve txn order when: there are multiple + records, newest first, all with the same date +*‘intra-day-reversed’* improve txn order when: same-day txns are in + opposite order to the overall file +*‘decimal-mark’* declare the decimal mark used in CSV amounts, + when ambiguous +*‘fields’ list* name CSV fields for easy reference, and + optionally assign their values to hledger + fields +*Field assignment* assign a CSV value or interpolated text value + to a hledger field +*‘if’ block* conditionally assign values to hledger fields, + or ‘skip’ a record or ‘end’ (skip rest of + file) +*‘if’ table* conditionally assign values to hledger fields, + using compact syntax +*‘balance-type’* select which type of balance + assertions/assignments to generate +*‘include’* inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are +evaluated. + + +File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV + +11.2 ‘separator’ +================ + +You can use the ‘separator’ rule to read other kinds of +character-separated data. The argument is any single separator +character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for +comma-separated values (CSV): + +separator , + + or for semicolon-separated values (SSV): + +separator ; + + or for tab-separated values (TSV): + +separator TAB + + If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a +‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be +inferred automatically, and you won’t need this rule. + + +File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV + +11.3 ‘skip’ +=========== + +skip N + + The word ‘skip’ followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines at the start of the input +data. (Empty/blank lines are skipped automatically, so you don’t need +to count those.) You’ll need this whenever your CSV data contains +header lines. Header lines skipped in this way are ignored, and not +parsed as CSV. + + ‘skip’ can also be used inside if blocks (described below), to skip +individual data records. Note records skipped in this way are still +required to be valid CSV, even though otherwise ignored. + + +File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV + +11.4 ‘date-format’ +================== + +date-format DATEFMT + + This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV +dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, +you’ll need to add a date-format rule describing them with a +strptime-style date parsing pattern - see +https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. +The pattern must parse the CSV date value completely. Some examples: + +# MM/DD/YY +date-format %m/%d/%y + +# D/M/YYYY +# The - makes leading zeros optional. +date-format %-d/%-m/%Y + +# YYYY-Mmm-DD +date-format %Y-%h-%d + +# M/D/YYYY HH:MM AM some other junk +# Note the time and junk must be fully parsed, though only the date is used. +date-format %-m/%-d/%Y %l:%M %p some other junk + + +File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV + +11.5 ‘timezone’ +=============== + +timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone +other than yours, but containing no explicit time zone information, you +can use this rule to declare the CSV’s native time zone, which helps +prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don’t +need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’, +‘%Ez’; see the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware +conversion, localising the CSV date-times to your current system time +zone. If you prefer to localise to some other time zone, eg for +reproducibility, you can (on unix at least) set the output timezone with +the TZ environment variable, eg: + +$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + ‘timezone’ currently does not understand timezone names, except +"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". +For others, use numeric format: +HHMM or -HHMM. + + +File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV + +11.6 ‘newest-first’ +=================== + +hledger tries to ensure that the generated transactions will be ordered +chronologically, including intra-day transactions. Usually it can +auto-detect how the CSV records are ordered. But if it encounters CSV +where all records are on the same date, it assumes that the records are +oldest first. If in fact the CSV’s records are normally newest first, +like: + +2022-10-01, txn 3... +2022-10-01, txn 2... +2022-10-01, txn 1... + + you can add the ‘newest-first’ rule to help hledger generate the +transactions in correct order. + +# same-day CSV records are newest first +newest-first + + +File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV + +11.7 ‘intra-day-reversed’ +========================= + +CSV records for each day are sometimes ordered in reverse compared to +the overall date order. Eg, here dates are newest first, but the +transactions on each date are oldest first: + +2022-10-02, txn 3... +2022-10-02, txn 4... +2022-10-01, txn 1... +2022-10-01, txn 2... + + In this situation, add the ‘intra-day-reversed’ rule, and hledger +will compensate, improving the order of transactions. + +# transactions within each day are reversed with respect to the overall date order +intra-day-reversed + + +File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV + +11.8 ‘decimal-mark’ +=================== + +decimal-mark . + + or: + +decimal-mark , + + hledger automatically accepts either period or comma as a decimal +mark when parsing numbers (cf Amounts). However if any numbers in the +CSV contain digit group marks, such as thousand-separating commas, you +should declare the decimal mark explicitly with this rule, to avoid +misparsed numbers. + + +File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV + +11.9 ‘fields’ list +================== + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word ‘fields’ followed by comma-separated field +names) is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say + ‘%SomeField’ instead of remembering ‘%13’. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger’s fields and + build a transaction. + + Here’s an example that says "use the 1st, 2nd and 4th fields as the +transaction’s date, description and amount; name the last two fields for +later reference; and ignore the others": + +fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to +the CSV file’s separator. Also: + + • There must be least two items in the list (at least one comma). + • Field names may not contain spaces. Spaces before/after field + names are optional. + • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen). + • Fields you don’t care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it’s convenient to use these for +your field names, suitably modified (eg lower-cased with spaces replaced +by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning +to a hledger field with the same name. Eg you could call the CSV’s +"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’ +field (and generating a balance assertion). + + +File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV + +11.10 Field assignment +====================== + +HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to +hledger fields. They can be used instead of or in addition to a fields +list (see above). + + To assign a value to a hledger field, write the field name (any of +the standard hledger field/pseudo-field names, defined below), a space, +followed by a text value on the same line. This text value may +interpolate CSV fields, referenced by their 1-based position in the CSV +record (‘%N’), or by the name they were given in the fields list +(‘%CSVFIELD’). + + Some examples: + +# set the amount to the 4th CSV field, with " USD" appended +amount %4 USD + +# combine three fields to make a comment, containing note: and date: tags +comment note: %somefield - %anotherfield, date: %1 + + Tips: + + • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’ + becomes ‘1’ when interpolated) (#1051). + • Interpolations always refer to a CSV field - you can’t interpolate + a hledger field. (See Referencing other fields below). + + +File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV + +11.11 Field names +================= + +Note the two kinds of field names mentioned here, and used only in +hledger CSV rules files: + + 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally + name the CSV columns for easy reference (since hledger doesn’t yet + automatically recognise column headings in a CSV file), by writing + arbitrary names in a ‘fields’ list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you + must set at least some of these to generate the hledger transaction + from a CSV record, by writing them as the left hand side of a field + assignment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a ‘fields’ list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what +happens when you assign values to them: + +* Menu: + +* date field:: +* date2 field:: +* status field:: +* code field:: +* description field:: +* comment field:: +* account field:: +* amount field:: +* currency field:: +* balance field:: + + +File: hledger.info, Node: date field, Next: date2 field, Up: Field names + +11.11.1 date field +------------------ + +Assigning to ‘date’ sets the transaction date. + + +File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names + +11.11.2 date2 field +------------------- + +‘date2’ sets the transaction’s secondary date, if any. + + +File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names + +11.11.3 status field +-------------------- + +‘status’ sets the transaction’s status, if any. + + +File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names + +11.11.4 code field +------------------ + +‘code’ sets the transaction’s code, if any. + + +File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names + +11.11.5 description field +------------------------- + +‘description’ sets the transaction’s description, if any. + + +File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names + +11.11.6 comment field +--------------------- + +‘comment’ sets the transaction’s comment, if any. + + ‘commentN’, where N is a number, sets the Nth posting’s comment. + + You can assign multi-line comments by writing literal ‘\n’ in the +code. A comment starting with ‘\n’ will begin on a new line. + + Comments can contain tags, as usual. + + +File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names + +11.11.7 account field +--------------------- + +Assigning to ‘accountN’, where N is 1 to 99, sets the account name of +the Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you’ll want to set ‘account1’ +and ‘account2’. Typically ‘account1’ is associated with the CSV file, +and is set once with a top-level assignment, while ‘account2’ is set +based on each transaction’s description, in conditional rules. + + If a posting’s account name is left unset but its amount is set (see +below), a default account name will be chosen (like "expenses:unknown" +or "income:unknown"). + + +File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names + +11.11.8 amount field +-------------------- + +There are several "amount" field name variants, useful for different +situations: + + • ‘amountN’ sets the amount of the Nth posting, and causes that + posting to be generated. By assigning to ‘amount1’, ‘amount2’, ... + etc. you can generate up to 99 postings. Posting numbers don’t + have to be consecutive; in certain situations using a high number + might be helpful to influence the layout of postings. + + • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair, + when and only when the amount must be obtained from two CSV fields. + Eg when the CSV has separate Debit and Credit fields instead of a + single Amount field. Note: + + • Don’t think "-in is for the first posting and -out is for the + second posting" - that’s not correct. Think: "‘amountN-in’ + and ‘amountN-out’ together detect the amount for posting N, by + inspecting two CSV fields at once." + • hledger assumes both CSV fields are unsigned, and will + automatically negate the -out value. + • It also expects that at least one of the values is empty or + zero, so it knows which one to ignore. If that’s not the case + you’ll need an if rule (see Setting amounts below). + + • ‘amount’, with no posting number (and similarly, ‘amount-in’ and + ‘amount-out’ with no number) are an older syntax. We keep them for + backwards compatibility, and because they have special behaviour + that is sometimes convenient: + + • They set the amount of posting 1 and (negated) the amount of + posting 2. + • Posting 2’s amount will be converted to cost if it has a cost + price. + • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or + ‘amount2-in’ and ‘amount2-out’) will take precedence. This + allows incrementally migrating old rules files to the new + syntax. + + There’s more to say about amount-setting that doesn’t fit here; +please see also "Setting amounts" below. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +11.11.9 currency field +---------------------- + +‘currency’ sets a currency symbol, to be prepended to all postings’ +amounts. You can use this if the CSV amounts do not have a currency +symbol, eg if it is in a separate column. + + ‘currencyN’ prepends a currency symbol to just the Nth posting’s +amount. + + +File: hledger.info, Node: balance field, Prev: currency field, Up: Field names + +11.11.10 balance field +---------------------- + +‘balanceN’ sets a balance assertion amount (or if the posting amount is +left empty, a balance assignment) on posting N. + + ‘balance’ is a compatibility spelling for hledger <1.17; it is +equivalent to ‘balance1’. + + You can adjust the type of assertion/assignment with the +‘balance-type’ rule (see below). + + See Tips below for more about setting amounts and currency. + + +File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV + +11.12 ‘if’ block +================ + +Rules can be applied conditionally, depending on patterns in the CSV +data. This allows flexibility; in particular, it is how you can +categorise transactions, selecting an appropriate account name based on +their description (for example). There are two ways to write +conditional rules: "if blocks", described here, and "if tables", +described below. + + An if block is the word ‘if’ and one or more "matcher" expressions +(can be a word or phrase), one per line, starting either on the same or +next line; followed by one or more indented rules. Eg, + +if MATCHER + RULE + + or + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be +applied. They are usually field assignments, but the following special +rules may also be used within an if block: + + • ‘skip’ - skips the matched CSV record (generating no transaction + from it) + • ‘end’ - skips the rest of the current CSV file. + + Some examples: + +# if the record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the record contains any of these phrases, set account2 and a transaction comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + +# if an empty record is seen (assuming five fields), ignore the rest of the CSV file +if ,,,, + end + + +File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV + +11.13 Matchers +============== + +There are two kinds: + + 1. A record matcher is a word or single-line text fragment or regular + expression (‘REGEX’), which hledger will try to match + case-insensitively anywhere within the CSV record. + Eg: ‘whole foods’ + + 2. A field matcher is preceded with a percent sign and CSV field name + (‘%CSVFIELD REGEX’). hledger will try to match these just within + the named CSV field. + Eg: ‘%date 2023’ + + The regular expression is (as usual in hledger) a POSIX extended +regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’, +‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular +expressions" in the hledger manual +(https://hledger.org/hledger.html#regular-expressions). + + With record matchers, it’s important to know that the record matched +is not the original CSV record, but a modified one: separators will be +converted to commas, and enclosing double quotes (but not enclosing +whitespace) are removed. So for example, when reading an SSV file, if +the original record was: + +2020-01-01; "Acme, Inc."; 1,000 + + the regex would see, and try to match, this modified record text: + +2020-01-01,Acme, Inc., 1,000 + + When an if block has multiple matchers, they are combined as follows: + + • By default they are OR’d (any one of them can match) + • When a matcher is preceded by ampersand (‘&’) it will be AND’ed + with the previous matcher (both of them must match). + + There’s not yet an easy syntax to negate a matcher. + + +File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV + +11.14 ‘if’ table +================ + +"if tables" are an alternative to if blocks; they can express many +matchers and field assignments in a more compact tabular format, like +this: + +if,HLEDGERFIELD1,HLEDGERFIELD2,... +MATCHERA,VALUE1,VALUE2,... +MATCHERB,VALUE1,VALUE2,... +MATCHERC,VALUE1,VALUE2,... + + + The first character after ‘if’ is taken to be the separator for the +rest of the table. It should be a non-alphanumeric character like ‘,’ +or ‘|’ that does not appear anywhere else in the table. (Note: it is +unrelated to the CSV file’s separator.) Whitespace can be used in the +matcher lines for readability, but not in the if line currently. The +table must be terminated by an empty line (or end of file). Each line +must contain the same number of separators; empty values are allowed. + + The above means: try all of the matchers; whenever a matcher +succeeds, assign all of the values on that line to the corresponding +hledger fields; later lines can overrider earlier ones. It is +equivalent to this sequence of if blocks: + +if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERB + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + +if,account2,comment +atm transaction fee,expenses:business:banking,deductible? check it +%description groceries,expenses:groceries, +2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + +File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV + +11.15 ‘balance-type’ +==================== + +Balance assertions generated by assigning to balanceN are of the simple +‘=’ type by default, which is a single-commodity, subaccount-excluding +assertion. You may find the subaccount-including variants more useful, +eg if you have created some virtual subaccounts of checking to help with +budgeting. You can select a different type of assertion with the +‘balance-type’ rule: + +# balance assertions will consider all commodities and all subaccounts +balance-type ==* + + Here are the balance assertion types for quick reference: + += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts + + +File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV + +11.16 ‘include’ +=============== + +include RULESFILE + + This includes the contents of another CSV rules file at this point. +‘RULESFILE’ is an absolute file path or a path relative to the current +file’s directory. This can be useful for sharing common rules between +several rules files, eg: + +# someaccount.csv.rules + +## someaccount-specific rules +fields date,description,amount +account1 assets:someaccount +account2 expenses:misc + +## common rules +include categorisation.rules + + +File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV + +11.17 Working with CSV +====================== + +Some tips: + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading CSV from standard input:: +* Reading multiple CSV files:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Amount signs:: +* Setting currency/commodity:: +* Amount decimal places:: +* Referencing other fields:: +* How CSV rules are evaluated:: +* Well factored rules:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV + +11.17.1 Rapid feedback +---------------------- + +It’s a good idea to get rapid feedback while creating/troubleshooting +CSV rules. Here’s a good way, using entr from eradman.com/entrproject: + +$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions +of interest. "bash -c" is used to run multiple commands, so we can echo +a separator each time the command re-runs, making it easier to read the +output. + + +File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV + +11.17.2 Valid CSV +----------------- + +Note that hledger will only accept valid CSV conforming to RFC 4180, and +equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab +as separators). This means, eg: + + • Values may be enclosed in double quotes, or not. Enclosing in + single quotes is not allowed. (Eg ‘'A','B'’ is rejected.) + • When values are enclosed in double quotes, spaces outside the + quotes are not allowed. (Eg ‘"A", "B"’ is rejected.) + • When values are not enclosed in quotes, they may not contain double + quotes. (Eg ‘A"A, B’ is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you’ll need to +transform it before reading with hledger. Try using sed, or a more +permissive CSV parser like python’s csv lib. + + +File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV + +11.17.3 File Extension +---------------------- + +To help hledger choose the CSV file reader and show the right error +messages (and choose the right field separator character by default), +it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’ +filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV +reader (and the default field separator) by prefixing the file path with +‘csv:’, ‘ssv:’ or ‘tsv:’: Eg: + +$ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator +rule if needed. + + +File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV + +11.17.4 Reading CSV from standard input +--------------------------------------- + +You’ll need the file format prefix when reading CSV from stdin also, +since hledger assumes journal format by default. Eg: + +$ cat foo.dat | hledger -f ssv:- print + + +File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV + +11.17.5 Reading multiple CSV files +---------------------------------- + +If you use multiple ‘-f’ options to read multiple CSV files at once, +hledger will look for a correspondingly-named rules file for each CSV +file. But if you use the ‘--rules-file’ option, that rules file will be +used for all the CSV files. + + +File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV + +11.17.6 Valid transactions +-------------------------- + +After reading a CSV file, hledger post-processes and validates the +generated journal entries as it would for a journal file - balancing +them, applying balance assignments, and canonicalising amount styles. +Any errors at this stage will be reported in the usual way, displaying +the problem entry. + + There is one exception: balance assertions, if you have generated +them, will not be checked, since normally these will work only when the +CSV data is part of the main journal. If you do need to check balance +assertions generated from CSV right away, pipe into another hledger: + +$ hledger -f file.csv print | hledger -f- print + + +File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV + +11.17.7 Deduplicating, importing +-------------------------------- + +When you download a CSV file periodically, eg to get your latest bank +transactions, the new file may overlap with the old one, containing some +of the same records. + + The import command will (a) detect the new transactions, and (b) +append just those transactions to your main journal. It is idempotent, +so you don’t have to remember how many times you ran it or with which +version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’ +file.) This is the easiest way to import CSV data. Eg: + +# download the latest CSV files, then run this command. +# Note, no -f flags needed here. +$ hledger import *.csv [--dry] + + This method works for most CSV files. (Where records have a stable +chronological order, and new records appear only at the new end.) + + A number of other tools and workflows, hledger-specific and +otherwise, exist for converting, deduplicating, classifying and managing +CSV data. See: + + • https://hledger.org/cookbook.html#setups-and-workflows + • https://plaintextaccounting.org -> data import/conversion + + +File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV + +11.17.8 Setting amounts +----------------------- + +Continuing from amount field above, here are more tips on handling +various amount-setting situations: + + 1. *If the amount is in a single CSV field:* + + a. *If its sign indicates direction of flow:* + Assign it to ‘amountN’, to set the Nth posting’s amount. N is + usually 1 or 2 but can go up to 99. + + b. *If another field indicates direction of flow:* + Use one or more conditional rules to set the appropriate + amount sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. *If the amount is in one of two CSV fields (eg Debit and Credit):* + + a. *If both fields are unsigned:* + Assign the fields to ‘amountN-in’ and ‘amountN-out’. This + sets posting N’s amount to whichever of these has a non-zero + value. If it’s the -out value, the amount will be negated. + + b. *If either field is signed:* + Use a conditional rule to flip the sign when needed. Eg + below, the -out value already has a minus sign so we undo + hledger’s automatic negating by negating once more (but only + if the field is non-empty, so that we don’t leave a minus sign + by itself): + + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields can contain a non-zero value (or both can be + empty):* + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such + as ‘1’ and ‘none’. For such cases, use conditional rules to + help select the amount. Eg, to handle the above you could + select the value containing non-zero digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. *If you want posting 2’s amount converted to cost:* + Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’) + syntax. + + 4. *If the CSV has only balance amounts, not transaction amounts:* + Assign to ‘balanceN’, to set a balance assignment on the Nth + posting, causing the posting’s amount to be calculated + automatically. ‘balance’ with no number is equivalent to + ‘balance1’. In this situation hledger is more likely to guess the + wrong default account name, so you may need to set that explicitly. + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV + +11.17.9 Amount signs +-------------------- + +There is some special handling for amount signs, to simplify parsing and +sign-flipping: + + • *If an amount value begins with a plus sign:* + that will be removed: ‘+AMT’ becomes ‘AMT’ + + • *If an amount value is parenthesised:* + it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes + ‘-AMT’ + + • *If an amount value has two minus signs (or two sets of + parentheses, or a minus sign and parentheses):* + they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes + ‘AMT’ + + • *If an amount value contains just a sign (or just a set of + parentheses):* + that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or + ‘"()"’ becomes ‘""’. + + +File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV + +11.17.10 Setting currency/commodity +----------------------------------- + +If the currency/commodity symbol is included in the CSV’s amount +field(s): + +2020-01-01,foo,$123.00 + + you don’t have to do anything special for the commodity symbol, it +will be assigned as part of the amount. Eg: + +fields date,description,amount + +2020-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + +2020-01-01,foo,USD,123.00 + + You can assign that to the ‘currency’ pseudo-field, which has the +special effect of prepending itself to every amount in the transaction +(on the left, with no separating space): + +fields date,description,currency,amount + +2020-01-01 foo + expenses:unknown USD123.00 + income:unknown USD-123.00 + + Or, you can use a field assignment to construct the amount yourself, +with more control. Eg to put the symbol on the right, and separated by +a space: + +fields date,description,cur,amt +amount %amt %cur + +2020-01-01 foo + expenses:unknown 123.00 USD + income:unknown -123.00 USD + + Note we used a temporary field name (‘cur’) that is not ‘currency’ - +that would trigger the prepending effect, which we don’t want here. + + +File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV + +11.17.11 Amount decimal places +------------------------------ + +Like amounts in a journal file, the amounts generated by CSV rules like +‘amount1’ influence commodity display styles, such as the number of +decimal places displayed in reports. + + The original amounts as written in the CSV file do not affect display +style (because we don’t yet reliably know their commodity). + + +File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV + +11.17.12 Referencing other fields +--------------------------------- + +In field assignments, you can interpolate only CSV fields, not hledger +fields. In the example below, there’s both a CSV field and a hledger +field named amount1, but %amount1 always means the CSV field, not the +hledger field: + +# Name the third CSV field "amount1" +fields date,description,amount1 + +# Set hledger's amount1 to the CSV amount1 field followed by USD +amount1 %amount1 USD + +# Set comment to the CSV amount1 (not the amount1 assigned above) +comment %amount1 + + Here, since there’s no CSV amount1 field, %amount1 will produce a +literal "amount1": + +fields date,description,csvamount +amount1 %csvamount USD +# Can't interpolate amount1 here +comment %amount1 + + When there are multiple field assignments to the same hledger field, +only the last one takes effect. Here, comment’s value will be be B, or +C if "something" is matched, but never A: + +comment A +comment B +if something + comment C + + +File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV + +11.17.13 How CSV rules are evaluated +------------------------------------ + +Here’s how to think of CSV rules being evaluated (if you really need +to). First, + + • ‘include’ - all includes are inlined, from top to bottom, depth + first. (At each include point the file is inlined and scanned for + further includes, recursively, before proceeding.) + + Then "global" rules are evaluated, top to bottom. If a rule is +repeated, the last one wins: + + • ‘skip’ (at top level) + • ‘date-format’ + • ‘newest-first’ + • ‘fields’ - names the CSV fields, optionally sets up initial + assignments to hledger fields + + Then for each CSV record in turn: + + • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip + all remaining CSV records. Otherwise if any of them contain a + ‘skip’ rule, skip that many CSV records. If there are multiple + matched ‘skip’ rules, the first one wins. + • collect all field assignments at top level and in matched ‘if’ + blocks. When there are multiple assignments for a field, keep only + the last one. + • compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELD references), or a + default + • generate a hledger transaction (journal entry) from these values. + + This is all part of the CSV reader, one of several readers hledger +can use to parse input files. When all files have been read +successfully, the transactions are passed as input to whichever hledger +command the user specified. + + +File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV + +11.17.14 Well factored rules +---------------------------- + +Some things than can help reduce duplication and complexity in rules +files: + + • Extracting common rules usable with multiple CSV files into a + ‘common.rules’, and adding ‘include common.rules’ to each CSV’s + rules file. + + • Splitting if blocks into smaller if blocks, extracting the + frequently used parts. + + +File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV + +11.18 CSV rules examples +======================== + +* Menu: + +* Bank of Ireland:: +* Coinbase:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples + +11.18.1 Bank of Ireland +----------------------- + +Here’s a CSV with two amount fields (Debit and Credit), and a balance +field, which we can use to add balance assertions, which is not +necessary but provides extra error checking: + +Date,Details,Debit,Credit,Balance +07/12/2012,LODGMENT 529898,,10.0,131.21 +07/12/2012,PAYMENT,5,,126 + +# bankofireland-checking.csv.rules + +# skip the header line +skip + +# name the csv fields, and assign some of them as journal entry fields +fields date, description, amount-out, amount-in, balance + +# We generate balance assertions by assigning to "balance" +# above, but you may sometimes need to remove these because: +# +# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience +# +# - it is sometimes calculated based on non-chronological ordering, +# eg when multiple transactions clear on the same day + +# date is in UK/Ireland format +date-format %d/%m/%Y + +# set the currency +currency EUR + +# set the base account for all txns +account1 assets:bank:boi:checking + +$ hledger -f bankofireland-checking.csv print +2012-12-07 LODGMENT 529898 + assets:bank:boi:checking EUR10.0 = EUR131.2 + income:unknown EUR-10.0 + +2012-12-07 PAYMENT + assets:bank:boi:checking EUR-5.0 = EUR126.0 + expenses:unknown EUR5.0 + + The balance assertions don’t raise an error above, because we’re +reading directly from CSV, but they will be checked if these entries are +imported into a journal file. + + +File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples + +11.18.2 Coinbase +---------------- + +A simple example with some CSV from Coinbase. The spot price is +recorded using cost notation. The legacy ‘amount’ field name +conveniently sets amount 2 (posting 2’s amount) to the total cost. + +# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes +# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + +# coinbase.csv.rules +skip 1 +fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes +date %Timestamp +date-format %Y-%m-%dT%T%Z +description %Notes +account1 assets:coinbase:cc +amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + +$ hledger print -f coinbase.csv +2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + +File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples + +11.18.3 Amazon +-------------- + +Here we convert amazon.com order history, and use an if block to +generate a third posting if there’s a fee. (In practice you’d probably +get this data from your bank instead, but it’s an example.) + +"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" +"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" +"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" + +# amazon-orders.csv.rules + +# skip one header line +skip 1 + +# name the csv fields, and assign the transaction's date, amount and code. +# Avoided the "status" and "amount" hledger field names to prevent confusion. +fields date, _, toorfrom, name, amzstatus, amzamount, fees, code + +# how to parse the date +date-format %b %-d, %Y + +# combine two fields to make the description +description %toorfrom %name + +# save the status as a tag +comment status:%amzstatus + +# set the base account for all transactions +account1 assets:amazon +# leave amount1 blank so it can balance the other(s). +# I'm assuming amzamount excludes the fees, don't remember + +# set a generic account2 +account2 expenses:misc +amount2 %amzamount +# and maybe refine it further: +#include categorisation.rules + +# add a third posting for fees, but only if they are non-zero. +if %fees [1-9] + account3 expenses:fees + amount3 %fees + +$ hledger -f amazon-orders.csv print +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed + assets:amazon + expenses:misc $20.00 + +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed + assets:amazon + expenses:misc $25.00 + expenses:fees $1.00 + + +File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples + +11.18.4 Paypal +-------------- + +Here’s a real-world rules file for (customised) Paypal CSV, with some +Paypal-specific rules, and a second rules file included: + +"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" +"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" +"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" +"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" +"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" +"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" +"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" +"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" + +# paypal-custom.csv.rules + +# Tips: +# Export from Activity -> Statements -> Custom -> Activity download +# Suggested transaction type: "Balance affecting" +# Paypal's default fields in 2018 were: +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" +# This rules file assumes the following more detailed fields, configured in "Customize report fields": +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" + +fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note + +skip 1 + +date-format %-m/%-d/%Y + +# ignore some paypal events +if +In Progress +Temporary Hold +Update to + skip + +# add more fields to the description +description %description_ %itemtitle + +# save some other fields as tags +comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ + +# convert to short currency symbols +if %currency USD + currency $ +if %currency EUR + currency E +if %currency GBP + currency P + +# generate postings + +# the first posting will be the money leaving/entering my paypal account +# (negative means leaving my account, in all amount fields) +account1 assets:online:paypal +amount1 %netamount + +# the second posting will be money sent to/received from other party +# (account2 is set below) +amount2 -%grossamount + +# if there's a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] + account3 expenses:banking:paypal + amount3 -%feeamount + comment3 business: + +# choose an account for the second posting + +# override the default account names: +# if the amount is positive, it's income (a debit) +if %grossamount ^[^-] + account2 income:unknown +# if negative, it's an expense (a credit) +if %grossamount ^- + account2 expenses:unknown + +# apply common rules for setting account2 & other tweaks +include common.rules + +# apply some overrides specific to this csv + +# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case. +if +Bank Account +Bank Deposit to PP Account + description %type for %referencetxnid %itemtitle + account2 assets:bank:wf:pchecking + account1 assets:online:paypal + +# Currency conversions +if Currency Conversion + account2 equity:currency conversion + +# common.rules + +if +darcs +noble benefactor + account2 revenues:foss donations:darcshub + comment2 business: + +if +Calm Radio + account2 expenses:online:apps + +if +electronic frontier foundation +Patreon +wikimedia +Advent of Code + account2 expenses:dues + +if Google + account2 expenses:online:apps + description google | music + +$ hledger -f paypal-custom.csv print +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed + assets:online:paypal $-6.99 = $-6.99 + expenses:online:apps $6.99 + +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $6.99 = $0.00 + assets:bank:wf:pchecking $-6.99 + +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed + assets:online:paypal $-7.00 = $-7.00 + expenses:dues $7.00 + +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $7.00 = $0.00 + assets:bank:wf:pchecking $-7.00 + +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed + assets:online:paypal $-2.00 = $-2.00 + expenses:dues $2.00 + expenses:banking:paypal ; business: + +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $2.00 = $0.00 + assets:bank:wf:pchecking $-2.00 + +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed + assets:online:paypal $9.41 = $9.41 + revenues:foss donations:darcshub $-10.00 ; business: + expenses:banking:paypal $0.59 ; business: + + +File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top + +12 Timeclock +************ + +The time logging format of timeclock.el, as read by hledger. + + hledger can read time logs in timeclock format. As with Ledger, +these are (a subset of) timeclock.el’s format, containing clock-in and +clock-out entries as in the example below. The date is a simple date. +The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are +optional. The timezone, if present, must be four digits and is ignored +(currently the time is always interpreted as a local time). Lines +beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored. + +i 2015/03/30 09:00:00 some:account name optional description after two spaces +o 2015/03/30 09:20:00 +i 2015/03/31 22:21:45 another account +o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting +some number of hours to an account. Or if the session spans more than +one day, it is split into several transactions, one for each day. For +the above time log, ‘hledger print’ generates these journal entries: + +$ hledger -f t.timeclock print +2015-03-30 * optional description after two spaces + (some:account name) 0.33h + +2015-03-31 * 22:21-23:59 + (another account) 1.64h + +2015-04-01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + +$ hledger -f sample.timeclock balance # current time balances +$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + • use emacs and the built-in timeclock.el, or the extended + timeclock-x.el and perhaps the extras in ledgerutils.el + + • at the command line, use these bash aliases: ‘shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’ + + • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository. + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + +File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top + +13 Timedot +********** + +‘timedot’ format is hledger’s human-friendly time logging format. +Compared to ‘timeclock’ format, it is + + • convenient for quick, approximate, and retroactive time logging + • readable: you can see at a glance where time was spent. + + A timedot file contains a series of day entries, which might look +like this: + +2021-08-04 +hom:errands .... .... +fos:hledger:timedot .. ; docs +per:admin:finance + + hledger reads this as three time transactions on this day, with each +dot representing a quarter-hour spent: + +$ hledger -f a.timedot print # .timedot file extension activates the timedot reader +2021-08-04 * + (hom:errands) 2.00 + +2021-08-04 * + (fos:hledger:timedot) 0.50 + +2021-08-04 * + (per:admin:finance) 0 + + A day entry begins with a date line: + + • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D). + + Optionally this can be followed on the same line by + + • a common *transaction description* for this day + • a common *transaction comment* for this day, after a semicolon + (‘;’). + + After the date line are zero or more optionally-indented time +transaction lines, consisting of: + + • an *account name* - any word or phrase, usually a hledger-style + account name. + • *two or more spaces* - a field separator, required if there is an + amount (as in journal format). + • a *timedot amount* - dots representing quarter hours, or a number + representing hours. + • an optional *comment* beginning with semicolon. This is ignored. + + In more detail, timedot amounts can be: + + • *dots*: zero or more period characters, each representing one + quarter-hour. Spaces are ignored and can be used for grouping. + Eg: ‘.... ..’ + + • a *number*, representing hours. Eg: ‘1.5’ + + • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’, + ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days + weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following + equivalencies are assumed: + ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ = + ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the + generated transaction amount, which is always in hours.) + + There is some added flexibility to help with keeping time log data in +the same file as your notes, todo lists, etc.: + + • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored. + + • Before the first date line, lines beginning with ‘*’ are ignored. + From the first date line onward, a sequence of ‘*’’s followed by a + space at beginning of lines (ie, the headline prefix used by Emacs + Org mode) is ignored. This means the time log can be kept under an + Org headline, and date lines or time transaction lines can be Org + headlines. + + • Lines not ending with a double-space and amount are parsed as + transactions with zero amount. (Most hledger reports hide these by + default; add -E to see them.) + + More examples: + +# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. +2016/2/1 +inc:client1 .... .... .... .... .... .... +fos:haskell .... .. +biz:research . + +2016/2/2 +inc:client1 .... .... +biz:research . + +2016/2/3 +inc:client1 4 +fos:hledger 3 +biz:research 1 + +* Time log +** 2020-01-01 +*** adm:time . +*** adm:finance . + +* 2020 Work Diary +** Q1 +*** 2020-02-29 +**** DONE +0700 yoga +**** UNPLANNED +**** BEGUN +hom:chores + cleaning ... + water plants + outdoor - one full watering can + indoor - light watering +**** TODO +adm:planning: trip +*** LATER + + Reporting: + +$ hledger -f a.timedot print date:2016/2/2 +2016-02-02 * + (inc:client1) 2.00 + +2016-02-02 * + (biz:research) 0.25 + +$ hledger -f a.timedot bal --daily --tree +Balance changes in 2016-02-01-2016-02-03: + + || 2016-02-01d 2016-02-02d 2016-02-03d +============++======================================== + biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 +------------++---------------------------------------- + || 7.75 2.25 8.00 + + Using period instead of colon as account name separator: + +2016/2/4 +fos.hledger.timedot 4 +fos.ledger .. + +$ hledger -f a.timedot --alias /\\./=: bal --tree + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +-------------------- + 4.50 + + A sample.timedot file. + + +File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top + +14 PART 3: REPORTING CONCEPTS +***************************** + + +File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top + +15 Time periods +*************** + +* Menu: + +* Report start & end date:: +* Smart dates:: +* Report intervals:: +* Date adjustment:: +* Period expressions:: + + +File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods + +15.1 Report start & end date +============================ + +By default, most hledger reports will show the full span of time +represented by the journal. The report start date will be the earliest +transaction or posting date, and the report end date will be the latest +transaction, posting, or market price date. + + 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 (below). + + Some notes: + + • End dates are exclusive, as in Ledger, so you should write the date + _after_ the last day you want to see in the report. + • As noted in reporting options: among start/end dates specified with + _options_, the last (i.e. right-most) option takes precedence. + • The effective report start and end dates are the intersection of + the start/end dates from options and that from ‘date:’ queries. + That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January + 2019, the smallest common time span. + • In some cases a report interval will adjust start/end dates to fall + on interval boundaries (see below). + + Examples: + +‘-b begin on St. Patrick’s day 2016 +2016/3/17’ +‘-e 12/1’ end at the start of december 1st of the current year + (11/30 will be the last date included) +‘-b all transactions on or after the 1st of the current month +thismonth’ +‘-p all transactions in the current month +thismonth’ +‘date:2016/3/17..’the above written as queries instead (‘..’ can also be + replaced with ‘-’) +‘date:..12/1’ +‘date:thismonth..’ +‘date:thismonth’ + + +File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods + +15.2 Smart dates +================ + +hledger’s user interfaces accept a "smart date" syntax for added +convenience. Smart dates optionally can be relative to today’s date, be +written with english words, and have less-significant parts omitted +(missing parts are inferred as 1). Some examples: + +‘2004/10/1’, exact date, several separators allowed. Year +‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31 +‘2004.9.1’ +‘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, -1, 0, 1 days from today +tomorrow’ +‘last/this/next -1, 0, 1 periods from the current period +day/week/month/quarter/year’ +‘in n n periods from the current period +days/weeks/months/quarters/years’ +‘n n periods from the current period +days/weeks/months/quarters/years +ahead’ +‘n -n periods from the current period +days/weeks/months/quarters/years +ago’ +‘20181201’ 8 digit YYYYMMDD with valid year month and + day +‘201812’ 6 digit YYYYMM with valid year and month + + Some 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 + + "Today’s date" can be overridden with the ‘--today’ option, in case +it’s needed for testing or for recreating old reports. (Except for +periodic transaction rules, which are not affected by ‘--today’.) + + +File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods + +15.3 Report intervals +===================== + +A report interval can be specified so that reports like register, +balance or activity become multi-period, showing each subperiod as a +separate row or column. + + The following standard intervals can be enabled with command-line +flags: + + • ‘-D/--daily’ + • ‘-W/--weekly’ + • ‘-M/--monthly’ + • ‘-Q/--quarterly’ + • ‘-Y/--yearly’ + + More complex intervals can be specified using ‘-p/--period’, +described below. + + +File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods + +15.4 Date adjustment +==================== + +With a report interval (other than daily), report start / end dates +which have not been specified explicitly and in full (eg not ‘-b +2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are +considered flexible: + + • A flexible start date will be automatically adjusted earlier if + needed to fall on a natural interval boundary. + • Similarly, a flexible end date will be adjusted later if needed to + make the last period a whole interval (the same length as the + others). + + This is convenient for producing clean periodic reports (this is +traditional hledger behaviour). By contrast, fully-specified exact +dates will not be adjusted (this is new in hledger 1.29). + + An example: with a journal whose first date is 2023-01-10 and last +date is 2023-03-20: + + • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’ + The report periods will begin on the 15th day of each month, + starting from 2023-01-15, and the last period’s last day will be + 2023-03-09. (Exact start and end dates, neither is adjusted.) + + • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’ + The report periods will begin on the 1st of each month, starting + from 2023-01-01, and the last period’s last day will be 2023-03-31. + (Flexible start and end dates, both are adjusted.) + + +File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods + +15.5 Period expressions +======================= + +The ‘-p/--period’ option specifies a period expression, which is a +compact way of expressing a start date, end date, and/or report +interval. + + Here’s a period expression with a start and end date (specifying the +first quarter of 2009): + +‘-p "from 2009/1/1 to 2009/4/1"’ + + Several keywords like "from" and "to" are supported for readability; +these are optional. "to" can also be written as ".." or "-". The +spaces are also optional, as long as you don’t run two dates together. +So the following 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, these are also +equivalent to the above: + +‘-p "1/1 4/1"’ +‘-p "jan-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 date in the journal: + +‘-p "from 2009/1/1"’ everything after january 1, 2009 +‘-p "since 2009/1"’ the same, since is a synonym +‘-p "from 2009"’ the same +‘-p "to 2009"’ everything before january 1, 2009 + + You can also specify a period by writing a single partial or full +date: + +‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1” +‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to + 2009/2/1” +‘-p the first day of 2009; equivalent to “2009/1/1 to +"2009/1/1"’ 2009/1/2” + + or by using the "Q" quarter-year syntax (case insensitive): + +‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to + 2009/4/1” +‘-p "q4"’ fourth quarter of the current year + +* Menu: + +* Period expressions with a report interval:: +* More complex report intervals:: +* Multiple weekday intervals:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +15.5.1 Period expressions with a report interval +------------------------------------------------ + +A period expression can also begin with a report interval, separated +from the start/end dates (if any) by a space or the word ‘in’: + +‘-p "weekly from 2009/1/1 to 2009/4/1"’ +‘-p "monthly in 2008"’ +‘-p "quarterly"’ + + +File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions + +15.5.2 More complex report intervals +------------------------------------ + +Some more complex intervals can be specified within period expressions, +such as: + + • ‘biweekly’ (every two weeks) + • ‘fortnightly’ + • ‘bimonthly’ (every two months) + • ‘every day|week|month|quarter|year’ + • ‘every N days|weeks|months|quarters|years’ + + Weekly on a custom day: + + • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted + after the number) + • ‘every WEEKDAYNAME’ (full or three-letter english weekday name, + case insensitive) + + Monthly on a custom day: + + • ‘every Nth day [of month]’ + • ‘every Nth WEEKDAYNAME [of month]’ + + Yearly on a custom day: + + • ‘every MM/DD [of year]’ (month number and day of month number) + • ‘every MONTHNAME DDth [of year]’ (full or three-letter english + month name, case insensitive, and day of month number) + • ‘every DDth MONTHNAME [of year]’ (equivalent to the above) + + Examples: + +‘-p "bimonthly from +2008"’ +‘-p "every 2 weeks"’ +‘-p "every 5 months from +2009/03"’ +‘-p "every 2nd day of periods will go from Tue to Tue +week"’ +‘-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 + November +‘-p "every 5th November"’ same +‘-p "every Nov 5th"’ same + + Show historical balances at end of the 15th day of each month (N is +an end date, exclusive as always): + +$ hledger balance -H -p "every 16th day" + + Group postings from the start of wednesday to end of the following +tuesday (N is both (inclusive) start date and (exclusive) end date): + +$ hledger register checking -p "every 3rd day of week" + + +File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions + +15.5.3 Multiple weekday intervals +--------------------------------- + +This special form is also supported: + + • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english + weekday names, case insensitive) + + Also, ‘weekday’ and ‘weekendday’ are shorthand for +‘mon,tue,wed,thu,fri’ and ‘sat,sun’. + + This is mainly intended for use with ‘--forecast’, to generate +periodic transactions on arbitrary days of the week. It may be less +useful with ‘-p’, since it divides each week into subperiods of unequal +length, which is unusual. (Related: #1632) + + Examples: + +‘-p "every dates will be Mon, Wed, Fri; periods will be +mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun +‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will +weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun +‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri +weekendday"’ + + +File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top + +16 Depth +******** + +With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show +accounts only to the specified depth, hiding deeper subaccounts. Use +this when you want a summary with less detail. This flag has the same +effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are +equivalent. + + +File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top + +17 Queries +********** + +One of hledger’s strengths is being able to quickly report on a precise +subset of your data. Most hledger commands accept optional query +arguments to restrict their scope. The syntax is as follows: + + • Zero or more space-separated query terms. These are most often + account name substrings: + + ‘utilities food:groceries’ + + • Terms with spaces or other special characters should be enclosed in + quotes: + + ‘"personal care"’ + + • Regular expressions are also supported: + + ‘"^expenses\b" "accounts (payable|receivable)"’ + + • Add a query type prefix to match other parts of the data: + + ‘date:202012- desc:amazon cur:USD amt:">100" status:’ + + • Add a ‘not:’ prefix to negate a term: + + ‘not:cur:USD’ + +* Menu: + +* Query types:: +* Combining query terms:: +* Queries and command options:: +* Queries and valuation:: +* Querying with account aliases:: +* Querying with cost or value:: + + +File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries + +17.1 Query types +================ + +Here are the types of query term available. Remember these can also be +prefixed with *‘not:’* to convert them into a negative match. + + *‘acct:REGEX’, ‘REGEX’* +Match account names containing this (case insensitive) regular +expression. This is the default query type when there is no prefix, and +regular expression syntax is typically not needed, so usually we just +write an account name substring, like ‘expenses’ or ‘food’. + + *‘amt:N, amt:N, amt:>=N’* +Match postings with a single-commodity amount equal to, less than, or +greater than N. (Postings with 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 special characters which are +regex-significant, you need to escape them with ‘\’. And for characters +which are significant to your shell you may need one more level of +escaping. So eg to match the dollar sign: +‘hledger print cur:\\$’. + + *‘desc:REGEX’* +Match transaction descriptions. + + *‘date:PERIODEXPR’* +Match dates (or with the ‘--date2’ flag, secondary dates) within the +specified period. PERIODEXPR is a period expression with no report +interval. Examples: +‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’, +‘date:2021-07-27..nextquarter’. + + *‘date2:PERIODEXPR’* +Match secondary dates within the specified period (independent of the +‘--date2’ flag). + + *‘depth:N’* +Match (or display, depending on command) accounts at or above this +depth. + + *‘note:REGEX’* +Match transaction notes (the part of the description right of ‘|’, or +the whole description if there’s no ‘|’). + + *‘payee:REGEX’* +Match transaction payee/payer names (the part of the description left of +‘|’, or the whole description if there’s no ‘|’). + + *‘real:, real:0’* +Match real or virtual postings respectively. + + *‘status:, status:!, status:*’* +Match unmarked, pending, or cleared transactions respectively. + + *‘type:TYPECODES’* +Match by account type (see Declaring accounts > Account types). +‘TYPECODES’ is one or more of the single-letter account type codes +‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match +their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain +kinds of account alias can disrupt account types, see Rewriting accounts +> Aliases and account types. + + *‘tag:REGEX[=REGEX]’* +Match by tag name, and optionally also by tag value. (To match only by +value, use ‘tag:.=REGEX’.) + + When querying by tag, note that: + + • Accounts also inherit the tags of their parent accounts + • Postings also inherit the tags of their account and their + transaction + • Transactions also acquire the tags of their postings. + + (*‘inacct:ACCTNAME’* +A special query term used automatically in hledger-web only: tells +hledger-web to show the transaction register for an account.) + + +File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries + +17.2 Combining query terms +========================== + +When given multiple query terms, most commands select things which +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 is a little different, showing 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. + + Although these fixed rules are enough for many needs, we do not +support full boolean expressions (#203), (and you should not write AND +or OR in your queries). This makes certain queries hard to express, but +here are some tricks that can help: + + 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses + paid with cash: + + $ hledger print food not:not:cash + + 2. Or pre-filter the transactions with ‘print’, piping the result into + a second hledger command (with balance assertions disabled): + + $ hledger print cash | hledger -f- -I balance food + + +File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries + +17.3 Queries and command options +================================ + +Some queries can also be expressed as command-line options: ‘depth:2’ is +equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc. +When you mix command options and query arguments, generally the +resulting query is their intersection. + + +File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries + +17.4 Queries and valuation +========================== + +When amounts are converted to other commodities in cost or value +reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old +amount quantity, not the new ones (except in hledger 1.22.0 where it’s +reversed, see #1625). + + +File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries + +17.5 Querying with account aliases +================================== + +When account names are rewritten with ‘--alias’ or ‘alias’, note that +‘acct:’ will match either the old or the new account name. + + +File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries + +17.6 Querying with cost or value +================================ + +When amounts are converted to other commodities in cost or value +reports, note that ‘cur:’ matches the new commodity symbol, and not the +old one, and ‘amt:’ matches the new quantity, and not the old one. +Note: this changed in hledger 1.22, previously it was the reverse, see +the discussion at #1625. + + +File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top + +18 Pivoting +*********** + +Normally, hledger groups and sums amounts within each account. The +‘--pivot FIELD’ option substitutes some other transaction field for +account names, causing amounts to be grouped and summed by that field’s +value instead. FIELD can be any of the transaction fields ‘status’, +‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on +a tag and a posting has multiple values of that tag, only the first +value is displayed. Values containing ‘colon:separated:parts’ will be +displayed hierarchically, like account names. + + Some examples: + +2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues +-------------------- + 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): + +$ 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: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top + +19 Generating data +****************** + +Two features for generating transient data (visible only at report time) +are built in to hledger’s journal format: + + • Auto posting rules can generate extra postings on certain + transactions. They are activated by the ‘--auto’ flag. + + • Periodic transaction rules can generate repeating transactions, + usually dated in the future, to help with forecasting or budgeting. + They are activated by the ‘--forecast’ or ‘balance --budget’ + options, described next. + + +File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top + +20 Forecasting +************** + +The ‘--forecast’ flag activates any periodic transaction rules in the +journal. These will generate temporary additional transactions, usually +recurring and in the future, which will appear in all reports. ‘hledger +print --forecast’ is a good way to see them. + + This can be useful for estimating balances into the future, perhaps +experimenting with different scenarios. + + It could also be useful for scripted data entry: you could describe +recurring transactions, and every so often copy the output of ‘print +--forecast’ into the journal. + + The generated transactions will have an extra tag, like +‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule +generated them. There is also a similar, hidden tag, named +‘_generated-transaction:’, which you can use to reliably match +transactions generated "just now" (rather than ‘print’ed in the past). + + The forecast transactions are generated within a _forecast period_, +which is independent of the report period. (Forecast period sets the +bounds for generated transactions, report period controls which +transactions are reported.) The forecast period begins on: + + • the start date provided within ‘--forecast’’s argument, if any + • otherwise, the later of + • the report start date, if specified (with ‘-b’/‘-p’/‘date:’) + • the day after the latest ordinary transaction in the journal, + if any + + • otherwise today. + + It ends on: + + • the end date provided within ‘--forecast’’s argument, if any + • otherwise, the report end date, if specified (with + ‘-e’/‘-p’/‘date:’) + • otherwise 180 days (6 months) from today. + + Note, this means that ordinary transactions will suppress periodic +transactions, by default; the periodic transactions will not start until +after the last ordinary transaction. This is usually convenient, but +you can get around it in two ways: + + • If you need to record some transactions in the future, make them + periodic transactions (with a single occurrence, eg: ‘~ + YYYY-MM-DD’) rather than ordinary transactions. That way they + won’t suppress other periodic transactions. + + • Or give ‘--forecast’ a period expression argument. A forecast + period specified this way can overlap ordinary transactions, and + need not be in the future. Some things to note: + + • You must use ‘=’ between flag and argument; a space won’t + work. + • The period expression can specify the forecast period’s start + date, end date, or both. See also Report start & end date. + • The period expression should not specify a report interval. + (Each periodic transaction rule specifies its own interval.) + + Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’, +‘--forecast=2021’. + + +File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top + +21 Budgeting +************ + +With the balance command’s ‘--budget’ report, each periodic transaction +rule generates recurring budget goals in specified accounts, and goals +and actual performance can be compared. See the balance command’s doc +below. + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top + +22 Cost reporting +***************** + +This section is about recording the cost of things, in transactions +where one commodity is exchanged for another. Eg an exchange of +currency, or a stock purchase or sale. First, a quick glossary: + + • Conversion - an exchange of one currency or commodity for another. + Eg a foreign currency exchange, or a purchase or sale of stock or + cryptocurrency. + + • Conversion transaction - a transaction involving one or more + conversions. + + • Conversion rate - the cost per unit of one commodity in the other, + ie the exchange rate. + + • Cost - how much of one commodity was paid to acquire the other. + And more generally, in hledger docs: the amount exchanged in the + "secondary" commodity (usually your base currency), whether in a + purchase or a sale, and whether expressed per unit or in total. + Also, the "@/@@ PRICE" notation used to represent this. + +* Menu: + +* -B Convert to cost:: +* Equity conversion postings:: +* Inferring equity postings from cost:: +* Inferring cost from equity postings:: +* When to infer cost/equity:: +* How to record conversions:: +* Cost tips:: + + +File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting + +22.1 -B: Convert to cost +======================== + +As discussed in JOURNAL > Costs, when recording a transaction you can +also record the amount’s cost in another commodity, by adding ‘@ +UNITPRICE’ or ‘@@ TOTALPRICE’. + + Then you can see a report with amounts converted to cost, by adding +the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger). +Eg: + +2022-01-01 + assets:dollars $-135 ; 135 dollars is exchanged for.. + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + +$ hledger bal -N + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Notes: + + -B is sensitive to the order of postings when a cost 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: + +2022-01-01 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros + + The @/@@ cost notation is convenient, but has some drawbacks: it does +not truly balance the transaction, so it disrupts the accounting +equation and tends to causes a non-zero total in balance reports. + + +File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting + +22.2 Equity conversion postings +=============================== + +By contrast, conventional double entry bookkeeping (DEB) uses a +different notation: an extra pair of equity postings to balance +conversion transactions. In this style, the above entry might be +written: + +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 + + This style is more correct, but it’s also more verbose and makes cost +reporting more difficult for PTA tools. + + Happily, current hledger can read either notation, or convert one to +the other when needed, so you can use the one you prefer. + + You can even use cost notation and equivalent conversion postings at +the same time, for clarity. hledger will ignore the redundancy. But be +sure the cost and conversion posting amounts match, or you’ll see a +not-so-clear transaction balancing error message. + + +File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting + +22.3 Inferring equity postings from cost +======================================== + +With ‘--infer-equity’, hledger detects transactions written with PTA +cost notation and adds equity conversion postings to them: + +2022-01-01 + assets:dollars -$135 + assets:euros €100 @ $1.35 + +$ hledger print --infer-equity +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 + equity:conversion:$-€:€ €-100 ; generated-posting: + equity:conversion:$-€:$ $135.00 ; generated-posting: + + The conversion account names can be changed with the conversion +account type declaration. + + –infer-equity is useful when when transactions have been recorded +using cost notation, to help preserve the accounting equation and +balance reports’ zero total, or to produce more conventional journal +entries for sharing with non-PTA-users. + + +File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting + +22.4 Inferring cost from equity postings +======================================== + +The reverse operation is possible using ‘--infer-costs’, which detects +transactions written with equity conversion postings and adds cost +notation to them: + +2022-01-01 + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 + +$ hledger print --infer-costs +2022-01-01 + assets:dollars $-135 @@ €100 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 + + –infer-costs is useful when combined with -B/–cost, allowing cost +reporting even when transactions have been recorded using equity +postings: + +$ hledger print --infer-costs -B +2009-01-01 + assets:dollars €-100 + assets:euros €100 + + Notes: + + For ‘--infer-costs’ to work, an exchange must consist of four +postings: + + 1. two non-equity postings + 2. two equity postings, next to one another + 3. the equity accounts must be declared, with account type + ‘V’/‘Conversion’ (or if they are not declared, they must be named + ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or + subaccounts of these) + 4. the equity postings’ amounts must exactly match the non-equity + postings’ amounts. + + Multiple such exchanges can coexist within a single transaction. + + When inferring cost, the order of postings matters: the cost is added +to the first of the non-equity postings involved in the exchange, in the +commodity of the last non-equity posting involved in the exchange. If +you don’t want to write your postings in the required order, you can use +explicit cost notation instead. + + –infer-equity and –infer-costs can be used together, if you have a +mixture of both notations in your journal. + + +File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting + +22.5 When to infer cost/equity +============================== + +Inferring equity postings or costs is still fairly new, so not enabled +by default. We’re not sure yet if that should change. Here are two +suggestions to try, experience reports welcome: + + 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal + -B --infer-costs’ + + 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger + --infer-equity --infer-costs"’ + + +File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting + +22.6 How to record conversions +============================== + +Essentially there are four ways to record a conversion transaction in +hledger. Here are all of them, with pros and cons. + +* Menu: + +* Conversion with implicit cost:: +* Conversion with explicit cost:: +* Conversion with equity postings:: +* Conversion with equity postings and explicit cost:: + + +File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions + +22.6.1 Conversion with implicit cost +------------------------------------ + +Let’s assume 100 EUR is converted to 120 USD. You can just record the +outflow (100 EUR) and inflow (120 USD) in the appropriate asset account: + +2021-01-01 + assets:cash -100 EUR + assets:cash 120 USD + + hledger will assume this transaction is balanced, inferring that the +conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate +by using ‘hledger print -x’. + + Pro: + + • Concise, easy + + Con: + + • Less error checking - typos in amounts or commodity symbols may not + be detected + • Conversion rate is not clear + • Disturbs the accounting equation, unless you add the –infer-equity + flag + + You can prevent accidental implicit conversions due to a mistyped +commodity symbol, by using ‘hledger check commodities’. + + You can prevent implicit conversions entirely, by using ‘hledger +check balancednoautoconversion’, or ‘-s/--strict’. + + +File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions + +22.6.2 Conversion with explicit cost +------------------------------------ + +You can add the conversion rate using @ notation: + +2021-01-01 + assets:cash -100 EUR @ 1.20 USD + assets:cash 120 USD + + Now hledger will check that 100 * 1.20 = 120, and would report an +error otherwise. + + Pro: + + • Still concise + • Makes the conversion rate clear + • Provides more error checking + + Con: + + • Disturbs the accounting equation, unless you add the –infer-equity + flag + + +File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions + +22.6.3 Conversion with equity postings +-------------------------------------- + +In strict double entry bookkeeping, the above transaction is not +balanced in EUR or in USD, since some EUR disappears, and some USD +appears. This violates the accounting equation (A+L+E=0), and prevents +reports like ‘balancesheetequity’ from showing a zero total. + + The proper way to make it balance is to add a balancing posting for +each commodity, using an equity account: + +2021-01-01 + assets:cash -100 EUR + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + Pro: + + • Preserves the accounting equation + • Keeps track of conversions and related gains/losses in one place + • Standard, works in any double entry accounting system + + Con: + + • More verbose + • Conversion rate is not obvious + • Cost reporting requires adding the –infer-costs flag + + +File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions + +22.6.4 Conversion with equity postings and explicit cost +-------------------------------------------------------- + +Here both equity postings and @ notation are used together. + +2021-01-01 + assets:cash -100 EUR @ 1.20 USD + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + Pro: + + • Preserves the accounting equation + • Keeps track of conversions and related gains/losses in one place + • Makes the conversion rate clear + • Provides more error checking + + Con: + + • Most verbose + • Not compatible with ledger + + +File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting + +22.7 Cost tips +============== + + • Recording the cost/conversion rate explicitly is good because it + makes that clear and helps detect errors. + • Recording equity postings is good because it is correct bookkeeping + and preserves the accounting equation. + • Combining these is possible. + • When you want to see the cost (or sale proceeds) of things, use + ‘-B’ (short form of ‘--cost’). + • If you use conversion postings without cost notation, add + ‘--infer-costs’ also. + • If you use cost notation without conversion postings, and you want + to see a balanced balance sheet or print correct journal entries, + use ‘--infer-equity’. + • Conversion to cost is performed before valuation (described next). + + +File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top + +23 Valuation +************ + +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), and/or to market value (using some market price on a +certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’ +option, which will be described below. We also provide the simpler ‘-V’ +and ‘-X COMMODITY’ options, and often one of these is all you need: + +* Menu: + +* -V Value:: +* -X Value in specified commodity:: +* Valuation date:: +* Finding market price:: +* --infer-market-prices market prices from transactions:: +* Valuation commodity:: +* Simple valuation examples:: +* --value Flexible valuation:: +* More valuation examples:: +* Interaction of valuation and queries:: +* Effect of valuation on reports:: + + +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation + +23.1 -V: Value +============== + +The ‘-V/--market’ flag converts amounts to market value in their default +_valuation commodity_, using the market prices in effect on the +_valuation date(s)_, if any. More on these in a minute. + + +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation + +23.2 -X: Value in specified commodity +===================================== + +The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which +currency you want to convert to, and it tries to convert everything to +that. + + +File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation + +23.3 Valuation date +=================== + +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which market +prices will be used. + + For single period reports, if an explicit report end date is +specified, that will be used as the valuation date; otherwise the +valuation date is the journal’s end date. + + For multiperiod reports, each column/period is valued on the last day +of the period, by default. + + +File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation + +23.4 Finding market price +========================= + +To convert a commodity A to its market value in another commodity B, +hledger looks for a suitable market price (exchange rate) as follows, in +this order of preference : + + 1. A _declared market price_ or _inferred market price_: A’s latest + market price in B on or before the valuation date as declared by a + P directive, or (with the ‘--infer-market-prices’ flag) inferred + from costs. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 3. A _forward chain of market prices_: a synthetic price formed by + combining the shortest chain of "forward" (only 1 above) market + prices, leading from A to B. + + 4. _Any chain of market prices_: a chain of any market prices, + including both forward and reverse prices (1 and 2 above), leading + from A to B. + + There is a limit to the length of these price chains; if hledger +reaches that length without finding a complete chain or exhausting all +possibilities, it will give up (with a "gave up" message visible in +‘--debug=2’ output). That limit is currently 1000. + + Amounts for which no suitable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation + +23.5 –infer-market-prices: market prices from transactions +========================================================== + +Normally, market value in hledger is fully controlled by, and requires, +P directives in your journal. Since adding and updating those can be a +chore, and since transactions usually take place at close to market +value, why not use the recorded costs as additional market prices (as +Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or +‘--value’ enables this. + + So for example, ‘hledger bs -V --infer-market-prices’ will get market +prices both from P directives and from transactions. If both occur on +the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Valuation section carefully, and try adding +‘--debug’ or ‘--debug=2’ to troubleshoot. + + ‘--infer-market-prices’ can infer market prices from: + + • multicommodity transactions with explicit prices (‘@’/‘@@’) + + • multicommodity transactions with implicit prices (no ‘@’, two + commodities, unbalanced). (With these, the order of postings + matters. ‘hledger print -x’ can be useful for troubleshooting.) + + • multicommodity transactions with equity postings, if cost is + inferred with ‘--infer-costs’. + + There is a limitation (bug) currently: when a valuation commodity is +not specified, prices inferred with ‘--infer-market-prices’ do not help +select a default valuation commodity, as ‘P’ prices would. So +conversion might not happen because no valuation commodity was detected +(‘--debug=2’ will show this). To be safe, specify the valuation +commmodity, eg: + + • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’ + • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then + --infer-market-prices’ + + Signed costs and market prices can be confusing. For reference, here +is the current behaviour, since hledger 1.25. (If you think it should +work differently, see #1870.) + +2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + +2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + +2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + +2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + +2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + +2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each +day, the two transactions are considered equivalent). Here are the +market prices inferred for B: + +$ hledger -f- --infer-market-prices prices +P 2022-01-01 B A 1 +P 2022-01-01 B A 1.0 +P 2022-01-02 B A -1 +P 2022-01-02 B A -1.0 +P 2022-01-03 B A -1 +P 2022-01-03 B A -1.0 + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation + +23.6 Valuation commodity +======================== + +*When you specify a valuation commodity (‘-X COMM’ or ‘--value +TYPE,COMM’):* +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). + + *When you leave the valuation commodity unspecified (‘-V’ or ‘--value +TYPE’):* +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: + + 1. The price commodity from the latest P-declared market price for A + on or before valuation date. + + 2. The price commodity from the latest P-declared market price for A + on any date. (Allows conversion to proceed when there are inferred + prices before the valuation date.) + + 3. If there are no P directives at all (any commodity or date) and the + ‘--infer-market-prices’ flag is used: the price commodity from the + latest transaction-inferred price for A on or before valuation + date. + + This means: + + • If you have P directives, they determine which commodities ‘-V’ + will convert, and to what. + + • If you have no P directives, and use the ‘--infer-market-prices’ + flag, costs determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation + +23.7 Simple valuation examples +============================== + +Here are some quick examples of ‘-V’: + +; 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 + + +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation + +23.8 –value: Flexible valuation +=============================== + +‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option: + + --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. + COMM is an optional commodity symbol. + Shows amounts converted to: + - default valuation commodity (or COMM) using market prices at posting dates + - default valuation commodity (or COMM) using market prices at period end(s) + - default valuation commodity (or COMM) using current market prices + - default valuation commodity (or COMM) using market prices at some date + + The TYPE part selects cost or value and valuation date: + +‘--value=then’ + + Convert amounts to their value in the default valuation commodity, + using market prices on each posting’s date. +‘--value=end’ + + Convert amounts to their value in the default valuation commodity, + using market prices on the last day of the report period (or if + unspecified, the journal’s end date); or in multiperiod reports, + market prices on the last day of each subperiod. +‘--value=now’ + + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). +‘--value=YYYY-MM-DD’ + + Convert amounts to their value in the default valuation commodity + using market prices on this date. + + To select a different valuation commodity, add the optional ‘,COMM’ +part: a comma, then the target commodity’s symbol. Eg: +*‘--value=now,EUR’*. hledger will do its best to convert amounts to +this commodity, deducing market prices as described above. + + +File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation + +23.9 More valuation examples +============================ + +Here are some examples showing the effect of ‘--value’, as seen with +‘print’: + +P 2000-01-01 A 1 B +P 2000-02-01 A 2 B +P 2000-03-01 A 3 B +P 2000-04-01 A 4 B + +2000-01-01 + (a) 1 A @ 5 B + +2000-02-01 + (a) 1 A @ 6 B + +2000-03-01 + (a) 1 A @ 7 B + + Show the cost of each posting: + +$ hledger -f- print --cost +2000-01-01 + (a) 5 B + +2000-02-01 + (a) 6 B + +2000-03-01 + (a) 7 B + + Show the value as of the last day of the report period (2000-02-29): + +$ hledger -f- print --value=end date:2000/01-2000/03 +2000-01-01 + (a) 2 B + +2000-02-01 + (a) 2 B + + With no report period specified, that shows the value as of the last +day of the journal (2000-03-01): + +$ hledger -f- print --value=end +2000-01-01 + (a) 3 B + +2000-02-01 + (a) 3 B + +2000-03-01 + (a) 3 B + + Show the current value (the 2000-04-01 price is still in effect +today): + +$ hledger -f- print --value=now +2000-01-01 + (a) 4 B + +2000-02-01 + (a) 4 B + +2000-03-01 + (a) 4 B + + Show the value on 2000/01/15: + +$ hledger -f- print --value=2000-01-15 +2000-01-01 + (a) 1 B + +2000-02-01 + (a) 1 B + +2000-03-01 + (a) 1 B + + You may need to explicitly set a commodity’s display style, when +reverse prices are used. Eg this output might be surprising: + +P 2000-01-01 A 2B + +2000-01-01 + a 1B + b + +$ hledger print -x -X A +2000-01-01 + a 0 + b 0 + + Explanation: because there’s no amount or commodity directive +specifying a display style for A, 0.5A gets the default style, which +shows no decimal digits. Because the displayed amount looks like zero, +the commodity symbol and minus sign are not displayed either. Adding a +commodity directive sets a more useful display style for A: + +P 2000-01-01 A 2B +commodity 0.00A + +2000-01-01 + a 1B + b + +$ hledger print -X A +2000-01-01 + a 0.50A + b -0.50A + + +File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation + +23.10 Interaction of valuation and queries +========================================== + +When matching postings based on queries in the presence of valuation, +the following happens. + + 1. The query is separated into two parts: + 1. the currency (‘cur:’) or amount (‘amt:’). + 2. all other parts. + + 2. The postings are matched to the currency and amount queries based + on pre-valued amounts. + 3. Valuation is applied to the postings. + 4. The postings are matched to the other parts of the query based on + post-valued amounts. + + See: 1625 + + +File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation + +23.11 Effect of valuation on reports +==================================== + +Here is a reference for how valuation is supposed to affect each part of +hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll +sideways.) It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. + +Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’, +type ‘--cost’ ‘--value=now’ +------------------------------------------------------------------------------ +*print* +posting cost value at value at posting value at value +amounts report end date report or at + or today journal DATE/today + end +balance unchanged unchanged unchanged unchanged unchanged +assertions/assignments +*register* +starting cost value at valued at day value at value +balance report or each historical report or at +(-H) journal posting was made journal DATE/today + end end +starting cost value at valued at day value at value +balance day before each historical day before at +(-H) report or posting was made report or DATE/today +with journal journal +report start start +interval +posting cost value at value at posting value at value +amounts report or date report or at + journal journal DATE/today + end end +summary summarised value at sum of postings value at value +posting cost period in interval, period at +amounts ends valued at ends DATE/today +with interval start +report +interval +running sum/average sum/average sum/average of sum/average sum/average +total/averageof of displayed values of of + displayed displayed displayed displayed + values values values values +*balance +(bs, +bse, cf, +is)* +balance sums of value at value at posting value at value +changes costs report end date report or at + or today journal DATE/today + of sums of end of of + postings sums of sums + postings of + postings +budget like like like balance like like +amounts balance balance changes balances balance +(–budget) changes changes changes +grand sum of sum of sum of displayed sum of sum of +total displayed displayed valued displayed displayed + values values values values +*balance +(bs, +bse, cf, +is) with +report +interval* +starting sums of value at sums of values value at sums +balances costs of report of postings report of +(-H) postings start of before report start of postings + before sums of start at sums of before + report all respective all report + start postings posting dates postings start + before before + report report + start start +balance sums of same as sums of values balance value +changes costs of –value=end of postings in change in at +(bal, postings period at each DATE/today +is, bs in period respective period, of +–change, posting dates valued at sums +cf period of +–change) ends postings +end sums of same as sums of values period end value +balances costs of –value=end of postings from balances, at +(bal -H, postings before period valued at DATE/today +is –H, from start to period period of +bs, cf) before end at ends sums + report respective of + start to posting dates postings + period end +budget like like like balance like like +amounts balance balance changes/end balances balance +(–budget) changes/end changes/end balances changes/end + balances balances balances +row sums, sums, sums, averages sums, sums, +totals, averages averages of displayed averages averages +row of of values of of +averages displayed displayed displayed displayed +(-T, -A) values values values values +column sums of sums of sums of sums of sums +totals displayed displayed displayed values displayed of + values values values displayed + values +grand sum, sum, sum, average of sum, sum, +total, average of average of column totals average of average +grand column column column of +average totals totals totals column + totals + + ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with +a zero starting balance. + + *Glossary:* + +_cost_ + + calculated using price(s) recorded in the transaction(s). +_value_ + + market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. +_report start_ + + the first day of the report period specified with -b or -p or + date:, otherwise today. +_report or journal start_ + + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. +_report end_ + + the last day of the report period specified with -e or -p or date:, + otherwise today. +_report or journal end_ + + the last day of the report period specified with -e or -p or date:, + otherwise the latest transaction date in the journal, otherwise + today. +_report interval_ + + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report’s multi-period mode (whether showing one or many + subperiods). + + +File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top + +24 PART 4: COMMANDS +******************* + +* Menu: + +* Commands overview:: +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* payees:: +* prices:: +* print:: +* register:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS + +24.1 Commands overview +====================== + +Here are the built-in commands: + +* Menu: + +* DATA ENTRY:: +* DATA CREATION:: +* DATA MANAGEMENT:: +* REPORTS FINANCIAL:: +* REPORTS VERSATILE:: +* REPORTS BASIC:: +* HELP:: +* ADD-ONS:: + + +File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview + +24.1.1 DATA ENTRY +----------------- + +These data entry commands are the only ones which can modify your +journal file. + + • add - add transactions using terminal prompts + • import - add new transactions from other files, eg CSV files + + +File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview + +24.1.2 DATA CREATION +-------------------- + + • close - generate balance-zeroing/restoring transactions + • rewrite - generate auto postings, like print –auto + + +File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview + +24.1.3 DATA MANAGEMENT +---------------------- + + • check - check for various kinds of error in the data + • diff - compare account transactions in two journal files + + +File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview + +24.1.4 REPORTS, FINANCIAL +------------------------- + + • aregister (areg) - show transactions in a particular account + • 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 + + +File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview + +24.1.5 REPORTS, VERSATILE +------------------------- + + • balance (bal) - show balance changes, end balances, budgets, + gains.. + • print - show transactions or export journal data + • register (reg) - show postings in one or more accounts & running + total + • roi - show return on investments + + +File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview + +24.1.6 REPORTS, BASIC +--------------------- + + • accounts - show account names + • activity - show bar charts of posting counts per period + • codes - show transaction codes + • commodities - show commodity/currency symbols + • descriptions - show transaction descriptions + • files - show input file paths + • notes - show note parts of transaction descriptions + • payees - show payee parts of transaction descriptions + • prices - show market prices + • stats - show journal statistics + • tags - show tag names + • test - run self tests + + +File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview + +24.1.7 HELP +----------- + + • help - show the hledger manual with info/man/pager + + +File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview + +24.1.8 ADD-ONS +-------------- + +And here are some typical add-on commands. Some of these are installed +by the hledger-install script. If installed, they will appear in +hledger’s commands list: + + • ui - run hledger’s terminal UI + • web - run hledger’s web UI + • iadd - add transactions using a TUI (currently hard to build) + • interest - generate interest transactions + • stockquotes - download market prices from AlphaVantage + • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + pijul, plot, and more.. + + Next, each command is described in detail, in alphabetical order. + + +File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS + +24.2 accounts +============= + +Show account names. + + This command lists account names. By default it shows all known +accounts, either used in transactions or declared with account +directives. + + With query arguments, only matched account names and account names +referenced by matched postings are shown. + + Or it can show just the used accounts (‘--used’/‘-u’), the declared +accounts (‘--declared’/‘-d’), the accounts declared but not used +(‘--unused’), the accounts used but not declared (‘--undeclared’), or +the first account matched by an account name pattern, if any (‘--find’). + + 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’. + + With ‘--types’, it also shows each account’s type, if it’s known. +(See Declaring accounts > Account types.) + + With ‘--positions’, it also shows the file and line number of each +account’s declaration, if any, and the account’s overall declaration +order; these may be useful when troubleshooting account display order. + + With ‘--directives’, it adds the ‘account’ keyword, showing valid +account directives which can be pasted into a journal file. This is +useful together with ‘--undeclared’ when updating your account +declarations to satisfy ‘hledger check accounts’. + + The ‘--find’ flag can be used to look up a single account name, in +the same way that the ‘aregister’ command does. It returns the +alphanumerically-first matched account name, or if none can be found, it +fails with a non-zero exit code. + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + +$ hledger accounts --undeclared --directives >> $LEDGER_FILE +$ hledger check accounts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS + +24.3 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: aregister, Prev: activity, Up: PART 4 COMMANDS + +24.4 add +======== + +Prompt for transactions and add them to the journal. Any arguments will +be used as default inputs for the first N prompts. + + 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 main journal file (which should be +in journal format). Existing transactions are not changed. This is one +of the few hledger commands that writes to the journal file (see also +‘import’). + + 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, + payees/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 go one step + backward. + • Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see https://hledger.org/add.html for a detailed tutorial): + +$ 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 go one step backward. +To end a transaction, enter . when prompted. +To quit, enter . at a date prompt or press control-d or control-c. +Date [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]: $ + + On Microsoft Windows, the add command makes sure that no part of the +file path ends with a period, as that would cause problems (#1056). + + +File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS + +24.5 aregister +============== + +(areg) + + Show the transactions and running historical balance of a single +account, with each transaction displayed as one line. + + ‘aregister’ shows the overall transactions affecting a particular +account (and any subaccounts). Each report line represents one +transaction in this account. Transactions before the report start date +are always included in the running balance (‘--historical’ mode is +always on). + + This is a more "real world", bank-like view than the ‘register’ +command (which shows individual postings, possibly from multiple +accounts, not necessarily in historical mode). As a quick rule of +thumb: - use ‘aregister’ for reviewing and reconciling real-world +asset/liability accounts - use ‘register’ for reviewing detailed +revenues/expenses. + + ‘aregister’ requires one argument: the account to report on. You can +write either the full account name, or a case-insensitive regular +expression which will select the alphabetically first matched account. + + When there are multiple matches, the alphabetically-first choice can +be surprising; eg if you have ‘assets:per:checking 1’ and +‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select +‘assets:biz:checking 2’. It’s just a convenience to save typing, so if +in doubt, write the full account name, or a distinctive substring that +matches uniquely. + + Transactions involving subaccounts of this account will also be +shown. ‘aregister’ ignores depth limits, so its final total will always +match a balance report with similar arguments. + + Any additional arguments form a query which will filter the +transactions shown. Note some queries will disturb the running balance, +causing it to be different from the account’s real-world running +balance. + + An example: this shows the transactions and historical running +balance during july, in the first account whose name contains +"checking": + +$ hledger areg checking date:jul + + Each ‘aregister’ line item shows: + + • the transaction’s date (or the relevant posting’s date if + different, see below) + • the names of all the other account(s) involved in this transaction + (probably abbreviated) + • the total change to this account’s balance from this transaction + • the account’s historical running balance after this transaction. + + Transactions making a net change of zero are not shown by default; +add the ‘-E/--empty’ flag to show them. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +‘--align-all’ flag. + + This command also supports the output destination and output format +options. The output formats supported are ‘txt’, ‘csv’, and ‘json’. + +* Menu: + +* aregister and custom posting dates:: + + +File: hledger.info, Node: aregister and custom posting dates, Up: aregister + +24.5.1 aregister and custom posting dates +----------------------------------------- + +Transactions whose date is outside the report period can still be shown, +if they have a posting to this account dated inside the report period. +(And in this case it’s the posting date that is shown.) This ensures +that ‘aregister’ can show an accurate historical running balance, +matching the one shown by ‘register -H’ with the same arguments. + + To filter strictly by transaction date instead, add the ‘--txn-dates’ +flag. If you use this flag and some of your postings have custom dates, +it’s probably best to assume the running balance is wrong. + + +File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS + +24.6 balance +============ + +(bal) + + Show accounts and their balances. + + ‘balance’ is one of hledger’s oldest and most versatile commands, for +listing account balances, balance changes, values, value changes and +more, during one time period or many. Generally it shows a table, with +rows representing accounts, and columns representing periods. + + Note there are some higher-level variants of the ‘balance’ command +with convenient defaults, which can be simpler to use: ‘balancesheet’, +‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need +more control, then use ‘balance’. + +* Menu: + +* balance features:: +* Simple balance report:: +* Balance report line format:: +* Filtered balance report:: +* List or tree mode:: +* Depth limiting:: +* Dropping top-level accounts:: +* Showing declared accounts:: +* Sorting by amount:: +* Percentages:: +* Multi-period balance report:: +* Balance change end balance:: +* Balance report types:: +* Budget report:: +* Data layout:: +* Useful balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +24.6.1 balance features +----------------------- + +Here’s a quick overview of the ‘balance’ command’s features, followed by +more detailed descriptions and examples. Many of these work with the +higher-level commands as well. + + ‘balance’ can show.. + + • accounts as a list (‘-l’) or a tree (‘-t’) + • optionally depth-limited (‘-[1-9]’) + • sorted by declaration order and name, or by amount + + ..and their.. + + • balance changes (the default) + • or actual and planned balance changes (‘--budget’) + • or value of balance changes (‘-V’) + • or change of balance values (‘--valuechange’) + • or unrealised capital gain/loss (‘--gain’) + + ..in.. + + • one time period (the whole journal period by default) + • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’) + + ..either.. + + • per period (the default) + • or accumulated since report start date (‘--cumulative’) + • or accumulated since account creation (‘--historical/-H’) + + ..possibly converted to.. + + • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’) + • or market value, as of transaction dates (‘--value=then[,COMM]’) + • or at period ends (‘--value=end[,COMM]’) + • or now (‘--value=now’) + • or at some other date (‘--value=YYYY-MM-DD’) + + ..with.. + + • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign + (‘--invert’) + • rows and columns swapped (‘--transpose’) + • another field used as account name (‘--pivot’) + • custom-formatted line items (single-period reports only) + (‘--format’) + • commodities displayed on the same line or multiple lines + (‘--layout’) + + This command supports the output destination and output format +options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period +reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal, +negative amounts are shown in red. + + The ‘--related’/‘-r’ flag shows the balance of the _other_ postings +in the transactions of the postings which would normally be shown. + + +File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance + +24.6.2 Simple balance report +---------------------------- + +With no arguments, ‘balance’ shows a list of all accounts and their +change of balance - ie, the sum of posting amounts, both inflows and +outflows - during the entire period of the journal. ("Simple" here +means just one column of numbers, covering a single period. You can +also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end +balance at the end of the journal period; more on this below. + + Accounts are sorted by declaration order if any, and then +alphabetically by account name. For instance (using +examples/sample.journal): + +$ hledger -f examples/sample.journal bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + Accounts with a zero balance (and no non-zero subaccounts, in tree +mode - see below) are hidden by default. Use ‘-E/--empty’ to show them +(revealing ‘assets:bank:checking’ here): + +$ hledger -f examples/sample.journal bal -E + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + The total of the amounts displayed is shown as the last line, unless +‘-N’/‘--no-total’ is used. + + +File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance + +24.6.3 Balance report line format +--------------------------------- + +For single-period balance reports displayed in the terminal (only), you +can use ‘--format FMT’ to customise the format and content of each line. +Eg: + +$ hledger -f examples/sample.journal 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 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: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance + +24.6.4 Filtered balance report +------------------------------ + +You can show fewer accounts, a different time period, totals from +cleared transactions only, etc. by using query arguments or options to +limit the postings being matched. Eg: + +$ hledger -f examples/sample.journal bal --cleared assets date:200806 + $-2 assets:cash +-------------------- + $-2 + + +File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance + +24.6.5 List or tree mode +------------------------ + +By default, or with ‘-l/--flat’, accounts are shown as a flat list with +their full names visible, as in the examples above. + + With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’ +"leaf" names indented below their parent: + +$ hledger -f examples/sample.journal balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts +-------------------- + 0 + + Notes: + + • "Boring" accounts are combined with their subaccount for more + compact output, unless ‘--no-elide’ is used. Boring accounts have + no balance of their own and just one subaccount (eg ‘assets:bank’ + and ‘liabilities’ above). + + • All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, + which requires explanation when sharing reports with + non-plaintextaccounting-users. A tree mode report’s final total is + the sum of the top-level balances shown, not of all the balances + shown. + + • Each group of sibling accounts (ie, under a common parent) is + sorted separately. + + +File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance + +24.6.6 Depth limiting +--------------------- + +With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg: +‘-3’) balance reports will show accounts only to the specified depth, +hiding the deeper subaccounts. This can be useful for getting an +overview without too much detail. + + Account balances at the depth limit always include the balances from +any deeper subaccounts (even in list mode). Eg, limiting to depth 1: + +$ hledger -f examples/sample.journal balance -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities +-------------------- + 0 + + +File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance + +24.6.7 Dropping top-level accounts +---------------------------------- + +You can also hide one or more top-level account name parts, using +‘--drop NUM’. This can be useful for hiding repetitive top-level +account names: + +$ hledger -f examples/sample.journal bal expenses --drop 1 + $1 food + $1 supplies +-------------------- + $2 + + +File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance + +24.6.8 Showing declared accounts +-------------------------------- + +With ‘--declared’, accounts which have been declared with an account +directive will be included in the balance report, even if they have no +transactions. (Since they will have a zero balance, you will also need +‘-E/--empty’ to see them.) + + More precisely, _leaf_ declared accounts (with no subaccounts) will +be included, since those are usually the more useful in reports. + + The idea of this is to be able to see a useful "complete" balance +report, even when you don’t have transactions in all of your declared +accounts yet. + + +File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance + +24.6.9 Sorting by amount +------------------------ + +With ‘-S/--sort-amount’, accounts with the largest (most positive) +balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your +biggest averaged monthly expenses first. When more than one commodity +is present, they will be sorted by the alphabetically earliest commodity +first, and then by subsequent commodities (if an amount is missing a +commodity, it is treated as 0). + + Revenues and liability balances are typically negative, however, so +‘-S’ shows these in reverse order. To work around this, you can add +‘--invert’ to flip the signs. (Or, use one of the higher-level reports, +which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’). + + +File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance + +24.6.10 Percentages +------------------- + +With ‘-%/--percent’, balance reports show each account’s value expressed +as a percentage of the (column) total. + + Note it is not useful to calculate percentages if the amounts in a +column have mixed signs. In this case, make a separate report for each +sign, eg: + +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` + + Similarly, if the amounts in a column have mixed commodities, convert +them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a +separate report for each commodity: + +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ + + +File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance + +24.6.11 Multi-period balance report +----------------------------------- + +With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’, +‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag), +‘balance’ shows a tabular report, with columns representing successive +time periods (and a title): + +$ hledger -f examples/sample.journal bal --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 + + Notes: + + • The report’s start/end dates will be expanded, if necessary, to + fully encompass the displayed subperiods (so that the first and + last subperiods have the same duration as the others). + • Leading and trailing periods (columns) containing all zeroes are + not shown, unless ‘-E/--empty’ is used. + • Accounts (rows) containing all zeroes are not shown, unless + ‘-E/--empty’ is used. + • Amounts with many commodities are shown in abbreviated form, unless + ‘--no-elide’ is used. _(experimental)_ + • Average and/or total columns can be added with the ‘-A/--average’ + and ‘-T/--row-total’ flags. + • The ‘--transpose’ flag can be used to exchange rows and columns. + • The ‘--pivot FIELD’ option causes a different transaction field to + be used as "account name". See PIVOTING. + + Multi-period reports with many periods can be too wide for easy +viewing in the terminal. Here are some ways to handle that: + + • Hide the totals row with ‘-N/--no-total’ + • Convert to a single currency with ‘-V’ + • Maximize the terminal window + • Reduce the terminal’s font size + • View with a pager like less, eg: ‘hledger bal -D --color=yes | less + -RS’ + • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D + -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or + a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’) + • Output as HTML and view with a browser: ‘hledger bal -D -o a.html + && open a.html’ + + +File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance + +24.6.12 Balance change, end balance +----------------------------------- + +It’s important to be clear on the meaning of the numbers shown in +balance reports. Here is some terminology we use: + + A *_balance change_* is the net amount added to, or removed from, an +account during some period. + + An *_end balance_* is the amount accumulated in an account as of some +date (and some time, but hledger doesn’t store that; assume end of day +in your timezone). It is the sum of previous balance changes. + + We call it a *_historical end balance_* if it includes all balance +changes since the account was created. For a real world account, this +means it will match the "historical record", eg the balances reported in +your bank statements or bank web UI. (If they are correct!) + + In general, balance changes are what you want to see when reviewing +revenues and expenses, and historical end balances are what you want to +see when reviewing or reconciling asset, liability and equity accounts. + + ‘balance’ shows balance changes by default. To see accurate +historical end balances: + + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the + journal covers the account’s full lifetime. + + 2. Include all of of the account’s prior postings in the report, by + not specifying a report start date, or by using the + ‘-H/--historical’ flag. (‘-H’ causes report start date to be + ignored when summing postings.) + + +File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance + +24.6.13 Balance report types +---------------------------- + +The balance command is quite flexible; here is the full detail on how to +control what it reports. If the following seems complicated, don’t +worry - this is for advanced reporting, and it does typically take some +time and experimentation to get clear on all these report modes. + + There are three important option groups: + + ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] +...’ + +* Menu: + +* Calculation type:: +* Accumulation type:: +* Valuation type:: +* Combining balance report types:: + + +File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types + +24.6.13.1 Calculation type +.......................... + +The basic calculation to perform for each table cell. It is one of: + + • ‘--sum’ : sum the posting amounts (*default*) + • ‘--budget’ : sum the amounts, but also show the budget goal amount + (for each account/period) + • ‘--valuechange’ : show the change in period-end historical balance + values (caused by deposits, withdrawals, and/or market price + fluctuations) + • ‘--gain’ : show the unrealised capital gain/loss, (the current + valued balance minus each amount’s original cost) + + +File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types + +24.6.13.2 Accumulation type +........................... + +How amounts should accumulate across report periods. Another way to say +it: which time period’s postings should contribute to each cell’s +calculation. It is one of: + + • ‘--change’ : calculate with postings from column start to column + end, ie "just this column". Typically used to see + revenues/expenses. (*default for balance, incomestatement*) + + • ‘--cumulative’ : calculate with postings from report start to + column end, ie "previous columns plus this column". Typically used + to show changes accumulated since the report’s start date. Not + often used. + + • ‘--historical/-H’ : calculate with postings from journal start to + column end, ie "all postings from before report start date until + this column’s end". Typically used to see historical end balances + of assets/liabilities/equity. (*default for balancesheet, + balancesheetequity, cashflow*) + + +File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types + +24.6.13.3 Valuation type +........................ + +Which kind of value or cost conversion should be applied, if any, before +displaying the report. It is one of: + + • no valuation type : don’t convert to cost or value (*default*) + • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to + some other commodity) + • ‘--value=then[,COMM]’ : convert amounts to market value on + transaction dates + • ‘--value=end[,COMM]’ : convert amounts to market value on period + end date(s) + (*default with ‘--valuechange’, ‘--gain’*) + • ‘--value=now[,COMM]’ : convert amounts to market value on today’s + date + • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on + another date + + or one of the equivalent simpler flags: + + • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are + independent options which can both be used at once) + • ‘-V/--market’ : like –value=end + • ‘-X COMM/--exchange COMM’ : like –value=end,COMM + + See Cost reporting and Valuation for more about these. + + +File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types + +24.6.13.4 Combining balance report types +........................................ + +Most combinations of these options should produce reasonable reports, +but if you find any that seem wrong or misleading, let us know. The +following restrictions are applied: + + • ‘--valuechange’ implies ‘--value=end’ + • ‘--valuechange’ makes ‘--change’ the default when used with the + ‘balancesheet’/‘balancesheetequity’ commands + • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’ + + For reference, here is what the combinations of accumulation and +valuation show: + +Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value= +Accumulation:v YYYY-MM-DD + /now’ +----------------------------------------------------------------------------- +‘--change’change in sum of period-end DATE-value + period posting-date value of of change in + market values change in period + in period period +‘--cumulative’change from sum of period-end DATE-value + report start to posting-date value of of change + period end market values change from from report + from report report start start to + start to period to period end period end + end +‘--historicalchange from sum of period-end DATE-value +/-H’ journal start posting-date value of of change + to period end market values change from from journal + (historical end from journal journal start start to + balance) start to period to period end period end + end + + +File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance + +24.6.14 Budget report +--------------------- + +The ‘--budget’ report type activates extra columns showing any budget +goals for each account and period. The budget goals are defined by +periodic transactions. This is useful for comparing planned and actual +income, expenses, time usage, etc. + + 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] + + This is different from a normal balance report in several ways: + + • Only accounts with budget goals during the report period are shown, + by default. + + • In each column, in square brackets after the actual amount, budget + goal amounts are shown, and the actual/goal percentage. (Note: + budget goals should be in the same commodity as the actual amount.) + + • All parent accounts are always shown, even in list mode. Eg + assets, assets:bank, and expenses above. + + • Amounts always include all subaccounts, budgeted or unbudgeted, + even in list mode. + + This means that the numbers displayed will not always add up! Eg +above, the ‘expenses’ actual amount includes the gifts and supplies +transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts +are not shown, as they have no budget amounts declared. + + This can be confusing. When you need to make things clearer, use the +‘-E/--empty’ flag, which will reveal all accounts including unbudgeted +ones, giving the full picture. Eg: + +$ 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] + + It’s common to limit budgets/budget reports to just expenses + +hledger bal -M --budget expenses + + or just revenues and expenses (eg, using account types): + +hledger bal -M --budget type:rx + + It’s also common to limit or convert them to a single currency +(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple +currencies, ‘--layout bare’ or ‘--layout tall’ can help. + + For more examples and notes, see Budgeting. + +* Menu: + +* Budget report start date:: +* Budgets and subaccounts:: +* Selecting budget goals:: +* Budget vs forecast:: + + +File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report + +24.6.14.1 Budget report start date +.................................. + +This might be a bug, but for now: when making budget reports, it’s a +good idea to explicitly set the report’s start date to the first day of +a reporting period, because a periodic rule like ‘~ monthly’ generates +its transactions on the 1st of each month, and if your journal has no +regular transactions on the 1st, the default report start date could +exclude that budget goal, which can be a little surprising. Eg here the +default report period is just the day of 2020-01-15: + +~ monthly in 2020 + (expenses:food) $500 + +2020-01-15 + expenses:food $400 + assets:checking + +$ hledger bal expenses --budget +Budget performance in 2020-01-15: + + || 2020-01-15 +==============++============ + || $400 +--------------++------------ + || $400 + + To avoid this, specify the budget report’s period, or at least the +start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the +budget goal transactions (periodic transactions) that you want. Eg, +adding ‘-b 2020/1/1’ to the above: + +$ hledger bal expenses --budget -b 2020/1/1 +Budget performance in 2020-01-01..2020-01-15: + + || 2020-01-01..2020-01-15 +===============++======================== + expenses:food || $400 [80% of $500] +---------------++------------------------ + || $400 [80% of $500] + + +File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report + +24.6.14.2 Budgets and subaccounts +................................. + +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 implicitly +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] + + +File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report + +24.6.14.3 Selecting budget goals +................................ + +The budget report evaluates periodic transaction rules to generate +special "goal transactions", which generate the goal amounts for each +account in each report subperiod. When troubleshooting, you can use +‘print --forecast’ to show these as forecasted transactions: + +$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated + + By default, the budget report uses all available periodic transaction +rules to generate goals. This includes rules with a different report +interval from your report. Eg if you have daily, weekly and monthly +periodic rules, all of these will contribute to the goals in a monthly +budget report. + + You can select a subset of periodic rules by providing an argument to +the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules +whose description contains DESCPAT, a case-insensitive substring (not a +regular expression or query). This means you can give your periodic +rules descriptions (remember that two spaces are needed), and then +select from multiple budgets defined in your journal. + + +File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report + +24.6.14.4 Budget vs forecast +............................ + +‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate +features, though both of them use the periodic transaction rules defined +in the journal, and both of them generate temporary transactions for +reporting purposes ("forecast transactions" and "budget goal +transactions", respectively). You can use both features at the same +time if you want. Here are some differences between them, as of hledger +1.29: + + CLI: + + • –forecast is a general hledger option, usable with any command + • –budget is a ‘balance’ command option, usable only with that + command. + + Visibility of generated transactions: + + • forecast transactions are visible in any report, like ordinary + transactions + • budget goal transactions are invisible except for the goal amounts + they produce in –budget reports. + + Periodic transaction rules: + + • –forecast uses all available periodic transaction rules + • –budget uses all periodic rules (‘--budget’) or a selected subset + (‘--budget=DESCPAT’) + + Period of generated transactions: + + • –forecast generates forecast transactions + • from after the last regular transaction to the end of the + report period (‘--forecast’) + • or, during a specified period (‘--forecast=PERIODEXPR’) + • possibly further restricted by a period specified in the + periodic transaction rule + • and always restricted within the bounds of the report period + + • –budget generates budget goal transactions + • throughout the report period + • possibly restricted by a period specified in the periodic + transaction rule. + + +File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance + +24.6.15 Data layout +------------------- + +The ‘--layout’ option affects how balance reports show multi-commodity +amounts and commodity symbols, which can improve readability. It can +also normalise the data for easy consumption by other programs. It has +four possible values: + + • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line, + optionally elided to WIDTH + • ‘--layout=tall’: each commodity is shown on a separate line + • ‘--layout=bare’: commodity symbols are in their own column, amounts + are bare numbers + • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form, + with one row per data value + + Here are the ‘--layout’ modes supported by each output format; note +only CSV output supports all of them: + +- txt csv html json sql +--------------------------------------- +wide Y Y Y +tall Y Y Y +bare Y Y Y +tidy Y + + Examples: + + • Wide layout. With many commodities, reports can be very wide: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + • Limited wide layout. A width limit reduces the width, but some + commodities will be hidden: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + • Tall layout. Each commodity gets a new line (may be different in + each column), and account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + • Bare layout. Commodity symbols are kept in one column, each + commodity gets its own report row, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + • Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + • Tidy layout produces normalised "tidy data", where every variable + has its own column and each row represents a single data point. + See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html + for more. This is the easiest kind of data for other software to + consume. Here’s how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + +File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance + +24.6.16 Useful balance reports +------------------------------ + +Some frequently used ‘balance’ options/reports are: + + • ‘bal -M revenues expenses’ + Show revenues/expenses in each month. Also available as the + ‘incomestatement’ command. + + • ‘bal -M -H assets liabilities’ + Show historical asset/liability balances at each month end. Also + available as the ‘balancesheet’ command. + + • ‘bal -M -H assets liabilities equity’ + Show historical asset/liability/equity balances at each month end. + Also available as the ‘balancesheetequity’ command. + + • ‘bal -M assets not:receivable’ + Show changes to liquid assets in each month. Also available as the + ‘cashflow’ command. + + Also: + + • ‘bal -M expenses -2 -SA’ + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + • ‘bal -M --budget expenses’ + Show monthly expenses and budget goals. + + • ‘bal -M --valuechange investments’ + Show monthly change in market value of investment assets. + + • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert]’ + Show top gainers [or losers] last week + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS + +24.7 balancesheet +================= + +(bs) + + This command displays a balance sheet, showing historical ending +balances of asset and liability accounts. (To see equity as well, use +the balancesheetequity command.) Amounts are shown with normal positive +sign, as in conventional financial statements. + + This report shows accounts declared with the ‘Asset’, ‘Cash’ or +‘Liability’ type (see account types). Or if no such accounts are +declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case +insensitive, plurals allowed) and their subaccounts. + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance -H assets liabilities’, but with +smarter account detection, and liabilities displayed with their sign +flipped. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS + +24.8 balancesheetequity +======================= + +(bse) + + This command displays a balance sheet, showing historical ending +balances of asset, liability and equity accounts. Amounts are shown +with normal positive sign, as in conventional financial statements. + + This report shows accounts declared with the ‘Asset’, ‘Cash’, +‘Liability’ or ‘Equity’ type (see account types). Or if no such +accounts are declared, it shows top-level accounts named ‘asset’, +‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their +subaccounts. + + 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 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance -H assets liabilities equity’, but +with smarter account detection, and liabilities/equity displayed with +their sign flipped. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS + +24.9 cashflow +============= + +(cf) + + This command displays a cashflow statement, showing the inflows and +outflows affecting "cash" (ie, liquid, easily convertible) assets. +Amounts are shown with normal positive sign, as in conventional +financial statements. + + This report shows accounts declared with the ‘Cash’ type (see account +types). Or if no such accounts are declared, it shows accounts + + • under a top-level account named ‘asset’ (case insensitive, plural + allowed) + • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or + ‘saving’. + + More precisely: all accounts matching this case insensitive regular +expression: + + ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’ + + and their subaccounts. + + An example cashflow report: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance assets not:fixed not:investment +not:receivable’, but with smarter account detection. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS + +24.10 check +=========== + +Check for various kinds of errors in your data. + + hledger provides a number of built-in error checks to help prevent +problems in your data. Some of these are run automatically; or, you can +use this ‘check’ command to run them on demand, with no output and a +zero exit code if all is well. Specify their names (or a prefix) as +argument(s). + + Some examples: + +hledger check # basic checks +hledger check -s # basic + strict checks +hledger check ordereddates payees # basic + two other checks + + If you are an Emacs user, you can also configure flycheck-hledger to +run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available: + +* Menu: + +* Basic checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: +* More about specific checks:: + + +File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check + +24.10.1 Basic checks +-------------------- + +These checks are always run automatically, by (almost) all hledger +commands, including ‘check’: + + • *parseable* - data files are well-formed and can be successfully + parsed + + • *balancedwithautoconversion* - all transactions are balanced, + inferring missing amounts where necessary, and possibly converting + commodities using costs or automatically-inferred costs + + • *assertions* - all balance assertions in the journal are passing. + (This check can be disabled with ‘-I’/‘--ignore-assertions’.) + + +File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check + +24.10.2 Strict checks +--------------------- + +These additional checks are run when the ‘-s’/‘--strict’ (strict mode) +flag is used. Or, they can be run by giving their names as arguments to +‘check’: + + • *accounts* - all account names used by transactions have been + declared + + • *commodities* - all commodity symbols used have been declared + + • *balancednoautoconversion* - transactions are balanced, possibly + using explicit costs but not inferred ones + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +24.10.3 Other checks +-------------------- + +These checks can be run only by giving their names as arguments to +‘check’. They are more specialised and not desirable for everyone, +therefore optional: + + • *ordereddates* - transactions are ordered by date within each file + + • *payees* - all payees used by transactions have been declared + + • *recentassertions* - all accounts with balance assertions have a + balance assertion no more than 7 days before their latest posting + + • *tags* - all tags used by transactions have been declared + + • *uniqueleafnames* - all account leaf names are unique + + +File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check + +24.10.4 Custom checks +--------------------- + +A few more checks are are available as separate add-on commands, in +https://github.com/simonmichael/hledger/tree/master/bin: + + • *hledger-check-tagfiles* - all tag values containing / (a forward + slash) exist as file paths + + • *hledger-check-fancyassertions* - more complex balance assertions + are passing + + You could make similar scripts to perform your own custom checks. +See: Cookbook -> Scripting. + + +File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check + +24.10.5 More about specific checks +---------------------------------- + +‘hledger check recentassertions’ will complain if any balance-asserted +account does not have a balance assertion within 7 days before its +latest posting. This aims to prevent the situation where you are +regularly updating your journal, but forgetting to check your balances +against the real world, then one day must dig back through months of +data to find an error. It assumes that adding a balance assertion +requires/reminds you to check the real-world balance. That may not be +true if you auto-generate balance assertions from bank data; in that +case, I recommend to import transactions uncleared, then use the +manual-review-and-mark-cleared phase as a reminder to check the latest +assertions against real-world balances. + + +File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS + +24.11 close +=========== + +‘close [--retain | --migrate | --open] [QUERY]’ + + By default: prints a transaction that zeroes out ("closes") all +accounts, transferring their balances to an equity account. Query +arguments can be added to override the accounts selection. Three other +modes are supported: + + ‘--retain’: prints a transaction closing revenue and expense +balances. This is traditionally done by businesses at the end of each +accounting period; it is less necessary in personal and computer-based +accounting, but it can help balance the accounting equation A=L+E. + + ‘--migrate’: prints a transaction to close asset, liability and most +equity balances, and another transaction to re-open them. This can be +useful when starting a new file (for performance or data protection). +Adding the closing transaction to the old file allows old and new files +to be combined. + + ‘--open’: as above, but prints just the opening transaction. This +can be useful for starting a new file, leaving the old file unchanged. +Similar to Ledger’s equity command. + + You can change the equity account name with ‘--close-acct ACCT’. It +defaults to ‘equity:retained earnings’ with ‘--retain’, or +‘equity:opening/closing balances’ otherwise. + + You can change the transaction description(s) with ‘--close-desc +'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with +‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise. + + Just one posting to the equity account will be used by default, with +an implicit amount. + + With ‘--x/--explicit’ the amount will be shown explicitly, and if it +involves multiple commodities, a separate posting will be generated for +each commodity. + + With ‘--interleaved’, each equity posting is shown next to the +corresponding source/destination posting. + + The default closing date is yesterday or the journal’s end date, +whichever is later. You can change this by specifying a report end +date; the last day of the report period will be the closing date. Eg +‘-e 2022’ means "close on 2022-12-31". + + The default closing date is yesterday, or the journal’s end date, +whichever is later. You can change this by specifying a report end +date; (The report start date does not matter.) The last day of the +report period will be the closing date; eg ‘-e 2022’ means "close on +2022-12-31". The opening date is always the day after the closing date. + +* Menu: + +* close and costs:: +* close and balance assertions:: +* Example retain earnings:: +* Example migrate balances to a new file:: +* Example excluding closing/opening transactions:: + + +File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close + +24.11.1 close and costs +----------------------- + +With ‘--show-costs’, any amount costs are shown, with separate postings +for each cost. (This currently the best way to view investment assets, +showing lots and cost bases.) If you have many currency conversion or +investment transactions, it can generate very large journal entries. + + +File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close + +24.11.2 close and balance assertions +------------------------------------ + +Balance assertions will be generated, verifying that the accounts have +been reset to zero (and then restored to their previous balances, if +there is an opening transaction). + + These provide useful error checking, but you can ignore them +temporarily with ‘-I’, or remove them if you prefer. + + You probably should avoid filtering transactions by status or +realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’), +with this command, since the balance assertions would depend on these. + + Note custom posting dates spanning the file boundary will disrupt the +balance assertions: + +2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve that you can transfer the money to and from a temporary +account, in effect splitting the multi-day transaction into two +single-day transactions: + +; in 2022.journal: +2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + +; in 2023.journal: +2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + +File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close + +24.11.3 Example: retain earnings +-------------------------------- + +Record 2022’s revenues/expenses as retained earnings on 2022-12-31, +appending the generated transaction to the journal: + +$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + Now 2022’s income statement will show only zeroes. To see it again, +exclude the retain transaction. Eg: + +$ hledger -f 2022.journal is not:desc:'retain earnings' + + +File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close + +24.11.4 Example: migrate balances to a new file +----------------------------------------------- + +Close assets/liabilities/equity on 2022-12-31 and re-open them on +2023-01-01: + +$ hledger close --migrate -f 2022.journal -p 2022 +# copy/paste the closing transaction to the end of 2022.journal +# copy/paste the opening transaction to the start of 2023.journal + + Now 2022’s balance sheet will show only zeroes, indicating a balanced +accounting equation. (Unless you are using @/@@ notation - in that +case, try adding –infer-equity.) To see it again, exclude the closing +transaction. Eg: + +$ hledger -f 2022.journal bs not:desc:'closing balances' + + +File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close + +24.11.5 Example: excluding closing/opening transactions +------------------------------------------------------- + +When combining many files for multi-year reports, the closing/opening +transactions cause some noise in reports like ‘print’ and ‘register’. +You can exclude them as shown above, but ‘not:desc:...’ could be +fragile, and also you will need to avoid excluding the very first +opening transaction, which can be awkward. Here is a way to do it, +using tags: add ‘clopen:’ tags to all opening/closing balances +transactions except the first, like this: + +; 2021.journal +2021-06-01 first opening balances +... +2021-12-31 closing balances ; clopen:2022 +... + +; 2022.journal +2022-01-01 opening balances ; clopen:2022 +... +2022-12-31 closing balances ; clopen:2023 +... + +; 2023.journal +2023-01-01 opening balances ; clopen:2023 +... + + Now, assuming a combined journal like: + +; all.journal +include 2021.journal +include 2022.journal +include 2023.journal + + The ‘clopen:’ tag can exclude all but the first opening transaction. +To show a clean multi-year checking register: + +$ hledger -f all.journal areg checking not:tag:clopen + + And the year values allow more precision. To show 2022’s year-end +balance sheet: + +$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 + + +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS + +24.12 codes +=========== + +List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction’s code field, in +the order transactions were parsed. The transaction code is an optional +value written in parentheses between the date and description, often +used to store a cheque number, order number or similar. + + Transactions aren’t required to have a code, and missing or empty +codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they +will be printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + +2022/1/1 (123) Supermarket + Food $5.00 + Checking + +2022/1/2 (124) Post Office + Postage $8.32 + Checking + +2022/1/3 Supermarket + Food $11.23 + Checking + +2022/1/4 (126) Post Office + Postage $3.21 + Checking + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + +126 + + +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS + +24.13 commodities +================= + +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS + +24.14 descriptions +================== + +List the unique descriptions that appear in transactions. + + This command lists the unique descriptions that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. + + Example: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS + +24.15 diff +========== + +Compares a particular account’s transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + + More precisely, for each posting affecting this account in either +file, it looks for a corresponding posting in the other file which posts +the same amount to the same account (ignoring date, description, etc.) +Since postings not transactions are compared, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This is useful eg if you have downloaded an account’s transactions +from your bank (eg as CSV data). When hledger and your bank disagree +about the account balance, you can compare the bank data with your +journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS + +24.16 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: PART 4 COMMANDS + +24.17 help +========== + +Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a +pager. With a TOPIC argument, open it at that topic if possible. TOPIC +can be any heading in the manual, or a heading prefix, case insensitive. +Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto +postings"’. + + This command shows the hledger manual built in to your hledger +version. It can be useful when offline, or when you prefer the terminal +to a web browser, or when the appropriate hledger manual or viewing +tools are not installed on your system. + + By default it chooses the best viewer found in $PATH (preferring info +since the hledger manual is large). You can select a particular viewer +with the ‘-i’, ‘-m’, or ‘-p’ flags. + + Examples + +$ hledger help --help # show how the help command works +$ hledger help # show the hledger manual with info, man or $PAGER +$ hledger help journal # show the journal topic in the hledger manual + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS + +24.18 import +============ + +Read new transactions added to each FILE since last run, and add them to +the journal. Or with –dry-run, just print the transactions that would +be added. Or with –catchup, just mark all of the FILEs’ transactions as +imported, without actually importing any. + + This command may append new transactions to the main journal file +(which should be in journal format). Existing transactions are not +changed. This is one of the few hledger commands that writes to the +journal file (see also ‘add’). + + Unlike other hledger commands, with ‘import’ the journal file is an +output file, and will be modified, though only by appending (existing +data will not be changed). The input files are specified as arguments, +so to import one or more CSV files to your main journal, you will run +‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’. + + Note you can import from any file format, though CSV files are the +most common import source, and these docs focus on that case. + +* Menu: + +* Deduplication:: +* Import testing:: +* Importing balance assignments:: +* Commodity display styles:: + + +File: hledger.info, Node: Deduplication, Next: Import testing, Up: import + +24.18.1 Deduplication +--------------------- + +As a convenience ‘import’ does _deduplication_ while reading +transactions. This does not mean "ignore transactions that look the +same", but rather "ignore transactions that have been seen before". +This is intended for when you are periodically importing foreign data +which may contain already-imported transactions. So eg, if every day +you download bank CSV files containing redundant data, you can safely +run ‘hledger import bank.csv’ and only new transactions will be +imported. (‘import’ is idempotent.) + + Since the items being read (CSV records, eg) often do not come with +unique identifiers, hledger detects new transactions by date, assuming +that: + + 1. new items always have the newest dates + 2. item dates do not change across reads + 3. and items with the same date remain in the same relative order + across reads. + + These are often true of CSV files representing transactions, or true +enough so that it works pretty well in practice. 1 is important, but +violations of 2 and 3 amongst the old transactions won’t matter (and if +you import often, the new transactions will be few, so less likely to be +the ones affected). + + hledger remembers the latest date processed in each input file by +saving a hidden ".latest" state file in the same directory. Eg when +reading ‘finance/bank.csv’, it will look for and update the +‘finance/.latest.bank.csv’ state file. The format is simple: one or +more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I +have processed transactions up to this date, and this many of them on +that date." Normally you won’t see or manipulate these state files +yourself. But if needed, you can delete them to reset the state (making +all transactions "new"), or you can construct them to "catch up" to a +certain date. + + Note deduplication (and updating of state files) can also be done by +‘print --new’, but this is less often used. + + +File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import + +24.18.2 Import testing +---------------------- + +With ‘--dry-run’, the transactions that will be imported are printed to +the terminal, without updating your journal or state files. The output +is valid journal format, like the print command, so you can re-parse it. +Eg, to see any importable transactions which CSV rules have not +categorised: + +$ hledger import --dry bank.csv | hledger -f- -I print unknown + + or (live updating): + +$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' + + Note: when importing from multiple files at once, it’s currently +possible for some .latest files to be updated successfully, while the +actual import fails because of a problem in one of the files, leaving +them out of sync (and causing some transactions to be missed). To +prevent this, do a –dry-run first and fix any problems before the real +import. + + +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import + +24.18.3 Importing balance assignments +------------------------------------- + +Entries added by import will have their posting amounts made explicit +(like ‘hledger print -x’). This means that any balance assignments in +imported files must be evaluated; but, imported files don’t get to see +the main file’s account balances. As a result, importing entries with +balance assignments (eg from an institution that provides only balances +and not posting amounts) will probably generate incorrect posting +amounts. To avoid this problem, use print instead of import: + +$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE + + (If you think import should leave amounts implicit like print does, +please test it and send a pull request.) + + +File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import + +24.18.4 Commodity display styles +-------------------------------- + +Imported amounts will be formatted according to the canonical commodity +styles (declared or inferred) in the main journal file. + + +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS + +24.19 incomestatement +===================== + +(is) + + This command displays an income statement, showing revenues and +expenses during one or more periods. Amounts are shown with normal +positive sign, as in conventional financial statements. + + This report shows accounts declared with the ‘Revenue’ or ‘Expense’ +type (see account types). Or if no such accounts are declared, it shows +top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case +insensitive, plurals allowed) and their subaccounts. + + Example: + +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the ‘balance’ command, and +supports many of that command’s features, such as multi-period reports. +It is similar to ‘hledger balance '(revenues|income)' expenses’, but +with smarter account detection, and revenues/income displayed with their +sign flipped. + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, ‘html’, and +(experimental) ‘json’. + + +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS + +24.20 notes +=========== + +List the unique notes that appear in transactions. + + This command lists the unique notes that appear in transactions, in +alphabetic order. You can add a query to select a subset of +transactions. The note is the part of the transaction description after +a | character (or if there is no |, the whole description). + + Example: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS + +24.21 payees +============ + +List the unique payee/payer names that appear in transactions. + + This command lists unique payee/payer names which have been declared +with payee directives (–declared), used in transaction descriptions +(–used), or both (the default). + + The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). + + You can add query arguments to select a subset of transactions. This +implies –used. + + Example: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS + +24.22 prices +============ + +Print market price directives from the journal. With +–infer-market-prices, generate additional market prices from costs. +With –infer-reverse-prices, also generate market prices by inverting +known prices. Prices can be filtered by a query. Price amounts are +displayed with their full precision. + + +File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS + +24.23 print +=========== + +Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from +the journal file, sorted by date (or with ‘--date2’, by secondary date). + + Amounts are shown mostly normalised to commodity display style, eg +the placement of commodity symbols will be consistent. All of their +decimal places are shown, as in the original journal entry (with one +alteration: in some cases trailing zeroes are added.) + + Amounts are shown right-aligned within each transaction (but not +across all transactions). + + Directives and inter-transaction comments are not shown, currently. +This means the print command is somewhat lossy, and if you are using it +to reformat your journal you should take care to also copy over the +directives and file-level comments. + + Eg: + +$ 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 + + print’s output is usually a valid hledger journal, and you can +process it again with a second hledger command. This can be useful for +certain kinds of search, eg: + +# Show running total of food expenses paid from cash. +# -f- reads from stdin. -I/--ignore-assertions is sometimes needed. +$ hledger print assets:cash | hledger -f- -I reg expenses:food + + There are some situations where print’s output can become +unparseable: + + • Valuation affects posting amounts but not balance assertion or + balance assignment amounts, potentially causing those to fail. + • Auto postings can generate postings with too many missing amounts. + • Account aliases can generate bad account names. + + Normally, the journal entry’s explicit or implicit amount style is +preserved. For example, when an amount is omitted in the journal, it +will not appear in the output. Similarly, when a cost is implied but +not written, it will not appear in the output. You can use the +‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can +be useful for troubleshooting or for making your journal more readable +and robust against data entry errors. ‘-x’ is also implied by using any +of ‘-B’,‘-V’,‘-X’,‘--value’. + + Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity +amount (these can arise when a multi-commodity transaction has an +implicit amount) to be split into multiple single-commodity postings, +keeping the output parseable. + + With ‘-B’/‘--cost’, amounts with costs are converted to cost using +that price. This can be used for troubleshooting. + + With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one +recent transaction whose description is most similar to DESC. DESC +should contain at least two characters. If there is no similar-enough +match, no transaction will be shown and the program exit code will be +non-zero. + + With ‘--new’, hledger prints only transactions it has not seen on a +previous run. This uses the same deduplication system as the ‘import’ +command. (See import’s docs for details.) + + This command also supports the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, and +(experimental) ‘json’ and ‘sql’. + + 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: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS + +24.24 register +============== + +(reg) + + Show postings and their running total. + + The register command displays matched postings, across all accounts, +in date order, with their running total or running historical balance. +(See also the ‘aregister’ command, which shows matched transactions in a +specific account.) + + register normally shows line per posting, but note that +multi-commodity amounts will occupy multiple lines (one line per +commodity). + + It 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. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +‘--align-all’ flag. + + 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. + + The ‘--invert’ flag negates all amounts. For example, it can be used +on an income account where amounts are normally displayed as negative +numbers. It’s also useful to show postings on the checking account +together with the related account: + +$ hledger register --related --invert assets:checking + + 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. + + With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one +recent posting whose description is most similar to DESC. DESC should +contain at least two characters. If there is no similar-enough match, +no posting will be shown and the program exit code will be non-zero. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +24.24.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 the output destination and output format +options The output formats supported are ‘txt’, ‘csv’, and +(experimental) ‘json’. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS + +24.25 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:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +24.25.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. + + +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite + +24.25.2 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: rewrite + +24.25.3 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: PART 4 COMMANDS + +24.26 roi +========= + +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + + At a minimum, you need to supply a query (which could be just an +account name) to select your investment(s) with ‘--inv’, and another +query to identify your profit and loss transactions with ‘--pnl’. + + If you do not record changes in the value of your investment +manually, or do not require computation of time-weighted return (TWR), +‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’ +does not match any of your accounts). + + This command 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. + + Price directives will be taken into account if you supply appropriate +‘--cost’ or ‘--value’ flags (see VALUATION). + + Note, in some cases this report can fail, for these reasons: + + • Error (NotBracketed): No solution for Internal Rate of Return + (IRR). Possible causes: IRR is huge (>1000000%), balance of + investment becomes negative at some point in time. + • Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or + converges too slowly. + + Examples: + + • Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger + + • Cookbook > Return on Investment: https://hledger.org/roi.html + +* Menu: + +* Spaces and special characters in --inv and --pnl:: +* Semantics of --inv and --pnl:: +* IRR and TWR explained:: + + +File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi + +24.26.1 Spaces and special characters in ‘--inv’ and +---------------------------------------------------- + +‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries +could have several space-separated terms (see QUERIES). + + To indicate that all search terms form single command-line argument, +you will need to put them in quotes (see Special characters): + +$ hledger roi --inv 'term1 term2 term3 ...' + + If any query terms contain spaces themselves, you will need an extra +level of nested quoting, eg: + +$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" + + +File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi + +24.26.2 Semantics of ‘--inv’ and ‘--pnl’ +---------------------------------------- + +Query supplied to ‘--inv’ has to match all transactions that are related +to your investment. Transactions not matching ‘--inv’ will be ignored. + + In these transactions, ROI will conside postings that match ‘--inv’ +to be "investment postings" and other postings (not matching ‘--inv’) +will be sorted into two categories: "cash flow" and "profit and loss", +as ROI needs to know which part of the investment value is your +contributions and which is due to the return on investment. + + • "Cash flow" is depositing or withdrawing money, buying or selling + assets, or otherwise converting between your investment commodity + and any other commodity. Example: + + 2019-01-01 Investing in Snake Oil + assets:cash -$100 + investment:snake oil + + 2020-01-01 Selling my Snake Oil + assets:cash $10 + investment:snake oil = 0 + + • "Profit and loss" is change in the value of your investment: + + 2019-06-01 Snake Oil falls in value + investment:snake oil = $57 + equity:unrealized profit or loss + + All non-investment postings are assumed to be "cash flow", unless +they match ‘--pnl’ query. Changes in value of your investment due to +"profit and loss" postings will be considered as part of your investment +return. + + Example: if you use ‘--inv snake --pnl equity:unrealized’, then +postings in the example below would be classifed as: + +2019-01-01 Snake Oil #1 + assets:cash -$100 ; cash flow posting + investment:snake oil ; investment posting + +2019-03-01 Snake Oil #2 + equity:unrealized pnl -$100 ; profit and loss posting + snake oil ; investment posting + +2019-07-01 Snake Oil #3 + equity:unrealized pnl ; profit and loss posting + cash -$100 ; cash flow posting + snake oil $50 ; investment posting + + +File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi + +24.26.3 IRR and TWR explained +----------------------------- + +"ROI" stands for "return on investment". Traditionally this was +computed as a difference between current value of investment and its +initial value, expressed in percentage of the initial value. + + However, this approach is only practical in simple cases, where +investments receives no in-flows or out-flows of money, and where rate +of growth is fixed over time. For more complex scenarios you need +different ways to compute rate of return, and this command implements +two of them: IRR and TWR. + + Internal rate of return, or "IRR" (also called "money-weighted rate +of return") takes into account effects of in-flows and out-flows. +Naively, if you are withdrawing from your investment, your future gains +would be smaller (in absolute numbers), and will be a smaller percentage +of your initial investment, and if you are adding to your investment, +you will receive bigger absolute gains (but probably at the same rate of +return). IRR is a way to compute rate of return for each period between +in-flow or out-flow of money, and then combine them in a way that gives +you a compound annual rate of return that investment is expected to +generate. + + As mentioned before, in-flows and out-flows would be any cash that +you personally put in or withdraw, and for the "roi" command, these are +the postings that match the query in the‘--inv’ argument and NOT match +the query in the‘--pnl’ argument. + + If you manually record changes in the value of your investment as +transactions that balance them against "profit and loss" (or "unrealized +gains") account or use price directives, then in order for IRR to +compute the precise effect of your in-flows and out-flows on the rate of +return, you will need to record the value of your investement on or +close to the days when in- or out-flows occur. + + In technical terms, IRR uses the same approach as computation of net +present value, and tries to find a discount rate that makes net present +value of all the cash flows of your investment to add up to zero. This +could be hard to wrap your head around, especially if you haven’t done +discounted cash flow analysis before. Implementation of IRR in hledger +should produce results that match the ‘XIRR’ formula in Excel. + + Second way to compute rate of return that ‘roi’ command implements is +called "time-weighted rate of return" or "TWR". Like IRR, it will also +break the history of your investment into periods between in-flows, +out-flows and value changes, to compute rate of return per each period +and then a compound rate of return. However, internal workings of TWR +are quite different. + + TWR represents your investment as an imaginary "unit fund" where +in-flows/ out-flows lead to buying or selling "units" of your investment +and changes in its value change the value of "investment unit". Change +in "unit price" over the reporting period gives you rate of return of +your investment. + + References: + + • Explanation of rate of return + • Explanation of IRR + • Explanation of TWR + • Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS + +24.27 stats +=========== + +Show journal and performance 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. + + At the end, it shows (in the terminal) the overall run time and +number of transactions processed per second. Note these are approximate +and will vary based on machine, current load, data size, hledger +version, haskell lib versions, GHC version.. but they may be of +interest. The ‘stats’ command’s run time is similar to that of a +single-column balance report. + + Example: + +$ hledger stats -f examples/1000x1000x10.journal +Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal +Included files : +Transactions span : 2000-01-01 to 2002-09-27 (1000 days) +Last transaction : 2002-09-26 (6995 days ago) +Transactions : 1000 (1.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) +Market prices : 1000 (A) + +Run time : 0.12 s +Throughput : 8342 txns/s + + This command supports the -o/–output-file option (but not +-O/–output-format selection). + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS + +24.28 tags +========== + +List the tags used in the journal, or their values. + + This command lists the tag names used in the journal, whether on +transactions, postings, or account declarations. + + With a TAGREGEX argument, only tag names matching this regular +expression (case insensitive, infix matched) are shown. + + With QUERY arguments, only transactions and accounts matching this +query are considered. If the query involves transaction fields (date:, +desc:, amt:, ...), the search is restricted to the matched transactions +and their accounts. + + With the –values flag, the tags’ unique non-empty values are listed +instead. With -E/–empty, blank/empty values are also shown. + + With –parsed, tags or values are shown in the order they were parsed, +with duplicates included. (Except, tags from account declarations are +always shown first.) + + Tip: remember, accounts also acquire tags from their parents, +postings also acquire tags from their account and transaction, +transactions also acquire tags from their postings. + + +File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS + +24.29 test +========== + +Run built-in unit tests. + + This command runs the unit tests built in to hledger and hledger-lib, +printing the results on stdout. If any test fails, the exit code will +be non-zero. + + This is mainly used by hledger developers, but you can also use it to +sanity-check the installed hledger executable on your platform. All +tests are expected to pass - if you ever see a failure, please report as +a bug! + + This command also accepts tasty test runner options, written after a +– (double hyphen). Eg to run only the tests in Hledger.Data.Amount, +with ANSI colour codes disabled: + +$ hledger test -- -pData.Amount --color=never + + For help on these, see https://github.com/feuerbach/tasty#options +(‘-- --help’ currently doesn’t show them). + + +File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top + +25 PART 5: COMMON TASKS +*********************** + +Here are some quick examples of how to do some basic tasks with hledger. + +* Menu: + +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file:: + + +File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS + +25.1 Getting help +================= + +Here’s how to list commands and view options and command docs: + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version’s manual in several formats by +using the help command. Eg: + +$ hledger help # show the hledger manual with info, man or $PAGER (best available) +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit +https://hledger.org. Chat and mail list support and discussion archives +can be found at https://hledger.org/support. + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS + +25.2 Constructing command lines +=============================== + +hledger has a flexible command line interface. We strive to keep it +simple and ergonomic, but if you run into one of the sharp edges +described in OPTIONS, here are some tips that might help: + + • command-specific options must go after the command (it’s fine to + put common options there too: ‘hledger CMD OPTS ARGS’) + • running add-on executables directly simplifies command line parsing + (‘hledger-ui OPTS ARGS’) + • enclose "problematic" args in single quotes + • if needed, also add a backslash to hide regular expression + metacharacters from the shell + • to see how a misbehaving command line is being parsed, add + ‘--debug=2’. + + +File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS + +25.3 Starting a journal file +============================ + +hledger looks for your accounting data in a journal file, +‘$HOME/.hledger.journal’ by default: + +$ hledger stats +The hledger journal file "/Users/simon/.hledger.journal" was not found. +Please create it first, eg with "hledger add" or a text editor. +Or, specify an existing journal file with -f or LEDGER_FILE. + + You can override this by setting the ‘LEDGER_FILE’ environment +variable. It’s a good practice to keep this important file under +version control, and to start a new file each year. So you could do +something like this: + +$ mkdir ~/finance +$ cd ~/finance +$ git init +Initialized empty Git repository in /Users/simon/finance/.git/ +$ touch 2020.journal +$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc +$ source ~/.bashrc +$ hledger stats +Main file : /Users/simon/finance/2020.journal +Included files : +Transactions span : to (0 days) +Last transaction : none +Transactions : 0 (0.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 0 +Accounts : 0 (depth 0) +Commodities : 0 () +Market prices : 0 () + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS + +25.4 Setting opening balances +============================= + +Pick a starting date for which you can look up the balances of some +real-world assets (bank accounts, wallet..) and liabilities (credit +cards..). + + To avoid a lot of data entry, you may want to start with just one or +two accounts, like your checking account or cash wallet; and pick a +recent starting date, like today or the start of the week. You can +always come back later and add more accounts and older transactions, eg +going back to january 1st. + + Add an opening balances transaction to the journal, declaring the +balances on this date. Here are two ways to do it: + + • The first way: open the journal in any text editor and save an + entry like this: + + 2020-01-01 * opening balances + assets:bank:checking $1000 = $1000 + assets:bank:savings $2000 = $2000 + assets:cash $100 = $100 + liabilities:creditcard $-50 = $-50 + equity:opening/closing balances + + These are start-of-day balances, ie whatever was in the account at + the end of the previous day. + + The * after the date is an optional status flag. Here it means + "cleared & confirmed". + + The currency symbols are optional, but usually a good idea as + you’ll be dealing with multiple currencies sooner or later. + + The = amounts are optional balance assertions, providing extra + error checking. + + • The second way: run ‘hledger add’ and follow the prompts to record + a similar transaction: + + $ hledger add + Adding transactions to journal file /Users/simon/finance/2020.journal + 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 go one step backward. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2020-02-07]: 2020-01-01 + Description: * opening balances + Account 1: assets:bank:checking + Amount 1: $1000 + Account 2: assets:bank:savings + Amount 2 [$-1000]: $2000 + Account 3: assets:cash + Amount 3 [$-3000]: $100 + Account 4: liabilities:creditcard + Amount 4 [$-3100]: $-50 + Account 5: equity:opening/closing balances + Amount 5 [$-3050]: + Account 6 (or . or enter to finish this transaction): . + 2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2020-01-01]: . + + If you’re using version control, this could be a good time to commit +the journal. Eg: + +$ git commit -m 'initial balances' 2020.journal + + +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS + +25.5 Recording transactions +=========================== + +As you spend or receive money, you can record these transactions using +one of the methods above (text editor, hledger add) or by using the +hledger-iadd or hledger-web add-ons, or by using the import command to +convert CSV data downloaded from your bank. + + Here are some simple transactions, see the hledger_journal(5) manual +and hledger.org for more ideas: + +2020/1/10 * gift received + assets:cash $20 + income:gifts + +2020.1.12 * farmers market + expenses:food $13 + assets:cash + +2020-01-15 paycheck + income:salary + assets:bank:checking $1000 + + +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS + +25.6 Reconciling +================ + +Periodically you should reconcile - compare your hledger-reported +balances against external sources of truth, like bank statements or your +bank’s website - to be sure that your ledger accurately represents the +real-world balances (and, that the real-world institutions have not made +a mistake!). This gets easy and fast with (1) practice and (2) +frequency. If you do it daily, it can take 2-10 minutes. If you let it +pile up, expect it to take longer as you hunt down errors and +discrepancies. + + A typical workflow: + + 1. Reconcile cash. Count what’s in your wallet. Compare with what + hledger reports (‘hledger bal cash’). If they are different, try + to remember the missing transaction, or look for the error in the + already-recorded transactions. A register report can be helpful + (‘hledger reg cash’). If you can’t find the error, add an + adjustment transaction. Eg if you have $105 after the above, and + can’t explain the missing $2, it could be: + + 2020-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + 2. Reconcile checking. Log in to your bank’s website. Compare + today’s (cleared) balance with hledger’s cleared balance (‘hledger + bal checking -C’). If they are different, track down the error or + record the missing transaction(s) or add an adjustment transaction, + similar to the above. Unlike the cash case, you can usually + compare the transaction history and running balance from your bank + with the one reported by ‘hledger reg checking -C’. This will be + easier if you generally record transaction dates quite similar to + your bank’s clearing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a +live-updating register while you edit the journal: ‘hledger-ui --watch +--register checking -C’ + + After reconciling, it could be a good time to mark the reconciled +transactions’ status as "cleared and confirmed", if you want to track +that, by adding the ‘*’ marker. Eg in the paycheck transaction above, +insert ‘*’ between ‘2020-01-15’ and ‘paycheck’ + + If you’re using version control, this can be another good time to +commit: + +$ git commit -m 'txns' 2020.journal + + +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS + +25.7 Reporting +============== + +Here are some basic reports. + + Show all transactions: + +$ hledger print +2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +2020-01-10 * gift received + assets:cash $20 + income:gifts + +2020-01-12 * farmers market + expenses:food $13 + assets:cash + +2020-01-15 * paycheck + income:salary + assets:bank:checking $1000 + +2020-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + +$ hledger accounts --tree +assets + bank + checking + savings + cash +equity + opening/closing balances +expenses + food + misc +income + gifts + salary +liabilities + creditcard + + Show all account totals: + +$ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard +-------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to +depth 2: + +$ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard +-------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple +balance sheet: + +$ hledger bs -2 +Balance Sheet 2020-01-16 + + || 2020-01-16 +========================++============ + Assets || +------------------------++------------ + assets:bank || $4000 + assets:cash || $105 +------------------------++------------ + || $4105 +========================++============ + Liabilities || +------------------------++------------ + liabilities:creditcard || $50 +------------------------++------------ + || $50 +========================++============ + Net: || $4055 + + The final total is your "net worth" on the end date. (Or use ‘bse’ +for a full balance sheet with equity.) + + Show income and expense totals, formatted as an income statement: + +hledger is +Income Statement 2020-01-01-2020-01-16 + + || 2020-01-01-2020-01-16 +===============++======================= + Revenues || +---------------++----------------------- + income:gifts || $20 + income:salary || $1000 +---------------++----------------------- + || $1020 +===============++======================= + Expenses || +---------------++----------------------- + expenses:food || $13 + expenses:misc || $2 +---------------++----------------------- + || $15 +===============++======================= + Net: || $1005 + + The final total is your net income during this period. + + Show transactions affecting your wallet, with running total: + +$ hledger register cash +2020-01-01 opening balances assets:cash $100 $100 +2020-01-10 gift received assets:cash $20 $120 +2020-01-12 farmers market assets:cash $-13 $107 +2020-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + +$ hledger activity -W +2019-12-30 ***** +2020-01-06 **** +2020-01-13 **** + + +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS + +25.8 Migrating to a new file +============================ + +At the end of the year, you may want to continue your journal in a new +file, so that old transactions don’t slow down or clutter your reports, +and to help ensure the integrity of your accounting history. See the +close command. + + If using version control, don’t forget to ‘git add’ the new file. + + +Tag Table: +Node: Top210 +Node: PART 1 USER INTERFACE3946 +Ref: #part-1-user-interface4087 +Node: Options4087 +Ref: #options4206 +Node: General options4348 +Ref: #general-options4473 +Node: Command options8923 +Ref: #command-options9074 +Node: Command arguments9490 +Ref: #command-arguments9648 +Node: Special characters10550 +Ref: #special-characters10713 +Node: Single escaping shell metacharacters10876 +Ref: #single-escaping-shell-metacharacters11117 +Node: Double escaping regular expression metacharacters11752 +Ref: #double-escaping-regular-expression-metacharacters12063 +Node: Triple escaping for add-on commands12633 +Ref: #triple-escaping-for-add-on-commands12893 +Node: Less escaping13561 +Ref: #less-escaping13715 +Node: Unicode characters14053 +Ref: #unicode-characters14218 +Node: Regular expressions15650 +Ref: #regular-expressions15790 +Node: Environment17644 +Ref: #environment17755 +Node: Input19366 +Ref: #input19466 +Node: Data formats20029 +Ref: #data-formats20142 +Node: Multiple files21594 +Ref: #multiple-files21731 +Node: Strict mode22216 +Ref: #strict-mode22326 +Node: Commands23080 +Ref: #commands23181 +Node: Add-on commands23665 +Ref: #add-on-commands23767 +Node: Output24934 +Ref: #output25037 +Node: Output destination25153 +Ref: #output-destination25284 +Node: Output format25713 +Ref: #output-format25859 +Node: CSV output27431 +Ref: #csv-output27547 +Node: HTML output27652 +Ref: #html-output27790 +Node: JSON output27890 +Ref: #json-output28028 +Node: SQL output28960 +Ref: #sql-output29076 +Node: Commodity styles29599 +Ref: #commodity-styles29739 +Node: Colour30346 +Ref: #colour30464 +Node: Box-drawing30898 +Ref: #box-drawing31022 +Node: Debug output31336 +Ref: #debug-output31447 +Node: Limitations32122 +Ref: #limitations32242 +Node: Troubleshooting33017 +Ref: #troubleshooting33158 +Node: PART 2 DATA FORMATS35680 +Ref: #part-2-data-formats35827 +Node: Journal35827 +Ref: #journal35938 +Node: Journal cheatsheet36581 +Ref: #journal-cheatsheet36722 +Node: About journal format40710 +Ref: #about-journal-format40872 +Node: Comments42410 +Ref: #comments42542 +Node: Transactions43396 +Ref: #transactions43521 +Node: Dates44555 +Ref: #dates44664 +Node: Simple dates44709 +Ref: #simple-dates44827 +Node: Posting dates45359 +Ref: #posting-dates45479 +Node: Status46462 +Ref: #status46565 +Node: Code48317 +Ref: #code48422 +Node: Description48654 +Ref: #description48787 +Node: Payee and note49109 +Ref: #payee-and-note49217 +Node: Transaction comments49564 +Ref: #transaction-comments49719 +Node: Postings50090 +Ref: #postings50225 +Node: Account names51234 +Ref: #account-names51366 +Node: Amounts53068 +Ref: #amounts53185 +Node: Decimal marks digit group marks54174 +Ref: #decimal-marks-digit-group-marks54351 +Node: Commodity55375 +Ref: #commodity55564 +Node: Directives influencing number parsing and display56546 +Ref: #directives-influencing-number-parsing-and-display56807 +Node: Commodity display style57269 +Ref: #commodity-display-style57477 +Node: Rounding59688 +Ref: #rounding59808 +Node: Costs60109 +Ref: #costs60227 +Node: Other cost/lot notations62258 +Ref: #other-costlot-notations62392 +Node: Balance assertions65145 +Ref: #balance-assertions65298 +Node: Assertions and ordering66391 +Ref: #assertions-and-ordering66582 +Node: Assertions and multiple included files67284 +Ref: #assertions-and-multiple-included-files67546 +Node: Assertions and multiple -f files68054 +Ref: #assertions-and-multiple--f-files68307 +Node: Assertions and commodities68716 +Ref: #assertions-and-commodities68940 +Node: Assertions and prices70130 +Ref: #assertions-and-prices70338 +Node: Assertions and subaccounts70769 +Ref: #assertions-and-subaccounts70992 +Node: Assertions and virtual postings71334 +Ref: #assertions-and-virtual-postings71574 +Node: Assertions and auto postings71714 +Ref: #assertions-and-auto-postings71946 +Node: Assertions and precision72617 +Ref: #assertions-and-precision72801 +Node: Posting comments73068 +Ref: #posting-comments73216 +Node: Tags73601 +Ref: #tags73717 +Node: Tag values74922 +Ref: #tag-values75013 +Node: Directives75786 +Ref: #directives75915 +Node: Directive effects77783 +Ref: #directive-effects77939 +Node: Directives and multiple files81022 +Ref: #directives-and-multiple-files81202 +Node: account directive81912 +Ref: #account-directive82074 +Node: Account comments83494 +Ref: #account-comments83646 +Node: Account subdirectives84166 +Ref: #account-subdirectives84359 +Node: Account error checking84501 +Ref: #account-error-checking84701 +Node: Account display order85920 +Ref: #account-display-order86110 +Node: Account types87249 +Ref: #account-types87392 +Node: alias directive91127 +Ref: #alias-directive91294 +Node: Basic aliases92354 +Ref: #basic-aliases92487 +Node: Regex aliases93241 +Ref: #regex-aliases93400 +Node: Combining aliases94294 +Ref: #combining-aliases94474 +Node: Aliases and multiple files95768 +Ref: #aliases-and-multiple-files95974 +Node: end aliases directive96559 +Ref: #end-aliases-directive96784 +Node: Aliases can generate bad account names96933 +Ref: #aliases-can-generate-bad-account-names97183 +Node: Aliases and account types97780 +Ref: #aliases-and-account-types97974 +Node: commodity directive98676 +Ref: #commodity-directive98856 +Node: Commodity error checking101460 +Ref: #commodity-error-checking101608 +Node: decimal-mark directive102137 +Ref: #decimal-mark-directive102325 +Node: include directive102726 +Ref: #include-directive102896 +Node: P directive103844 +Ref: #p-directive103995 +Node: payee directive104894 +Ref: #payee-directive105049 +Node: tag directive105369 +Ref: #tag-directive105530 +Node: Periodic transactions106002 +Ref: #periodic-transactions106168 +Node: Periodic rule syntax107906 +Ref: #periodic-rule-syntax108086 +Node: Periodic rules and relative dates108741 +Ref: #periodic-rules-and-relative-dates109009 +Node: Two spaces between period expression and description!109548 +Ref: #two-spaces-between-period-expression-and-description109827 +Node: Other syntax110517 +Ref: #other-syntax110643 +Node: Auto postings111288 +Ref: #auto-postings111424 +Node: Auto postings and multiple files113935 +Ref: #auto-postings-and-multiple-files114137 +Node: Auto postings and dates114354 +Ref: #auto-postings-and-dates114626 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions114801 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115140 +Node: Auto posting tags115647 +Ref: #auto-posting-tags115860 +Node: Balance assignments116522 +Ref: #balance-assignments116702 +Node: Balance assignments and prices118036 +Ref: #balance-assignments-and-prices118206 +Node: Bracketed posting dates118417 +Ref: #bracketed-posting-dates118603 +Node: D directive119147 +Ref: #d-directive119321 +Node: apply account directive120989 +Ref: #apply-account-directive121175 +Node: Y directive121874 +Ref: #y-directive122040 +Node: Secondary dates122884 +Ref: #secondary-dates123040 +Node: Star comments123872 +Ref: #star-comments124034 +Node: Valuation expressions124574 +Ref: #valuation-expressions124753 +Node: Virtual postings124875 +Ref: #virtual-postings125056 +Node: Other Ledger directives126628 +Ref: #other-ledger-directives126793 +Node: CSV127363 +Ref: #csv127456 +Node: CSV rules cheatsheet129559 +Ref: #csv-rules-cheatsheet129691 +Node: separator131459 +Ref: #separator131590 +Node: skip132168 +Ref: #skip132280 +Node: date-format132863 +Ref: #date-format132988 +Node: timezone133734 +Ref: #timezone133861 +Node: newest-first134894 +Ref: #newest-first135036 +Node: intra-day-reversed135620 +Ref: #intra-day-reversed135778 +Node: decimal-mark136275 +Ref: #decimal-mark136420 +Node: fields list136759 +Ref: #fields-list136900 +Node: Field assignment138623 +Ref: #field-assignment138767 +Node: Field names139816 +Ref: #field-names139947 +Node: date field141168 +Ref: #date-field141286 +Node: date2 field141338 +Ref: #date2-field141479 +Node: status field141541 +Ref: #status-field141684 +Node: code field141739 +Ref: #code-field141884 +Node: description field141935 +Ref: #description-field142095 +Node: comment field142160 +Ref: #comment-field142315 +Node: account field142628 +Ref: #account-field142778 +Node: amount field143374 +Ref: #amount-field143523 +Node: currency field145628 +Ref: #currency-field145781 +Node: balance field146050 +Ref: #balance-field146182 +Node: if block146570 +Ref: #if-block146695 +Node: Matchers148119 +Ref: #matchers148233 +Node: if table149763 +Ref: #if-table149889 +Node: balance-type151325 +Ref: #balance-type151458 +Node: include152166 +Ref: #include152297 +Node: Working with CSV152747 +Ref: #working-with-csv152894 +Node: Rapid feedback153265 +Ref: #rapid-feedback153398 +Node: Valid CSV153854 +Ref: #valid-csv154000 +Node: File Extension154754 +Ref: #file-extension154927 +Node: Reading CSV from standard input155517 +Ref: #reading-csv-from-standard-input155741 +Node: Reading multiple CSV files155907 +Ref: #reading-multiple-csv-files156125 +Node: Valid transactions156374 +Ref: #valid-transactions156568 +Node: Deduplicating importing157196 +Ref: #deduplicating-importing157391 +Node: Setting amounts158437 +Ref: #setting-amounts158608 +Node: Amount signs161131 +Ref: #amount-signs161299 +Node: Setting currency/commodity162038 +Ref: #setting-currencycommodity162242 +Node: Amount decimal places163434 +Ref: #amount-decimal-places163640 +Node: Referencing other fields163958 +Ref: #referencing-other-fields164171 +Node: How CSV rules are evaluated165074 +Ref: #how-csv-rules-are-evaluated165291 +Node: Well factored rules166804 +Ref: #well-factored-rules166972 +Node: CSV rules examples167310 +Ref: #csv-rules-examples167445 +Node: Bank of Ireland167510 +Ref: #bank-of-ireland167647 +Node: Coinbase169115 +Ref: #coinbase169253 +Node: Amazon170306 +Ref: #amazon170431 +Node: Paypal172156 +Ref: #paypal172264 +Node: Timeclock179910 +Ref: #timeclock180015 +Node: Timedot182183 +Ref: #timedot182306 +Node: PART 3 REPORTING CONCEPTS187157 +Ref: #part-3-reporting-concepts187321 +Node: Time periods187321 +Ref: #time-periods187455 +Node: Report start & end date187573 +Ref: #report-start-end-date187725 +Node: Smart dates189458 +Ref: #smart-dates189611 +Node: Report intervals191571 +Ref: #report-intervals191726 +Node: Date adjustment192178 +Ref: #date-adjustment192338 +Node: Period expressions193670 +Ref: #period-expressions193811 +Node: Period expressions with a report interval195647 +Ref: #period-expressions-with-a-report-interval195881 +Node: More complex report intervals196111 +Ref: #more-complex-report-intervals196356 +Node: Multiple weekday intervals198285 +Ref: #multiple-weekday-intervals198474 +Node: Depth199338 +Ref: #depth199440 +Node: Queries199760 +Ref: #queries199862 +Node: Query types200807 +Ref: #query-types200928 +Node: Combining query terms204268 +Ref: #combining-query-terms204445 +Node: Queries and command options205543 +Ref: #queries-and-command-options205742 +Node: Queries and valuation206007 +Ref: #queries-and-valuation206202 +Node: Querying with account aliases206441 +Ref: #querying-with-account-aliases206652 +Node: Querying with cost or value206794 +Ref: #querying-with-cost-or-value206971 +Node: Pivoting207280 +Ref: #pivoting207394 +Node: Generating data208882 +Ref: #generating-data209014 +Node: Forecasting209512 +Ref: #forecasting209637 +Node: Budgeting212524 +Ref: #budgeting212644 +Node: Cost reporting212915 +Ref: #cost-reporting213043 +Node: -B Convert to cost214158 +Ref: #b-convert-to-cost214314 +Node: Equity conversion postings215722 +Ref: #equity-conversion-postings215936 +Node: Inferring equity postings from cost216831 +Ref: #inferring-equity-postings-from-cost217080 +Node: Inferring cost from equity postings217899 +Ref: #inferring-cost-from-equity-postings218147 +Node: When to infer cost/equity219956 +Ref: #when-to-infer-costequity220174 +Node: How to record conversions220582 +Ref: #how-to-record-conversions220774 +Node: Conversion with implicit cost221065 +Ref: #conversion-with-implicit-cost221270 +Node: Conversion with explicit cost222175 +Ref: #conversion-with-explicit-cost222420 +Node: Conversion with equity postings222847 +Ref: #conversion-with-equity-postings223116 +Node: Conversion with equity postings and explicit cost223953 +Ref: #conversion-with-equity-postings-and-explicit-cost224220 +Node: Cost tips224694 +Ref: #cost-tips224820 +Node: Valuation225556 +Ref: #valuation225680 +Node: -V Value226466 +Ref: #v-value226592 +Node: -X Value in specified commodity226791 +Ref: #x-value-in-specified-commodity226986 +Node: Valuation date227143 +Ref: #valuation-date227314 +Node: Finding market price227753 +Ref: #finding-market-price227958 +Node: --infer-market-prices market prices from transactions229138 +Ref: #infer-market-prices-market-prices-from-transactions229416 +Node: Valuation commodity232262 +Ref: #valuation-commodity232475 +Node: Simple valuation examples233720 +Ref: #simple-valuation-examples233918 +Node: --value Flexible valuation234581 +Ref: #value-flexible-valuation234787 +Node: More valuation examples236473 +Ref: #more-valuation-examples236682 +Node: Interaction of valuation and queries238693 +Ref: #interaction-of-valuation-and-queries238934 +Node: Effect of valuation on reports239414 +Ref: #effect-of-valuation-on-reports239611 +Node: PART 4 COMMANDS247370 +Ref: #part-4-commands247513 +Node: Commands overview247883 +Ref: #commands-overview248017 +Node: DATA ENTRY248196 +Ref: #data-entry248320 +Node: DATA CREATION248523 +Ref: #data-creation248677 +Node: DATA MANAGEMENT248801 +Ref: #data-management248966 +Node: REPORTS FINANCIAL249091 +Ref: #reports-financial249266 +Node: REPORTS VERSATILE249581 +Ref: #reports-versatile249754 +Node: REPORTS BASIC250015 +Ref: #reports-basic250167 +Node: HELP250700 +Ref: #help250822 +Node: ADD-ONS250881 +Ref: #add-ons250987 +Node: accounts251584 +Ref: #accounts251717 +Node: activity253692 +Ref: #activity253811 +Node: add254185 +Ref: #add254295 +Node: aregister257156 +Ref: #aregister257277 +Node: aregister and custom posting dates260253 +Ref: #aregister-and-custom-posting-dates260419 +Node: balance260987 +Ref: #balance261113 +Node: balance features262118 +Ref: #balance-features262258 +Node: Simple balance report264388 +Ref: #simple-balance-report264573 +Node: Balance report line format266218 +Ref: #balance-report-line-format266420 +Node: Filtered balance report268670 +Ref: #filtered-balance-report268862 +Node: List or tree mode269189 +Ref: #list-or-tree-mode269357 +Node: Depth limiting270732 +Ref: #depth-limiting270898 +Node: Dropping top-level accounts271515 +Ref: #dropping-top-level-accounts271715 +Node: Showing declared accounts272029 +Ref: #showing-declared-accounts272228 +Node: Sorting by amount272769 +Ref: #sorting-by-amount272936 +Node: Percentages273626 +Ref: #percentages273785 +Node: Multi-period balance report274355 +Ref: #multi-period-balance-report274555 +Node: Balance change end balance276948 +Ref: #balance-change-end-balance277157 +Node: Balance report types278605 +Ref: #balance-report-types278786 +Node: Calculation type279302 +Ref: #calculation-type279457 +Node: Accumulation type279988 +Ref: #accumulation-type280168 +Node: Valuation type281096 +Ref: #valuation-type281284 +Node: Combining balance report types282351 +Ref: #combining-balance-report-types282545 +Node: Budget report284449 +Ref: #budget-report284601 +Node: Budget report start date290335 +Ref: #budget-report-start-date290513 +Node: Budgets and subaccounts291875 +Ref: #budgets-and-subaccounts292082 +Node: Selecting budget goals295568 +Ref: #selecting-budget-goals295767 +Node: Budget vs forecast296814 +Ref: #budget-vs-forecast296973 +Node: Data layout298673 +Ref: #data-layout298823 +Node: Useful balance reports306764 +Ref: #useful-balance-reports306914 +Node: balancesheet308067 +Ref: #balancesheet308212 +Node: balancesheetequity309578 +Ref: #balancesheetequity309736 +Node: cashflow311179 +Ref: #cashflow311310 +Node: check312796 +Ref: #check312910 +Node: Basic checks313716 +Ref: #basic-checks313836 +Node: Strict checks314374 +Ref: #strict-checks314517 +Node: Other checks314958 +Ref: #other-checks315100 +Node: Custom checks315677 +Ref: #custom-checks315834 +Node: More about specific checks316255 +Ref: #more-about-specific-checks316417 +Node: close317149 +Ref: #close317260 +Node: close and costs319898 +Ref: #close-and-costs320042 +Node: close and balance assertions320331 +Ref: #close-and-balance-assertions320533 +Node: Example retain earnings321704 +Ref: #example-retain-earnings321921 +Node: Example migrate balances to a new file322279 +Ref: #example-migrate-balances-to-a-new-file322544 +Node: Example excluding closing/opening transactions323097 +Ref: #example-excluding-closingopening-transactions323346 +Node: codes324524 +Ref: #codes324641 +Node: commodities325517 +Ref: #commodities325653 +Node: descriptions325723 +Ref: #descriptions325860 +Node: diff326151 +Ref: #diff326266 +Node: files327312 +Ref: #files327421 +Node: help327562 +Ref: #help-1327671 +Node: import328661 +Ref: #import328784 +Node: Deduplication329892 +Ref: #deduplication330017 +Node: Import testing331939 +Ref: #import-testing332104 +Node: Importing balance assignments332955 +Ref: #importing-balance-assignments333161 +Node: Commodity display styles333818 +Ref: #commodity-display-styles333991 +Node: incomestatement334120 +Ref: #incomestatement334262 +Node: notes335629 +Ref: #notes335751 +Node: payees336113 +Ref: #payees336228 +Node: prices336753 +Ref: #prices336868 +Node: print337170 +Ref: #print337285 +Node: register342731 +Ref: #register342853 +Node: Custom register output347962 +Ref: #custom-register-output348093 +Node: rewrite349468 +Ref: #rewrite349586 +Node: Re-write rules in a file351498 +Ref: #re-write-rules-in-a-file351661 +Node: Diff output format352814 +Ref: #diff-output-format352997 +Node: rewrite vs print --auto354109 +Ref: #rewrite-vs.-print---auto354271 +Node: roi354845 +Ref: #roi354952 +Node: Spaces and special characters in --inv and --pnl356713 +Ref: #spaces-and-special-characters-in---inv-and---pnl356961 +Node: Semantics of --inv and --pnl357459 +Ref: #semantics-of---inv-and---pnl357706 +Node: IRR and TWR explained359584 +Ref: #irr-and-twr-explained359744 +Node: stats362856 +Ref: #stats362964 +Node: tags364361 +Ref: #tags-1364468 +Node: test365485 +Ref: #test365578 +Node: PART 5 COMMON TASKS366328 +Ref: #part-5-common-tasks366461 +Node: Getting help366735 +Ref: #getting-help366876 +Node: Constructing command lines367640 +Ref: #constructing-command-lines367841 +Node: Starting a journal file368522 +Ref: #starting-a-journal-file368729 +Node: Setting opening balances369927 +Ref: #setting-opening-balances370132 +Node: Recording transactions373285 +Ref: #recording-transactions373474 +Node: Reconciling374030 +Ref: #reconciling374182 +Node: Reporting376495 +Ref: #reporting376644 +Node: Migrating to a new file380633 +Ref: #migrating-to-a-new-file380790  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -18,8 +18,8 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.29. It - also describes the common options, file formats and concepts used by + This manual is for hledger's command line interface, version 1.29.1. + It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeep- ing/accounting as well! You don't need to know everything in here to use hledger productively, but when you have a question about function- @@ -8659,4 +8659,4 @@ -hledger-1.29 March 2023 HLEDGER(1) +hledger-1.29.1 March 2023 HLEDGER(1)