diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -9,8 +9,11 @@ User-visible changes in the hledger command line tool and library. -# 1.26 2022-06-04 +# 1.26.1 2022-07-11 +- require safe 0.3.19+ to avoid deprecation warning + +# 1.26 2022-06-04 Improvements - `register` and `aregister` have been made faster, by diff --git a/Hledger/Cli/Commands/Balancesheet.txt b/Hledger/Cli/Commands/Balancesheet.txt --- a/Hledger/Cli/Commands/Balancesheet.txt +++ b/Hledger/Cli/Commands/Balancesheet.txt @@ -6,10 +6,10 @@ _FLAGS -The asset and liability accounts shown are those accounts declared with -the Asset or Cash or Liability type, or otherwise all accounts under a -top-level asset or liability account (case insensitive, plurals -allowed). +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: diff --git a/Hledger/Cli/Commands/Balancesheetequity.txt b/Hledger/Cli/Commands/Balancesheetequity.txt --- a/Hledger/Cli/Commands/Balancesheetequity.txt +++ b/Hledger/Cli/Commands/Balancesheetequity.txt @@ -5,10 +5,10 @@ _FLAGS -The asset, liability and equity accounts shown are those accounts -declared with the Asset, Cash, Liability or Equity type, or otherwise -all accounts under a top-level asset, liability or equity account (case -insensitive, plurals allowed). +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: diff --git a/Hledger/Cli/Commands/Cashflow.txt b/Hledger/Cli/Commands/Cashflow.txt --- a/Hledger/Cli/Commands/Cashflow.txt +++ b/Hledger/Cli/Commands/Cashflow.txt @@ -6,15 +6,13 @@ _FLAGS -"Cash" assets are those accounts which are (or whose parents are) -declared as Cash by an account directive, like this: - -account some:liquid:asset ; type:C - -Or if there are no such declarations, all accounts +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 asset account (case insensitive, plural allowed) -- with some variation of cash, bank, checking or saving in their name. +- 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: diff --git a/Hledger/Cli/Commands/Incomestatement.txt b/Hledger/Cli/Commands/Incomestatement.txt --- a/Hledger/Cli/Commands/Incomestatement.txt +++ b/Hledger/Cli/Commands/Incomestatement.txt @@ -1,15 +1,14 @@ 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. _FLAGS -The revenue and expense accounts shown are those accounts declared with -the Revenue or Expense type, or otherwise all accounts under a top-level -revenue or income or expense account (case insensitive, plurals -allowed). +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: 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" "June 2022" "hledger-ui-1.26 " "hledger User Manuals" +.TH "HLEDGER-UI" "1" "July 2022" "hledger-ui-1.26.1 " "hledger User Manuals" @@ -7,7 +7,7 @@ .PP hledger-ui is a terminal interface (TUI) for the hledger accounting tool. -This manual is for hledger-ui 1.26. +This manual is for hledger-ui 1.26.1. .SH SYNOPSIS .PP \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R] diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info --- a/embeddedfiles/hledger-ui.info +++ b/embeddedfiles/hledger-ui.info @@ -12,7 +12,7 @@ ************* hledger-ui is a terminal interface (TUI) for the hledger accounting -tool. This manual is for hledger-ui 1.26. +tool. This manual is for hledger-ui 1.26.1. 'hledger-ui [OPTIONS] [QUERYARGS]' 'hledger ui -- [OPTIONS] [QUERYARGS]' @@ -639,34 +639,34 @@  Tag Table: Node: Top221 -Node: OPTIONS1654 -Ref: #options1752 -Node: MOUSE6634 -Ref: #mouse6729 -Node: KEYS7011 -Ref: #keys7104 -Node: SCREENS11190 -Ref: #screens11288 -Node: Accounts screen11378 -Ref: #accounts-screen11506 -Node: Register screen13845 -Ref: #register-screen14000 -Node: Transaction screen15984 -Ref: #transaction-screen16142 -Node: Error screen17012 -Ref: #error-screen17134 -Node: TIPS17378 -Ref: #tips17477 -Node: Watch mode17529 -Ref: #watch-mode17646 -Node: Watch mode limitations18396 -Ref: #watch-mode-limitations18537 -Node: ENVIRONMENT19673 -Ref: #environment19784 -Node: FILES21092 -Ref: #files21191 -Node: BUGS21404 -Ref: #bugs21481 +Node: OPTIONS1656 +Ref: #options1754 +Node: MOUSE6636 +Ref: #mouse6731 +Node: KEYS7013 +Ref: #keys7106 +Node: SCREENS11192 +Ref: #screens11290 +Node: Accounts screen11380 +Ref: #accounts-screen11508 +Node: Register screen13847 +Ref: #register-screen14002 +Node: Transaction screen15986 +Ref: #transaction-screen16144 +Node: Error screen17014 +Ref: #error-screen17136 +Node: TIPS17380 +Ref: #tips17479 +Node: Watch mode17531 +Ref: #watch-mode17648 +Node: Watch mode limitations18398 +Ref: #watch-mode-limitations18539 +Node: ENVIRONMENT19675 +Ref: #environment19786 +Node: FILES21094 +Ref: #files21193 +Node: BUGS21406 +Ref: #bugs21483  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 @@ -5,7 +5,7 @@ NAME hledger-ui is a terminal interface (TUI) for the hledger accounting - tool. This manual is for hledger-ui 1.26. + tool. This manual is for hledger-ui 1.26.1. SYNOPSIS hledger-ui [OPTIONS] [QUERYARGS] @@ -548,4 +548,4 @@ -hledger-ui-1.26 June 2022 HLEDGER-UI(1) +hledger-ui-1.26.1 July 2022 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,12 +1,12 @@ -.TH "HLEDGER-WEB" "1" "June 2022" "hledger-web-1.26 " "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "July 2022" "hledger-web-1.26.1 " "hledger User Manuals" .SH NAME .PP hledger-web is a web interface (WUI) for the hledger accounting tool. -This manual is for hledger-web 1.26. +This manual is for hledger-web 1.26.1. .SH SYNOPSIS .PP \f[C]hledger-web [OPTIONS]\f[R] diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info --- a/embeddedfiles/hledger-web.info +++ b/embeddedfiles/hledger-web.info @@ -12,7 +12,7 @@ ************** hledger-web is a web interface (WUI) for the hledger accounting tool. -This manual is for hledger-web 1.26. +This manual is for hledger-web 1.26.1. 'hledger-web [OPTIONS]' 'hledger web -- [OPTIONS]' @@ -631,22 +631,22 @@  Tag Table: Node: Top223 -Node: OPTIONS1886 -Ref: #options1991 -Node: PERMISSIONS9902 -Ref: #permissions10041 -Node: EDITING UPLOADING DOWNLOADING11253 -Ref: #editing-uploading-downloading11434 -Node: RELOADING12268 -Ref: #reloading12402 -Node: JSON API12835 -Ref: #json-api12949 -Node: ENVIRONMENT18439 -Ref: #environment18555 -Node: FILES19789 -Ref: #files19889 -Node: BUGS20102 -Ref: #bugs20180 +Node: OPTIONS1888 +Ref: #options1993 +Node: PERMISSIONS9904 +Ref: #permissions10043 +Node: EDITING UPLOADING DOWNLOADING11255 +Ref: #editing-uploading-downloading11436 +Node: RELOADING12270 +Ref: #reloading12404 +Node: JSON API12837 +Ref: #json-api12951 +Node: ENVIRONMENT18441 +Ref: #environment18557 +Node: FILES19791 +Ref: #files19891 +Node: BUGS20104 +Ref: #bugs20182  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 @@ -5,7 +5,7 @@ NAME hledger-web is a web interface (WUI) for the hledger accounting tool. - This manual is for hledger-web 1.26. + This manual is for hledger-web 1.26.1. SYNOPSIS hledger-web [OPTIONS] @@ -585,4 +585,4 @@ -hledger-web-1.26 June 2022 HLEDGER-WEB(1) +hledger-web-1.26.1 July 2022 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" "June 2022" "hledger-1.26 " "hledger User Manuals" +.TH "HLEDGER" "1" "July 2022" "hledger-1.26.1 " "hledger User Manuals" @@ -9,7 +9,7 @@ This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger\[aq]s concepts and file formats. -This manual is for hledger 1.26. +This manual is for hledger 1.26.1. .SH SYNOPSIS .PP \f[C]hledger\f[R] @@ -4436,10 +4436,11 @@ shown with normal positive sign, as in conventional financial statements. .PP -The asset and liability accounts shown are those accounts declared with -the \f[C]Asset\f[R] or \f[C]Cash\f[R] or \f[C]Liability\f[R] type, or -otherwise all accounts under a top-level \f[C]asset\f[R] or -\f[C]liability\f[R] account (case insensitive, plurals allowed). +This report shows accounts declared with the \f[C]Asset\f[R], +\f[C]Cash\f[R] or \f[C]Liability\f[R] type (see account types). +Or if no such accounts are declared, it shows top-level accounts named +\f[C]asset\f[R] or \f[C]liability\f[R] (case insensitive, plurals +allowed) and their subaccounts. .PP Example: .IP @@ -4487,11 +4488,12 @@ Amounts are shown with normal positive sign, as in conventional financial statements. .PP -The asset, liability and equity accounts shown are those accounts -declared with the \f[C]Asset\f[R], \f[C]Cash\f[R], \f[C]Liability\f[R] -or \f[C]Equity\f[R] type, or otherwise all accounts under a top-level -\f[C]asset\f[R], \f[C]liability\f[R] or \f[C]equity\f[R] account (case -insensitive, plurals allowed). +This report shows accounts declared with the \f[C]Asset\f[R], +\f[C]Cash\f[R], \f[C]Liability\f[R] or \f[C]Equity\f[R] type (see +account types). +Or if no such accounts are declared, it shows top-level accounts named +\f[C]asset\f[R], \f[C]liability\f[R] or \f[C]equity\f[R] (case +insensitive, plurals allowed) and their subaccounts. .PP Example: .IP @@ -4545,22 +4547,15 @@ Amounts are shown with normal positive sign, as in conventional financial statements. .PP -\[dq]Cash\[dq] assets are those accounts which are (or whose parents -are) declared as \f[C]Cash\f[R] by an account directive, like this: -.IP -.nf -\f[C] -account some:liquid:asset ; type:C -\f[R] -.fi -.PP -Or if there are no such declarations, all accounts +This report shows accounts declared with the \f[C]Cash\f[R] type (see +account types). +Or if no such accounts are declared, it shows accounts .IP \[bu] 2 -under a top-level \f[C]asset\f[R] account (case insensitive, plural -allowed) +under a top-level account named \f[C]asset\f[R] (case insensitive, +plural allowed) .IP \[bu] 2 -with some variation of \f[C]cash\f[R], \f[C]bank\f[R], -\f[C]checking\f[R] or \f[C]saving\f[R] in their name. +whose name contains some variation of \f[C]cash\f[R], \f[C]bank\f[R], +\f[C]checking\f[R] or \f[C]saving\f[R]. .PP More precisely: all accounts matching this case insensitive regular expression: @@ -5255,16 +5250,16 @@ .PD 0 .P .PD -.PP 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. .PP -The revenue and expense accounts shown are those accounts declared with -the \f[C]Revenue\f[R] or \f[C]Expense\f[R] type, or otherwise all -accounts under a top-level \f[C]revenue\f[R] or \f[C]income\f[R] or -\f[C]expense\f[R] account (case insensitive, plurals allowed). +This report shows accounts declared with the \f[C]Revenue\f[R] or +\f[C]Expense\f[R] type (see account types). +Or if no such accounts are declared, it shows top-level accounts named +\f[C]revenue\f[R] or \f[C]income\f[R] or \f[C]expense\f[R] (case +insensitive, plurals allowed) and their subaccounts. .PP Example: .IP diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -13,10072 +13,10068 @@ This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger's concepts and file formats. This -manual is for hledger 1.26. - - 'hledger' - - 'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]' - - 'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]' - - hledger is a reliable, cross-platform set of programs for tracking -money, time, or any other commodity, using double-entry accounting and a -simple, editable file format. hledger is inspired by and largely -compatible with ledger(1). - - The basic function of the hledger CLI is to read a plain text file -describing financial transactions (in accounting terms, a general -journal) and print useful reports on standard output, or export them as -CSV. hledger can also read some other file formats such as CSV files, -translating them to journal format. Additionally, hledger lists other -hledger-* executables found in the user's $PATH and can invoke them as -subcommands. - - hledger reads data from one or more files in hledger journal, -timeclock, timedot, or CSV format specified with '-f', or -'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). If using '$LEDGER_FILE', note this -must be a real environment variable, not a shell variable. You can -specify standard input with '-f-'. - - Transactions are dated movements of money between two (or more) named -accounts, and are recorded with journal entries like this: - -2015/10/16 bought food - expenses:food $10 - assets:cash - - Most users use a text editor to edit the journal, usually with an -editor mode such as ledger-mode for added convenience. hledger's -interactive add command is another way to record new transactions. -hledger never changes existing transactions. - - To get started, you can either save some entries like the above in -'~/.hledger.journal', or run 'hledger add' and follow the prompts. Then -try some commands like 'hledger print' or 'hledger balance'. Run -'hledger' with no arguments for a list of commands. - -* Menu: - -* OPTIONS:: -* ENVIRONMENT:: -* DATA FILES:: -* TIME PERIODS:: -* DEPTH:: -* QUERIES:: -* CONVERSION & COST:: -* VALUATION:: -* PIVOTING:: -* OUTPUT:: -* COMMANDS:: -* JOURNAL FORMAT:: -* CSV FORMAT:: -* TIMECLOCK FORMAT:: -* TIMEDOT FORMAT:: -* COMMON TASKS:: -* LIMITATIONS:: -* TROUBLESHOOTING:: - - -File: hledger.info, Node: OPTIONS, Next: ENVIRONMENT, Prev: Top, Up: Top - -1 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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 directives and options: '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: DATA FILES, Prev: OPTIONS, Up: Top - -2 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\MyUserName\.hledger.journal'. You can change this by running -a command like this in a powershell window: - -> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - - (Let us know if you need to be an Administrator, and if this persists -across a reboot.) - - *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: DATA FILES, Next: TIME PERIODS, Prev: ENVIRONMENT, Up: Top - -3 DATA FILES -************ - -hledger reads transactions from one or more data files. The default -data file is '$HOME/.hledger.journal' (or on Windows, something like -'C:/Users/USER/.hledger.journal'). - - You can override this with the '$LEDGER_FILE' environment variable: - -$ setenv LEDGER_FILE ~/finance/2016.journal -$ hledger stats - - or with 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: DATA FILES - -3.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 their own sections, 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: DATA FILES - -3.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: DATA FILES - -3.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: TIME PERIODS, Next: DEPTH, Prev: DATA FILES, Up: Top - -4 TIME PERIODS -************** - -* Menu: - -* Smart dates:: -* Report start & end date:: -* Report intervals:: -* Period expressions:: - - -File: hledger.info, Node: Smart dates, Next: Report start & end date, Up: TIME PERIODS - -4.1 Smart dates -=============== - -hledger's user interfaces accept a flexible "smart date" syntax. Smart -dates allow some english words, can be relative to today's date, and can -have less-significant date parts omitted (defaulting to 1). - - Examples: - -'2004/10/1', 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 - - 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 - - Note "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; those are not affected by '--today'.) - - -File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: TIME PERIODS - -4.2 Report start & end date -=========================== - -By default, most hledger reports will show the full span of time -represented by the journal data. 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. - - 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. - * A report interval (see below) will adjust start/end dates, when - needed, so that they fall on subperiod boundaries. - - 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: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: TIME PERIODS - -4.3 Report intervals -==================== - -A report interval can be specified so that commands like register, -balance and activity become multi-period, showing each subperiod as a -separate row or column. - - The following "standard" report intervals can be enabled by using -their corresponding flag: - - * '-D/--daily' - * '-W/--weekly' - * '-M/--monthly' - * '-Q/--quarterly' - * '-Y/--yearly' - - These standard intervals always start on natural interval boundaries: -eg '--weekly' starts on mondays, '--monthly' starts on the first of the -month, '--yearly' always starts on January 1st, etc. - - Certain more complex intervals, and more flexible boundary dates, can -be specified by '-p/--period'. These are described in period -expressions, below. - - Report intervals can only be specified by the flags above, and not by -query arguments, currently. - - Report intervals have another effect: multi-period reports are always -expanded to fill a whole number of subperiods. So if you use a report -interval (other than '--daily'), and you have specified a start or end -date, you may notice those dates being overridden (ie, the report starts -earlier than your requested start date, or ends later than your -requested end date). This is done to ensure "full" first and last -subperiods, so that all subperiods' numbers are comparable. - - To summarise: - - * In multiperiod reports, all subperiods are forced to be the same - length, to simplify reporting. - * Reports with the standard - '--weekly'/'--monthly'/'--quarterly'/'--yearly' intervals are - required to start on the first day of a week/month/quarter/year. - We'd like more flexibility here but it isn't supported yet. - * '--period' (below) can specify more complex intervals, starting on - any date. - - -File: hledger.info, Node: Period expressions, Prev: Report intervals, Up: TIME PERIODS - -4.4 Period expressions -====================== - -The '-p/--period' option accepts period expressions, a shorthand way of -expressing a start date, end date, and/or report interval all at once. - - Here's a basic period expression specifying the first quarter of -2009. Note, hledger always treats start dates as inclusive and end -dates as exclusive: - -'-p "from 2009/1/1 to 2009/4/1"' - - Keywords like "from" and "to" are optional, and so are the spaces, as -long as you don't run two dates together. "to" can also be written as -".." or "-". These are equivalent to the above: - -'-p "2009/1/1 2009/4/1"' -'-p2009/1/1to2009/4/1' -'-p2009/1/1..2009/4/1' - - Dates are smart dates, so if the current year is 2009, the above can -also be written as: - -'-p "1/1 4/1"' -'-p "january-apr"' -'-p "this year to 4/1"' - - If you specify only one date, the missing start or end date will be -the earliest or latest transaction in your journal: - -'-p "from 2009/1/1"' everything after january 1, 2009 -'-p "from 2009/1"' the same -'-p "from 2009"' the same -'-p "to 2009"' everything before january 1, 2009 - - A single date with no "from" or "to" defines both the start and end -date like so: - -'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” -'-p "2009/1"' the month of jan; equivalent to “2009/1/1 to 2009/2/1” -'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2” - - Or you can specify a single quarter like so: - -'-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:: -* Intervals with custom start date:: -* Periods or dates ?:: -* Events on multiple weekdays:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -4.4.1 Period expressions with a report interval ------------------------------------------------ - -'-p/--period''s argument can also begin with, or entirely consist of, a -report interval. This should be separated from the start/end dates (if -any) by a space, or the word 'in'. The basic intervals (which can also -be written as command line flags) are 'daily', 'weekly', 'monthly', -'quarterly', and 'yearly'. Some examples: - -'-p "weekly from 2009/1/1 to 2009/4/1"' -'-p "monthly in 2008"' -'-p "quarterly"' - - As mentioned above, the 'weekly', 'monthly', 'quarterly' and 'yearly' -intervals require a report start date that is the first day of a week, -month, quarter or year. And, report start/end dates will be expanded if -needed to span a whole number of intervals. - - For example: - -'-p "weekly from starts on 2008/12/29, closest preceding -2009/1/1 to 2009/4/1"' Monday -'-p "monthly in starts on 2018/11/01 -2008/11/25"' -'-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, -2009-05-05 to which are first and last days of Q2 2009 -2009-06-01"' -'-p "yearly from starts on 2009/01/01, first day of 2009 -2009-12-29"' - - -File: hledger.info, Node: More complex report intervals, Next: Intervals with custom start date, Prev: Period expressions with a report interval, Up: Period expressions - -4.4.2 More complex report intervals ------------------------------------ - -Some more complex kinds of interval are also supported in period -expressions: - - * 'biweekly' - * 'fortnightly' - * 'bimonthly' - * 'every day|week|month|quarter|year' - * 'every N days|weeks|months|quarters|years' - - These too will cause report start/end dates to be expanded, if -needed, to span a whole number of intervals. Examples: - -'-p "bimonthly from periods will have boundaries on 2008/01/01, -2008"' 2008/03/01, ... -'-p "every 2 weeks"' starts on closest preceding Monday -'-p "every 5 months from periods will have boundaries on 2009/03/01, -2009/03"' 2009/08/01, ... - - -File: hledger.info, Node: Intervals with custom start date, Next: Periods or dates ?, Prev: More complex report intervals, Up: Period expressions - -4.4.3 Intervals with custom start date --------------------------------------- - -All intervals mentioned above are required to start on their natural -calendar boundaries, but the following intervals can start on any date: - - Weekly on 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 custom day: - - * 'every Nth day [of month]' - * 'every Nth WEEKDAYNAME [of month]' - - Yearly on 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 "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 period boundaries will be on second Monday of -Monday"' each month -'-p "every 11/05"' yearly periods with boundaries on 5th of - November -'-p "every 5th same -November"' -'-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: Periods or dates ?, Next: Events on multiple weekdays, Prev: Intervals with custom start date, Up: Period expressions - -4.4.4 Periods or dates ? ------------------------- - -Report intervals like the above are most often used with '-p|--period', -to divide reports into multiple subperiods - each generated date marks a -subperiod boundary. Here, the periods between the dates are what's -important. - - But report intervals can also be used with '--forecast' to generate -future transactions, or with 'balance --budget' to generate budget -goal-setting transactions. For these, the dates themselves are what -matters. - - -File: hledger.info, Node: Events on multiple weekdays, Prev: Periods or dates ?, Up: Period expressions - -4.4.5 Events on multiple weekdays ---------------------------------- - -The 'every WEEKDAYNAME' form has a special variant with multiple day -names, comma-separated. Eg: 'every mon,thu,sat'. Also, 'weekday' and -'weekendday' are shorthand for 'mon,tue,wed,thu,fri' and 'sat,sun' -respectively. - - This form 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. (Because gaps between periods are not allowed; if you'd like to -change this, see #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 - -5 DEPTH -******* - -With the '--depth NUM' option (short form: '-NUM'), commands like -account, balance and register will show only the uppermost accounts in -the account tree, down to level NUM. 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: CONVERSION & COST, Prev: DEPTH, Up: Top - -6 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 account aliases:: -* Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value:: - - -File: hledger.info, Node: Query types, Next: Combining query terms, Up: QUERIES - -6.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 - -6.2 Combining 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. - - while the print command shows transactions which: - - * match any of the description terms AND - * have any postings matching any of the positive account terms AND - * have no postings matching any of the negative account terms AND - * match all the other terms. - - You can do more powerful queries (such as AND-ing two like terms) by -running a first query with 'print', and piping the result into a second -hledger command. Eg: how much of food expenses was paid with cash ? - -$ hledger print assets:cash | hledger -f- -I balance expenses:food - - If you are interested in full boolean expressions for queries, see -#203. - - -File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Combining query terms, Up: QUERIES - -6.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 account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: QUERIES - -6.4 Queries and account aliases -=============================== - -When account names are rewritten with '--alias' or 'alias', 'acct:' will -match either the old or the new account name. - - -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and account aliases, Up: QUERIES - -6.5 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 - -6.6 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 - -6.7 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: CONVERSION & COST, Next: VALUATION, Prev: QUERIES, Up: Top - -7 CONVERSION & COST -******************* - -This section is about converting between commodities. Some definitions: - - * A "commodity conversion" is an exchange of one currency or - commodity for another. Eg a foreign currency exchange, or a - purchase or sale of stock or cryptocurrency. - - * A "conversion transaction" is a transaction involving one or more - such conversions. - - * "Conversion rate" is the exchange rate in a conversion - the cost - per unit of one commodity in the other. - - * "Cost" is how much of one commodity was paid to acquire the other - (when buying), or how much was received in exchange for the other - (when selling). We call both of these "cost" for convenience - (after all, it is cost for one party or the other). - -* Menu: - -* Recording conversions:: -* Inferring missing conversion rates:: -* Inferring missing equity postings:: -* Cost reporting:: -* Conversion summary:: - - -File: hledger.info, Node: Recording conversions, Next: Inferring missing conversion rates, Up: CONVERSION & COST - -7.1 Recording conversions -========================= - -As a concrete example, let's assume 100 EUR was converted to 120 USD. -There are several ways to record this in the journal, each with pros and -cons which will be explained in more detail below. (Also, these -examples use journal format which is properly explained much further -below; sorry about that, you may want to read some of that first.) - -* Menu: - -* Implicit conversion:: -* Priced conversion:: -* Equity conversion:: -* Priced equity conversion:: - - -File: hledger.info, Node: Implicit conversion, Next: Priced conversion, Up: Recording conversions - -7.1.1 Implicit conversion -------------------------- - -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: - - * Easy, concise - * hledger can do cost reporting - - Con: - - * Less error checking - typos in amounts or commodity symbols may not - be detected - * conversion rate is not clear - * disturbs the accounting equation - - 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: Priced conversion, Next: Equity conversion, Prev: Implicit conversion, Up: Recording conversions - -7.1.2 Priced conversion ------------------------ - -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 some error checking - * hledger can do cost reporting - - Con: - - * Disturbs the accounting equation - - -File: hledger.info, Node: Equity conversion, Next: Priced equity conversion, Prev: Priced conversion, Up: Recording conversions - -7.1.3 Equity conversion ------------------------ - -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 - * works in any double entry accounting system - - Con: - - * More verbose - * conversion rate is not clear - * hledger can not do cost reporting - - -File: hledger.info, Node: Priced equity conversion, Prev: Equity conversion, Up: Recording conversions - -7.1.4 Priced equity conversion ------------------------------- - -Another possible notation would be to record both the conversion rate -and the equity postings: - -2021-01-01 - assets:cash -100 EUR @ 1.20 USD - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - hledger currently does not allow this; instead, you can record the -conversion rate as a comment. - - -File: hledger.info, Node: Inferring missing conversion rates, Next: Inferring missing equity postings, Prev: Recording conversions, Up: CONVERSION & COST - -7.2 Inferring missing conversion rates -====================================== - -hledger will do this automatically for implicit conversions. Currently -it can not do this for equity conversions. - - -File: hledger.info, Node: Inferring missing equity postings, Next: Cost reporting, Prev: Inferring missing conversion rates, Up: CONVERSION & COST - -7.3 Inferring missing equity postings -===================================== - -With the '--infer-equity' flag, hledger will add equity postings to -priced and implicit conversions (and move the conversion rate into a -comment). - - -File: hledger.info, Node: Cost reporting, Next: Conversion summary, Prev: Inferring missing equity postings, Up: CONVERSION & COST - -7.4 Cost reporting -================== - -With the '-B/--cost' flag, hledger will convert the amounts in priced -and implicit conversions to their cost in the other commodity. This is -useful to see a report of what you paid for things (or how much you sold -things for). Currently '-B/--cost' does not work on equity conversions, -and it disables '--infer-equity'. - - These operations are transient, only affecting reports. If you want -to change the journal file permanently, you could pipe each entry -through 'hledger -f- -I print [-x] [--infer-equity] [-B]' - - -File: hledger.info, Node: Conversion summary, Prev: Cost reporting, Up: CONVERSION & COST - -7.5 Conversion summary -====================== - - * Recording the conversion rate is good because it makes that clear - and allows cost reporting. - * Recording equity postings is good because it balances the - accounting equation and is correct bookkeeping. - * Combining these is not yet supported, so you have to choose. For - now, priced conversions are a good compromise, so that: - * When you want to see the cost (or sale proceeds) of things, - use '-B/--cost'. - * When you want to see a balanced balance sheet or correct - journal entries, use '--infer-equity'. - * Combining these is not yet supported; '-B/--cost' will take - precedence. - - * Conversion/cost operations are performed before valuation. - - -File: hledger.info, Node: VALUATION, Next: PIVOTING, Prev: CONVERSION & COST, Up: Top - -8 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:: -* Market prices:: -* --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 - -8.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 - -8.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: Market prices, Prev: -X Value in specified commodity, Up: VALUATION - -8.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: Market prices, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: VALUATION - -8.4 Market prices -================= - -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 transaction prices. - - 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: Market prices, Up: VALUATION - -8.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 transaction prices as additional market -prices (as Ledger does) ? We could produce value reports without -needing P directives at all. - - 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. -(And 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.) - - * but not, currently, from "more correct" multicommodity transactions - (no '@', multiple commodities, balanced). - - There is another 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' - - -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: VALUATION - -8.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, transaction prices 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 - -8.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 - -8.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 - -8.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 - -8.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 - -8.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: PIVOTING, Next: OUTPUT, Prev: VALUATION, Up: Top - -9 PIVOTING -********** - -Normally hledger sums amounts, and organizes them in a hierarchy, based -on account name. The '--pivot FIELD' option causes it to sum and -organize hierarchy based on the value of some other field instead. -FIELD can be: 'status', 'code', 'description', 'payee', 'note', or the -full name (case insensitive) of any tag. As with account names, values -containing 'colon:separated:parts' will be displayed hierarchically in -reports. - - '--pivot' is a general option affecting all reports; you can think of -hledger transforming the journal before any other processing, replacing -every posting's account name with the value of the specified field on -that posting, inheriting it from the transaction or using a blank value -if it's not present. - - An example: - -2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees --------------------- - 0 - - Pivoted balance report, using member: tag values instead: - -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 - - One way to show only amounts with a member: value (using a query, -described below): - -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account -name"): - -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR - - -File: hledger.info, Node: OUTPUT, Next: COMMANDS, Prev: PIVOTING, Up: Top - -10 OUTPUT -********* - -* Menu: - -* Output destination:: -* Output styling:: -* Output format:: -* Commodity styles:: - - -File: hledger.info, Node: Output destination, Next: Output styling, Up: OUTPUT - -10.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) - - hledger can optionally produce debug output (if enabled with -'--debug=N'); this goes to stderr, and is not affected by -'-o/--output-file'. If you need to capture it, use shell redirects, eg: -'hledger bal --debug=3 >file 2>&1'. - - -File: hledger.info, Node: Output styling, Next: Output format, Prev: Output destination, Up: OUTPUT - -10.2 Output styling -=================== - -hledger commands can produce colour output when the terminal supports -it. This is controlled by the '--color/--colour' option: - 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. - - hledger commands can also use unicode box-drawing characters to -produce prettier tables and output. This is controlled by the -'--pretty' option: - 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: Output format, Next: Commodity styles, Prev: Output styling, Up: OUTPUT - -10.3 Output format -================== - -Some commands offer additional output formats, other than the usual -plain text terminal output. Here are those commands and the formats -currently supported: - -- txt csv html json sql ------------------------------------------------------------- -aregister 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 - -* Menu: - -* CSV output:: -* HTML output:: -* JSON output:: -* SQL output:: - - -File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format - -10.3.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 - -10.3.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 - -10.3.3 JSON output ------------------- - - * Not yet much used; real-world feedback is welcome. - - * Our JSON is rather large and verbose, as it is quite 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 - -10.3.4 SQL output ------------------ - - * 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, Prev: Output format, Up: OUTPUT - -10.4 Commodity styles -===================== - -The display style of a commodity/currency is inferred according to the -rules described in Commodity display style. The inferred display style -can be overridden by an optional '-c/--commodity-style' option -(Exceptions: as is the case for inferred styles, price amounts, and all -amounts displayed by the 'print' command, will be displayed with all of -their decimal digits visible, regardless of the specified precision). -For example, the following will override the display style for dollars. - -$ hledger print -c '$1.000,0' - - The format specification of the style is identical to the commodity -display style specification for the commodity directive. The command -line option can be supplied repeatedly to override the display style for -multiple commodity/currency symbols. - - -File: hledger.info, Node: COMMANDS, Next: JOURNAL FORMAT, Prev: OUTPUT, Up: Top - -11 COMMANDS -*********** - -hledger provides a number of commands for producing reports and managing -your data. 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'. - - Here are the built-in commands, with the most often-used in bold: - - *Data entry:* - - These data entry commands are the only ones which can modify your -journal file. - - * *add* - add transactions using guided prompts - * *import* - add any new transactions from other files (eg csv) - - *Data management:* - - * check - check for various kinds of issue in the data - * close (equity) - generate balance-resetting transactions - * diff - compare account transactions in two journal files - * rewrite - generate extra postings, similar to print -auto - - *Financial statements:* - - * *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 - * roi - show return on investments - - *Miscellaneous reports:* - - * accounts - show account names - * activity - show postings-per-interval bar charts - * *balance (bal)* - show balance changes/end balances/budgets in any - accounts - * codes - show transaction codes - * commodities - show commodity/currency symbols - * descriptions - show unique transaction descriptions - * files - show input file paths - * help - show hledger user manuals in several formats - * notes - show unique note segments of transaction descriptions - * payees - show unique payee segments of transaction descriptions - * prices - show market price records - * *print* - show transactions (journal entries) - * print-unique - show only transactions with unique descriptions - * *register (reg)* - show postings in one or more accounts & running - total - * register-match - show a recent posting that best matches a - description - * stats - show journal statistics - * tags - show tag names - * test - run self tests - - *Add-on commands:* - - Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on -commands; these appear in the commands list with a '+' mark. Two of -these are maintained and released with hledger: - - * *ui* - an efficient terminal interface (TUI) for hledger - * *web* - a simple web interface (WUI) for hledger - - And these add-ons are maintained separately: - - * iadd - a more interactive alternative for the add command - * interest - generates interest transactions according to various - schemes - * stockquotes - downloads market prices for your commodities from - AlphaVantage _(experimental)_ - - Next, the detailed command docs, in alphabetical order. - -* Menu: - -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* print-unique:: -* register:: -* register-match:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: -* About add-on commands:: - - -File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS - -11.1 accounts -============= - -accounts -Show account names. - - This command lists account names, either declared with account -directives (-declared), posted to (-used), or both (the default). With -query arguments, only matched account names and account names referenced -by matched postings are shown. It shows a flat list by default. With -'--tree', it uses indentation to show the account hierarchy. In flat -mode you can add '--drop N' to omit the first few account name -components. Account names can be depth-clipped with 'depth:N' or -'--depth N' or '-N'. - - With '--types', it also shows each account's type, if it's known. -(See Declaring accounts > Account types.) - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS - -11.2 activity -============= - -activity -Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - - Examples: - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS - -11.3 add -======== - -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, - 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 the tutorial for a detailed explanation): - -$ hledger add -Adding transactions to journal file /src/hledger/examples/sample.journal -Any command line arguments will be used as defaults. -Use tab key to complete, readline keys to edit, enter to accept defaults. -An optional (CODE) may follow transaction dates. -An optional ; COMMENT may follow descriptions or amounts. -If you make a mistake, enter < at any prompt to 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: COMMANDS - -11.4 aregister -============== - -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. -(Eg if you have 'assets:aaa:checking' and 'assets:bbb:checking' -accounts, 'hledger areg checking' would select 'assets:aaa:checking'.) - - 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 - -11.4.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: COMMANDS - -11.5 balance -============ - -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:: -* Filtered balance report:: -* List or tree mode:: -* Depth limiting:: -* Dropping top-level accounts:: -* Multi-period balance report:: -* Showing declared accounts:: -* Data layout:: -* Sorting by amount:: -* Percentages:: -* Balance change end balance:: -* Balance report types:: -* Useful balance reports:: -* Budget report:: -* Customising single-period balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -11.5.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: Filtered balance report, Prev: balance features, Up: balance - -11.5.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. For real-world -accounts, this should also match 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: Filtered balance report, Next: List or tree mode, Prev: Simple balance report, Up: balance - -11.5.3 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 - -11.5.4 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 - -11.5.5 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: Multi-period balance report, Prev: Depth limiting, Up: balance - -11.5.6 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: Multi-period balance report, Next: Showing declared accounts, Prev: Dropping top-level accounts, Up: balance - -11.5.7 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: Showing declared accounts, Next: Data layout, Prev: Multi-period balance report, Up: balance - -11.5.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: Data layout, Next: Sorting by amount, Prev: Showing declared accounts, Up: balance - -11.5.9 Data layout ------------------- - -The '--layout' option affects how multi-commodity amounts are displayed, -and some other things, influencing the overall layout of the report -data: - - * '--layout=wide[,WIDTH]': commodities are shown on a single line, - possibly elided to the specified width - * '--layout=tall': each commodity is shown on a separate line - * '--layout=bare': amounts are shown as bare numbers, with commodity - symbols in a separate column - * '--layout=tidy': data is normalised to tidy form, with one row per - data value. We currently support this with CSV output only. In - tidy mode, totals and row averages are disabled ('-N/--no-total' is - implied and '-T/--row-total' and '-A/--average' will be ignored). - - These '--layout' modes are supported with some but not all of the -output formats: - -- 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 when 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 - is a column and each row represents a single data point (see - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). - This kind of data is the easiest to process with other software: - - $ 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: Sorting by amount, Next: Percentages, Prev: Data layout, Up: balance - -11.5.10 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: Balance change end balance, Prev: Sorting by amount, Up: balance - -11.5.11 Percentages -------------------- - -With '-%/--percent', balance reports show each account's value expressed -as a percentage of the (column) total: - -$ hledger -f examples/sample.journal bal expenses -Q -% -Balance changes in 2008: - - || 2008Q1 2008Q2 2008Q3 2008Q4 -===================++================================= - expenses:food || 0 50.0 % 0 0 - expenses:supplies || 0 50.0 % 0 0 --------------------++--------------------------------- - || 0 100.0 % 0 0 - - 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: Balance change end balance, Next: Balance report types, Prev: Percentages, Up: balance - -11.5.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: Useful balance reports, Prev: Balance change end balance, Up: balance - -11.5.13 Balance report types ----------------------------- - -For more flexible reporting, there are three important option groups: - - 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] -...' - - The first two are the most important: calculation type selects the -basic calculation to perform for each table cell, while accumulation -type says which postings should be included in each cell's calculation. -Typically one or both of these are selected by default, so you don't -need to write them explicitly. A valuation type can be added if you -want to convert the basic report to value or cost. - - *Calculation type:* -The basic calculation to perform for each table cell. It is one of: - - * '--sum' : sum the posting amounts (*default*) - * '--budget' : like -sum but also show a goal amount - * '--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) - - *Accumulation type:* -Which postings should be included in each cell's calculation. It is one -of: - - * '--change' : postings from column start to column end, ie within - the cell's period. Typically used to see revenues/expenses. - (*default for balance, incomestatement*) - - * '--cumulative' : postings from report start to column end, eg to - show changes accumulated since the report's start date. Rarely - used. - - * '--historical/-H' : postings from journal start to column end, ie - all postings from account creation to the end of the cell's period. - Typically used to see historical end balances of - assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) - - *Valuation type:* -Which kind of valuation, valuation date(s) and optionally a target -valuation commodity to use. It is one of: - - * no valuation, show amounts in their original commodities - (*default*) - * '--value=cost[,COMM]' : no valuation, show amounts converted to - cost - * '--value=then[,COMM]' : show value at transaction dates - * '--value=end[,COMM]' : show value at period end date(s) (*default - with '--valuechange', '--gain'*) - * '--value=now[,COMM]' : show value at today's date - * '--value=YYYY-MM-DD[,COMM]' : show value at another date - - or one of their aliases: '--cost/-B', '--market/-V' or -'--exchange/-X'. - - 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: YYYY-MM-DD -v /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: Useful balance reports, Next: Budget report, Prev: Balance report types, Up: balance - -11.5.14 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: Budget report, Next: Customising single-period balance reports, Prev: Useful balance reports, Up: balance - -11.5.15 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 very 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] - - For more examples and notes, see Budgeting. - -* Menu: - -* Budget report start date:: -* Budgets and subaccounts:: -* Selecting budget goals:: - - -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report - -11.5.15.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 - -11.5.15.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, Prev: Budgets and subaccounts, Up: Budget report - -11.5.15.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 the -print command 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: Customising single-period balance reports, Prev: Budget report, Up: balance - -11.5.16 Customising single-period balance reports -------------------------------------------------- - -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 (plus a newline) specifies the formatting -applied to each account/balance pair. It may contain any suitable text, -with data fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - - * MAX truncates at this width (optional) - - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS - -11.6 balancesheet -================= - -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. - - The asset and liability accounts shown are those accounts declared -with the 'Asset' or 'Cash' or 'Liability' type, or otherwise all -accounts under a top-level 'asset' or 'liability' account (case -insensitive, plurals allowed). - - 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: COMMANDS - -11.7 balancesheetequity -======================= - -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. - - The asset, liability and equity accounts shown are those accounts -declared with the 'Asset', 'Cash', 'Liability' or 'Equity' type, or -otherwise all accounts under a top-level 'asset', 'liability' or -'equity' account (case insensitive, plurals allowed). - - 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: COMMANDS - -11.8 cashflow -============= - -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. - - "Cash" assets are those accounts which are (or whose parents are) -declared as 'Cash' by an account directive, like this: - -account some:liquid:asset ; type:C - - Or if there are no such declarations, all accounts - - * under a top-level 'asset' account (case insensitive, plural - allowed) - * with some variation of 'cash', 'bank', 'checking' or 'saving' in - their name. - - 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: COMMANDS - -11.9 check -========== - -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 - - Here are the checks currently available: - -* Menu: - -* Basic checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: - - -File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check - -11.9.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 transaction prices or automatically-inferred - transaction prices - - * *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 - -11.9.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 transaction prices but not inferred ones - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -11.9.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 - - * *uniqueleafnames* - all account leaf names are unique - - -File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check - -11.9.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: close, Next: codes, Prev: check, Up: COMMANDS - -11.10 close -=========== - -close, equity -Prints a sample "closing" transaction bringing specified account -balances to zero, and an inverse "opening" transaction restoring the -same account balances. - - If like most people you split your journal files by time, eg by year: -at the end of the year you can use this command to "close out" your -asset and liability (and perhaps equity) balances in the old file, and -reinitialise them in the new file. This helps ensure that report -balances remain correct whether you are including old files or not. -(Because all closing/opening transactions except the very first will -cancel out - see example below.) - - Some people also use this command to close out revenue and expense -balances at the end of an accounting period. This properly records the -period's profit/loss as "retained earnings" (part of equity), and allows -the accounting equation (A-L=E) to balance, which you could then check -by the bse report's zero total. - - You can print just the closing transaction by using the '--close' -flag, or just the opening transaction with the '--open' flag. - - Their descriptions are 'closing balances' and 'opening balances' by -default; you can customise these with the '--close-desc' and -'--open-desc' options. - - Just one balancing equity posting is used by default, with the amount -left implicit. The default account name is 'equity:opening/closing -balances'. You can customise the account name(s) with '--close-acct' -and '--open-acct'. (If you specify only one of these, it will be used -for both.) - - With '--x/--explicit', the equity posting's amount will be shown -explicitly, and if it involves multiple commodities, there will be a -separate equity posting for each commodity (as in the print command). - - With '--interleaved', each equity posting is shown next to the -posting it balances (good for troubleshooting). - -* Menu: - -* close and prices:: -* close date:: -* Example close asset/liability accounts for file transition:: -* Hiding opening/closing transactions:: -* close and balance assertions:: -* Example close revenue/expense accounts to retained earnings:: - - -File: hledger.info, Node: close and prices, Next: close date, Up: close - -11.10.1 close and prices ------------------------- - -Transaction prices are ignored (and discarded) by closing/opening -transactions, by default. With '--show-costs', they are preserved; -there will be a separate equity posting for each cost in each commodity. -This means 'balance -B' reports will look the same after the transition. -Note if you have many foreign currency or investment transactions, this -will generate very large journal entries. - - -File: hledger.info, Node: close date, Next: Example close asset/liability accounts for file transition, Prev: close and prices, Up: close - -11.10.2 close date ------------------- - -The default closing date is yesterday, or the journal's end date, -whichever is later. - - Unless you are running 'close' on exactly the first day of the new -period, you'll want to override the closing date. This is done by -specifying a report end date, where "last day of the report period" will -be the closing date. The opening date is always the following day. So -to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any -of these will work: - -end date explanation -argument -------------------------------------------------------------------- -'-e 2021-01-01' end dates are exclusive -'-e 2021' equivalent, per smart dates -'-p 2020' equivalent, the period's begin date is ignored -'date:2020' equivalent query - - -File: hledger.info, Node: Example close asset/liability accounts for file transition, Next: Hiding opening/closing transactions, Prev: close date, Up: close - -11.10.3 Example: close asset/liability accounts for file transition -------------------------------------------------------------------- - -Carrying asset/liability balances from 2020.journal into a new file for -2021: - -$ hledger close -f 2020.journal -p 2020 assets liabilities -# copy/paste the closing transaction to the end of 2020.journal -# copy/paste the opening transaction to the start of 2021.journal - - Or: - -$ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction -$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction - - Now, - -$ hledger bs -f 2021.journal # just new file - balances correct -$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct -$ hledger bs -f 2020.journal # just old files - balances are zero ? - # (exclude final closing txn, see below) - - -File: hledger.info, Node: Hiding opening/closing transactions, Next: close and balance assertions, Prev: Example close asset/liability accounts for file transition, Up: close - -11.10.4 Hiding opening/closing transactions -------------------------------------------- - -Although the closing/opening transactions cancel out, they will be -visible in reports like 'print' and 'register', creating some visual -clutter. You can exclude them all with a query, like: - -$ hledger print not:desc:'opening|closing' # less typing -$ hledger print not:'equity:opening/closing balances' # more precise - - But when reporting on multiple files, this can get a bit tricky; you -may need to keep the earliest opening balances, for a historical -register report; or you may need to suppress a closing transaction, to -see year-end balances. If you find yourself needing more precise -queries, here's one solution: add more easily-matched tags to -opening/closing transactions, like this: - -; 2019.journal -2019-01-01 opening balances ; earliest opening txn, no tag here -... -2019-12-31 closing balances ; clopen:2020 -... - -; 2020.journal -2020-01-01 opening balances ; clopen:2020 -... -2020-12-31 closing balances ; clopen:2021 -... - -; 2021.journal -2021-01-01 opening balances ; clopen:2021 -... - - Now with - -; all.journal -include 2019.journal -include 2020.journal -include 2021.journal - - you could do eg: - -$ hledger -f all.journal reg -H checking not:tag:clopen - # all years checking register, hiding non-essential opening/closing txns - -$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 - # 2020 year end balances, suppressing 2020 closing txn - - -File: hledger.info, Node: close and balance assertions, Next: Example close revenue/expense accounts to retained earnings, Prev: Hiding opening/closing transactions, Up: close - -11.10.5 close and balance assertions ------------------------------------- - -The closing and opening transactions will include balance assertions, -verifying that the accounts have first been reset to zero and then -restored to their previous balance. These provide valuable error -checking, alerting you when things get out of line, but you can ignore -them temporarily with '-I' or just remove them if you prefer. - - You probably shouldn't use status or realness filters (like -C or -R -or 'status:') with 'close', or the generated balance assertions will -depend on these flags. Likewise, if you run this command with '--auto', -the balance assertions would probably always require '--auto'. - - Multi-day transactions (where some postings have a different date) -break the balance assertions, because the money is temporarily -"invisible" while in transit: - -2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - assets:bank:checking -5 ; date: 2021/1/2 - - To fix the assertions, you can add a temporary account to track such -in-transit money (splitting the multi-day transaction into two -single-day transactions): - -; in 2020.journal: -2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - liabilities:pending - -; in 2021.journal: -2021/1/2 clearance of last year's pending transactions - liabilities:pending 5 = 0 - assets:bank:checking - - -File: hledger.info, Node: Example close revenue/expense accounts to retained earnings, Prev: close and balance assertions, Up: close - -11.10.6 Example: close revenue/expense accounts to retained earnings --------------------------------------------------------------------- - -For this, use '--close' to suppress the opening transaction, as it's not -needed. Also you'll want to change the equity account name to your -equivalent of "equity:retained earnings". - - Closing 2021's first quarter revenues/expenses: - -$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ - --close-acct='equity:retained earnings' >> 2021.journal - - The same, using the default journal and current year: - -$ hledger close --close revenues expenses -p Q1 \ - --close-acct='equity:retained earnings' >> $LEDGER_FILE - - Now, the first quarter's balance sheet should show a zero (unless you -are using @/@@ notation without equity postings): - -$ hledger bse -p Q1 - - And we must suppress the closing transaction to see the first -quarter's income statement (using the description; 'not:'retained -earnings'' won't work here): - -$ hledger is -p Q1 not:desc:'closing balances' - - -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS - -11.11 codes -=========== - -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: - -1/1 (123) - (a) 1 - -1/1 () - (a) 1 - -1/1 - (a) 1 - -1/1 (126) - (a) 1 - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - - -126 - - -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS - -11.12 commodities -================= - -commodities -List all commodity/currency symbols used or declared in the journal. - - -File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS - -11.13 descriptions -================== - -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: COMMANDS - -11.14 diff -========== - -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: COMMANDS - -11.15 files -=========== - -files -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - - -File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS - -11.16 help -========== - -help -Show the hledger user manual in one of several formats, optionally -positioned at a given TOPIC (if possible). - - TOPIC is any heading in the manual, or the start of any heading (but -not the middle). It is case insensitive. - - Some examples: 'commands', 'print', 'forecast', '"auto postings"', -'"commodity column"'. - - This command shows the user manual built in to this hledger version. -It can be useful if the correct version of the hledger manual, or the -usual viewing tools, are not installed on your system. - - By default it uses the best viewer it can find in $PATH, in this -order: 'info', 'man', $PAGER (unless a topic is specified), 'less', or -stdout. When run non-interactively, it always uses stdout. Or you can -select a particular viewer with the '-i' (info), '-m' (man), or '-p' -(pager) flags. - - -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS - -11.17 import -============ - -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 - -11.17.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 - -11.17.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' - - -File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import - -11.17.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 - -11.17.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: COMMANDS - -11.18 incomestatement -===================== - -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. - - The revenue and expense accounts shown are those accounts declared -with the 'Revenue' or 'Expense' type, or otherwise all accounts under a -top-level 'revenue' or 'income' or 'expense' account (case insensitive, -plurals allowed). - - 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: COMMANDS - -11.19 notes -=========== - -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: COMMANDS - -11.20 payees -============ - -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: COMMANDS - -11.21 prices -============ - -prices -Print market price directives from the journal. With --infer-market-prices, generate additional market prices from transaction -prices. With -infer-reverse-prices, also generate market prices by -inverting transaction prices. Prices (and postings providing -transaction prices) can be filtered by a query. Price amounts are -displayed with their full precision. - - -File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS - -11.22 print -=========== - -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 transaction price is -implied but not written, it will not appear in the output. You can use -the '-x'/'--explicit' flag to make all amounts and transaction prices -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 transaction prices are converted to -cost using that price. This can be used for troubleshooting. - - With '-m'/'--match' and a STR argument, print will show at most one -transaction: the one one whose description is most similar to STR, and -is most recent. STR should contain at least two characters. If there -is no similar-enough match, no transaction will be shown. - - With '--new', 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: print-unique, Next: register, Prev: print, Up: COMMANDS - -11.23 print-unique -================== - -print-unique -Print transactions which do not reuse an already-seen description. - - Example: - -$ cat unique.journal -1/1 test - (acct:one) 1 -2/2 test - (acct:two) 2 -$ LEDGER_FILE=unique.journal hledger print-unique -(-f option not supported) -2015/01/01 test - (acct:one) 1 - - -File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS - -11.24 register -============== - -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. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -11.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: register-match, Next: rewrite, Prev: register, Up: COMMANDS - -11.25 register-match -==================== - -register-match -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. If there are multiple equally -good matches, it shows the most recent. Query options (options, not -arguments) can be used to restrict the search space. Helps -ledger-autosync detect already-seen transactions when importing. - - -File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS - -11.26 rewrite -============= - -rewrite -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - - This is a start at a generic rewriter of transaction entries. It -reads the default journal and prints the transactions, like print, but -adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing -transaction's first posting amount. - - Examples: - -$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -$ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the -two spaces between account and amount. - - More: - -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for '--add-posting' option is a usual posting of transaction -with an exception for amount specification. More precisely, you can use -''*'' (star symbol) before the amount to indicate that that this is a -factor for an amount of original matched posting. If the amount -includes a commodity name, the new posting amount will be in the new -commodity; otherwise, it will be in the matched posting amount's -commodity. - -* Menu: - -* Re-write rules in a file:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -11.26.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 - -11.26.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 - -11.26.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: COMMANDS - -11.27 roi -========= - -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 - -11.27.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 - -11.27.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 - -11.27.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: COMMANDS - -11.28 stats -=========== - -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 also supports output destination and output format -selection. - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS - -11.29 tags -========== - -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, Next: About add-on commands, Prev: tags, Up: COMMANDS - -11.30 test -========== - -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: About add-on commands, Prev: test, Up: COMMANDS - -11.31 About add-on commands -=========================== - -Add-on commands are 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. - - Add-ons are a relatively easy way to add local features or experiment -with new ideas. They can be written in any language, but haskell -scripts have a big advantage: they can use the same hledger library -functions that built-in commands use for command-line options, parsing -and reporting. Some experimental/example add-on scripts can be found in -the hledger repo's bin/ directory. - - 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: JOURNAL FORMAT, Next: CSV FORMAT, Prev: COMMANDS, Up: Top - -12 JOURNAL FORMAT -***************** - -hledger's default file format, representing a General Journal. - - 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). These are mostly in the order you'll use them, but in some -cases related concepts have been grouped together for easy reference, or -linked before they are introduced, so feel free to skip over anything -that looks unnecessary right now. - -* Menu: - -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Comments:: -* Tags:: -* Postings:: -* Account names:: -* Amounts:: -* Transaction prices:: -* Lot prices lot dates:: -* Balance assertions:: -* Balance assignments:: -* Directives:: -* Directives and multiple files:: -* Comment blocks:: -* Including other files:: -* Default year:: -* Declaring payees:: -* Declaring the decimal mark:: -* Declaring commodities:: -* Default commodity:: -* Declaring market prices:: -* Declaring accounts:: -* Rewriting accounts:: -* Default parent account:: -* Periodic transactions:: -* Auto postings:: - - -File: hledger.info, Node: Transactions, Next: Dates, Up: JOURNAL FORMAT - -12.1 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 FORMAT - -12.2 Dates -========== - -* Menu: - -* Simple dates:: -* Secondary dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Secondary dates, Up: Dates - -12.2.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 default year 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: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates - -12.2.2 Secondary dates ----------------------- - -Real-life transactions sometimes involve more than one date - eg the -date you write a cheque, and the date it clears in your bank. When you -want to model this, for more accurate daily balances, you can specify -individual posting dates. - - Or, you can use the older _secondary date_ feature (Ledger calls it -auxiliary date or effective date). Note: we support this for -compatibility, but I usually recommend avoiding this feature; posting -dates are almost always clearer and simpler. - - 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", as shown here: - -2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking - -$ hledger register checking -2010-02-23 movie ticket assets:checking $-10 $-10 - -$ hledger register checking --date2 -2010-02-19 movie ticket assets:checking $-10 $-10 - - -File: hledger.info, Node: Posting dates, Prev: Secondary dates, Up: Dates - -12.2.3 Posting dates --------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like 'date:DATE'. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction's date. You can set the secondary date -similarly, with 'date2:DATE2'. The 'date:' or 'date2:' tags must have a -valid simple date value if they are present, eg a 'date:' tag with no -value is not allowed. - - Ledger's earlier, more compact bracketed date syntax is also -supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'. hledger will attempt -to parse any square-bracketed sequence of the '0123456789/-.=' -characters in this way. With this syntax, DATE infers its year from the -transaction and DATE2 infers its year from DATE. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: JOURNAL FORMAT - -12.3 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 FORMAT - -12.4 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: Comments, Prev: Code, Up: JOURNAL FORMAT - -12.5 Description -================ - -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -12.5.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: Comments, Next: Tags, Prev: Description, Up: JOURNAL FORMAT - -12.6 Comments -============= - -Lines in the journal beginning with a semicolon (';') or hash ('#') or -star ('*') are comments, and will be ignored. (Star comments cause -org-mode nodes to be ignored, allowing emacs users to fold and navigate -their journals with org-mode or orgstruct-mode.) - - You can attach comments to a transaction by writing them after the -description and/or indented on the following lines (before the -postings). Similarly, you can attach comments to an individual posting -by writing them after the amount and/or indented on the following lines. -Transaction and posting comments must begin with a semicolon (';'). - - Some examples: - -# a file comment -; another file comment -* also a file comment, useful in org/orgstruct mode - -comment -A multiline file comment, which continues -until a line containing just "end comment" -(or end of file). -end comment - -2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 -; a file comment (because not indented) - - You can also comment larger regions of a file using 'comment' and -'end comment' directives. - - -File: hledger.info, Node: Tags, Next: Postings, Prev: Comments, Up: JOURNAL FORMAT - -12.7 Tags -========= - -Tags are a way to add extra labels or labelled data to postings and -transactions, which you can then search or pivot on. - - A simple tag is a word (which may contain hyphens) followed by a full -colon, written inside a transaction or posting comment line: - -2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the -next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or -newlines. Ending at commas means you can write multiple short tags on -one line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - * "'a comment containing'" is just comment text, not a tag - * "'tag1'" is a tag with no value - * "'tag2'" is another tag, whose value is "'some value ...'" - - Tags in a transaction comment affect the transaction and all of its -postings, while tags in a posting comment affect only that posting. For -example, the following transaction has three tags ('A', 'TAG2', -'third-tag') and the posting has four (those plus 'posting-tag'): - -1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values -are simple strings. - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Tags, Up: JOURNAL FORMAT - -12.8 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. - -* Menu: - -* Virtual postings:: - - -File: hledger.info, Node: Virtual postings, Up: Postings - -12.8.1 Virtual postings ------------------------ - -A posting with a parenthesised 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 accounting, 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: - -1/1 opening balances - (assets:checking) $1000 - (assets:savings) $2000 - - A posting with a bracketed 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: - -1/1 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- not required to balance - - Ordinary non-parenthesised, non-bracketed postings are called _real -postings_. You can exclude virtual postings from reports with the -'-R/--real' flag or 'real:1' query. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: JOURNAL FORMAT - -12.9 Account names -================== - -Account names typically have several parts separated by a full colon, -from which hledger derives a hierarchical chart of accounts. They can -be anything you like, but in finance there are traditionally five -top-level accounts: 'assets', 'liabilities', 'revenue', 'expenses', and -'equity'. - - Account names may contain single spaces, eg: 'assets:accounts -receivable'. Because of this, they must always be followed by *two or -more spaces* (or newline). - - Account names can be aliased. - - -File: hledger.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: JOURNAL FORMAT - -12.10 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 - -12.10.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 detail below. - - -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts - -12.10.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 - -12.10.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, in JOURNAL FORMAT -> Declaring commodities. 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 - -12.10.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. - - Transaction price 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 transaction price). 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 - -12.10.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"). (Guaranteed since hledger 1.17.1; in older versions -this could vary if hledger was built with Decimal < 0.5.1.) - - -File: hledger.info, Node: Transaction prices, Next: Lot prices lot dates, Prev: Amounts, Up: JOURNAL FORMAT - -12.11 Transaction prices -======================== - -Within a transaction, you can note an amount's price in another -commodity. This can be used to document the cost (in a purchase) or -selling price (in a sale). For example, transaction prices are useful -to record purchases of a foreign currency. Note transaction prices are -fixed at the time of the transaction, and do not change over time. See -also market prices, which represent prevailing exchange rates on a -certain date. - - There are several ways to record a transaction price: - - 1. Write the price per unit, as '@ UNITPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as '@@ TOTALPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - 4. Like 1, but the '@' is parenthesised, i.e. '(@)'; this is for - compatibility with Ledger journals (Virtual posting costs), and is - equivalent to 1 in hledger. - - 5. Like 2, but as in 4 the '@@' is parenthesised, i.e. '(@@)'; in - hledger, this is equivalent to 2. - - Use the '-B/--cost' flag to convert amounts to their transaction -price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in -Ledger). Eg here is how -B affects the balance report for the example -above: - -$ hledger bal -N --flat - $-135 assets:dollars - €100 assets:euros -$ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction -price is inferred: the inferred price will be in the commodity of the -last amount. So if example 3's postings are reversed, while the -transaction is equivalent, -B shows something different: - -2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros €100 ; for 100 euros - -$ hledger bal -N --flat -B - €-100 assets:dollars # <- the dollars' selling price - €100 assets:euros - - -File: hledger.info, Node: Lot prices lot dates, Next: Balance assertions, Prev: Transaction prices, Up: JOURNAL FORMAT - -12.12 Lot prices, lot dates -=========================== - -Ledger allows another kind of price, lot price (four variants: -'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}', -'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified. -These are normally used to select a lot when selling investments. -hledger will parse these, for compatibility with Ledger journals, but -currently ignores them. A transaction price, lot price and/or lot date -may appear in any order, after the posting amount and before the balance -assertion if any. - - -File: hledger.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices lot dates, Up: JOURNAL FORMAT - -12.13 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, 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 - -12.13.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 - -12.13.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 - -12.13.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 - -12.13.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 - -12.13.5 Assertions and prices ------------------------------ - -Balance assertions ignore transaction prices, and should normally be -written without one: - -2019/1/1 - (a) $1 @ €1 = $1 - - We do allow prices to be written there, however, and print shows -them, even though they don't affect whether the assertion passes or -fails. This is for backward compatibility (hledger's close command used -to generate balance assertions with prices), and because balance -_assignments_ do use them (see below). - - -File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions - -12.13.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 - -12.13.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 - -12.13.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 - -12.13.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: Balance assignments, Next: Directives, Prev: Balance assertions, Up: JOURNAL FORMAT - -12.14 Balance assignments -========================= - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). Note that using balance assignments makes your journal a -little less explicit; to know the exact amount posted, you have to run -hledger or do the calculations yourself, instead of just reading it. - -* Menu: - -* Balance assignments and prices:: - - -File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments - -12.14.1 Balance assignments and prices --------------------------------------- - -A transaction price in a balance assignment will cause the calculated -amount to have that price attached: - -2019/1/1 - (a) = $1 @ €2 - -$ hledger print --explicit -2019-01-01 - (a) $1 @ €2 = $1 @ €2 - - -File: hledger.info, Node: Directives, Next: Directives and multiple files, Prev: Balance assignments, Up: JOURNAL FORMAT - -12.15 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 add some as your needs grow. Here is an overview of -directives by purpose: - -purpose directives command line - options with - similar effect ---------------------------------------------------------------------------- -*READING/GENERATING DATA:* -Declare a commodity's or 'commodity', 'D', -file's decimal mark to help 'decimal-mark' -parse amounts accurately -Apply changes to the data 'alias', 'apply '--alias' -while parsing account', 'comment', - 'D', 'Y' -Inline extra data files 'include' multiple - '-f/--file''s -Generate extra transactions or '~' -budget goals -Generate extra postings '=' -*CHECKING FOR ERRORS:* -Define valid entities to allow 'account', -stricter error checking 'commodity', 'payee' -*DISPLAYING REPORTS:* -Declare accounts' display 'account' -order and accounting type -Declare commodity display 'commodity', 'D' '-c/--commodity-style' -styles - - And here are all the directives and their precise effects: - -directiveeffects ends - at - file - end? ---------------------------------------------------------------------------- -*'account'*Declares an account, for checking all entries in all files; - and its display order and type, for reports. Subdirectives: - any text, ignored. -*'alias'*Rewrites account names, in following entries until end of Y - current file or 'end aliases'. -*'applyPrepends a common parent account to all account names, in Y -account'*following entries until end of current file or 'end apply - account'. -*'comment'*Ignores part of the journal file, until end of current fileY - or 'end comment'. -*'commodity'*Declares a commodity, for checking all entries in all files;N, - the decimal mark for parsing amounts of this commodity, for Y - following entries until end of current file; and its display - style, for reports. Takes precedence over 'D'. - Subdirectives: 'format' (alternate syntax). -*'D'* Sets a default commodity to use for no-symbol amounts, and Y - its decimal mark for parsing amounts of this commodity in - following entries until end of current file; and its display - style, for reports. -*'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 they - were written inline. -*'payee'*Declares a payee name, for checking all entries in all files. -*'P'* Declares a market price for a commodity on some date, for - valuation reports. -*'Y'* Declares a year for yearless dates, for following entries Y - until end of current file. -*'~'* Declares a periodic transaction rule that generates future -(tilde)transactions with '--forecast' and budget goals with 'balance - --budget'. -*'='* Declares an auto posting rule that generates extra postings partly -(equals)on matched transactions with '--auto', in current, parent, - and child files (but not sibling files, see #1212). - - -File: hledger.info, Node: Directives and multiple files, Next: Comment blocks, Prev: Directives, Up: JOURNAL FORMAT - -12.16 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: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: JOURNAL FORMAT - -12.17 Comment blocks -==================== - -A line containing just 'comment' starts a commented region of the file, -and a line containing just 'end comment' (or the end of the current -file) ends it. See also comments. - - -File: hledger.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: JOURNAL FORMAT - -12.18 Including other files -=========================== - -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: Default year, Next: Declaring payees, Prev: Including other files, Up: JOURNAL FORMAT - -12.19 Default year -================== - -You can set a default year to be used for subsequent dates which don't -specify a year. This is a line beginning with 'Y' followed by the year. -Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -Y2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - -File: hledger.info, Node: Declaring payees, Next: Declaring the decimal mark, Prev: Default year, Up: JOURNAL FORMAT - -12.20 Declaring payees -====================== - -The 'payee' 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 - - -File: hledger.info, Node: Declaring the decimal mark, Next: Declaring commodities, Prev: Declaring payees, Up: JOURNAL FORMAT - -12.21 Declaring the decimal mark -================================ - -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: Declaring commodities, Next: Default commodity, Prev: Declaring the decimal mark, Up: JOURNAL FORMAT - -12.22 Declaring commodities -=========================== - -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 - - 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: Declaring commodities - -12.22.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: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: JOURNAL FORMAT - -12.23 Default commodity -======================= - -The 'D' 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). - - The syntax is 'D AMOUNT'. As with 'commodity', 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 - - If both 'commodity' and 'D' directives are found for a commodity, -'commodity' takes precedence for setting decimal mark and display style. - - If you are using 'D' and also checking commodities, you will need to -add a 'commodity' directive similar to the 'D'. (The 'hledger check -commodities' command expects 'commodity' directives, and ignores 'D'). - - -File: hledger.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: JOURNAL FORMAT - -12.24 Declaring market prices -============================= - -The 'P' directive declares a market price, which is an exchange rate -between two commodities on a certain date. (In Ledger, they are called -"historical prices".) These are often obtained from a stock exchange, -cryptocurrency exchange, or the 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: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: JOURNAL FORMAT - -12.25 Declaring accounts -======================== - -'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. - * They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - * They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and - incomestatement. - * They can store other account information, as comments or as tags - which can be used to filter reports. - * They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - * In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - - The simplest form is just the word 'account' followed by a -hledger-style account name, eg this account directive declares the -'assets:bank:checking' account: - -account assets:bank:checking - -* Menu: - -* Account error checking:: -* Account comments:: -* Account subdirectives:: -* Account types:: -* Account display order:: - - -File: hledger.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts - -12.25.1 Account error checking ------------------------------- - -By default, accounts come into existence when a transaction references -them by name. 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 -the 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 in other formats). - * 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 comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts - -12.25.2 Account comments ------------------------- - -Comments, beginning with a semicolon, can be added: - - * on the same line, *after two or more spaces* (because ; is allowed - in account names) - * on the next lines, indented - - An example of both: - -account assets:bank:checking ; same-line comment, note 2+ spaces required before ; - ; next-line comment - ; some tags, type:A, acctnum:12345 - - Compatibility note: same-line comments are not supported by Ledger or -hledger <1.13. - - -File: hledger.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts - -12.25.3 Account subdirectives ------------------------------ - -We also allow (and ignore) Ledger-style indented subdirectives, just for -compatibility.: - -account assets:bank:checking - format blah blah ; <- subdirective, ignored - - Here is the full syntax of account directives: - -account ACCTNAME [;type:ACCTTYPE] [COMMENT] - [;COMMENTS] - [LEDGER-STYLE SUBDIRECTIVES, IGNORED] - - -File: hledger.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts - -12.25.4 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 - CONVERSION & COST).) - - 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. Note the Cash - regexp changed in hledger 1.24.99.2. - - 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 each of them, 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: Account display order, Prev: Account types, Up: Declaring accounts - -12.25.5 Account display order ------------------------------ - -Account directives also set the order in which accounts are displayed, -eg in reports, the hledger-ui accounts screen, and the hledger-web -sidebar. By default accounts are listed in alphabetical order. But if -you have these account directives in the journal: - -account assets -account liabilities -account equity -account revenues -account expenses - - you'll see those accounts displayed in declaration order, not -alphabetically: - -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses - - Undeclared accounts, if any, are displayed last, in alphabetical -order. - - Note that sorting is done at each level of the account tree (within -each group of sibling accounts under the same parent). And currently, -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: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: JOURNAL FORMAT - -12.26 Rewriting accounts -======================== - -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:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts - -12.26.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: Rewriting accounts - -12.26.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: Rewriting accounts - -12.26.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, Prev: Combining aliases, Up: Rewriting accounts - -12.26.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, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: Rewriting accounts - -12.26.5 'end aliases' ---------------------- - -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, Up: Rewriting accounts - -12.26.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: Rewriting accounts - -12.26.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: Default parent account, Next: Periodic transactions, Prev: Rewriting accounts, Up: JOURNAL FORMAT - -12.27 Default parent account -============================ - -You can specify a parent account which will be prepended to all accounts -within a section of the journal. Use the 'apply account' and 'end apply -account' directives like so: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - which is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - If 'end apply account' is omitted, the effect lasts to the end of the -file. Included files are also affected, eg: - -apply account business -include biz.journal -end apply account -apply account personal -include personal.journal - - Prior to hledger 1.0, legacy 'account' and 'end' spellings were also -supported. - - A default parent account also affects account directives. It does -not affect account names being entered via hledger add or hledger-web. -If account aliases are present, they are applied after the default -parent account. - - -File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: Default parent account, Up: JOURNAL FORMAT - -12.28 Periodic transactions -=========================== - -Periodic transaction rules describe transactions that recur. They allow -hledger to generate temporary future transactions to help with -forecasting, so you don't have to write out each one in the journal, and -it's easy to try out different forecasts. - - 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. - - Periodic transaction rules also have a second meaning: they are used -to define budget goals, shown in budget reports. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: -* Forecasting with periodic transactions:: -* Budgeting with periodic transactions:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -12.28.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.): - -~ monthly - expenses:rent $2000 - assets:bank:checking - - There is an additional constraint on the period expression: the start -date must fall on a natural boundary of the interval. Eg 'monthly from -2018/1/1' is valid, but 'monthly from 2018/1/15' is not. - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -12.28.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!, Next: Forecasting with periodic transactions, Prev: Periodic rules and relative dates, Up: Periodic transactions - -12.28.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: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions - -12.28.4 Forecasting with periodic transactions ----------------------------------------------- - -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 with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions - -12.28.5 Budgeting with periodic transactions --------------------------------------------- - -With the '--budget' flag, currently supported by the balance command, -each periodic transaction rule declares recurring budget goals for the -specified accounts. Eg the first example above declares a goal of -spending $2000 on rent (and also, a goal of depositing $2000 into -checking) every month. Goals and actual performance can then be -compared in budget reports. - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Auto postings, Prev: Periodic transactions, Up: JOURNAL FORMAT - -12.29 Auto postings -=================== - -"Automated postings" or "auto postings" are extra postings which get -added automatically to transactions which match certain queries, defined -by "auto posting rules", when you use the '--auto' flag. - - 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 - -12.29.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 - -12.29.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 - -12.29.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 - -12.29.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: CSV FORMAT, Next: TIMECLOCK FORMAT, Prev: JOURNAL FORMAT, Up: Top - -13 CSV FORMAT -************* - -How hledger reads CSV data, and the CSV rules file format. - - hledger can read CSV files (Character Separated Value - usually -comma, semicolon, or tab) containing dated records as if they were -journal files, automatically converting each CSV record into a -transaction. - - (To learn about _writing_ CSV, see CSV output.) - - We describe each CSV file's format with a corresponding _rules file_. -By default this is named like the CSV file with a '.rules' extension -added. Eg when reading 'FILE.csv', hledger also looks for -'FILE.csv.rules' in the same directory as 'FILE.csv'. You can specify a -different rules file with the '--rules-file' option. If a rules file is -not found, hledger will create a sample rules file, which you'll need to -adjust. - - This file contains rules describing the CSV data (header line, fields -layout, date format etc.), and how to construct hledger journal entries -(transactions) from it. Often there will also be a list of conditional -rules for categorising transactions based on their descriptions. Here's -an overview of the CSV rules; these are described more fully below, -after the examples: - -*'skip'* skip one or more header lines or matched - CSV records -*'fields' list* name CSV fields, assign them to hledger - fields -*field assignment* assign a value to one hledger field, with - interpolation -*Field names* hledger field names, used in the fields - list and field assignments -*'separator'* a custom field separator -*'if' block* apply some rules to CSV records matched by - patterns -*'if' table* apply some rules to CSV records matched by - patterns, alternate syntax -*'end'* skip the remaining CSV records -*'date-format'* how to parse dates in CSV records -*'decimal-mark'* the decimal mark used in CSV amounts, if - ambiguous -*'newest-first'* disambiguate record order when there's only - one date -*'include'* inline another CSV rules file -*'balance-type'* choose which type of balance assignments to - use - - Note, for best error messages when reading CSV files, use a '.csv', -'.tsv' or '.ssv' file extension or file prefix - see File Extension -below. - - There's an introductory Convert CSV files tutorial on hledger.org. - -* Menu: - -* Examples:: -* CSV rules:: -* Tips:: - - -File: hledger.info, Node: Examples, Next: CSV rules, Up: CSV FORMAT - -13.1 Examples -============= - -Here are some sample hledger CSV rules files. See also the full -collection at: -https://github.com/simonmichael/hledger/tree/master/examples/csv - -* Menu: - -* Basic:: -* Bank of Ireland:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Basic, Next: Bank of Ireland, Up: Examples - -13.1.1 Basic ------------- - -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 - - Default account names are chosen, since we didn't set them. - - -File: hledger.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: Examples - -13.1.2 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: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: Examples - -13.1.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: Examples - -13.1.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: CSV rules, Next: Tips, Prev: Examples, Up: CSV FORMAT - -13.2 CSV rules -============== - -The following kinds of rule can appear in the rules file, in any order. -Blank lines and lines beginning with '#' or ';' are ignored. - -* Menu: - -* skip:: -* fields list:: -* field assignment:: -* Field names:: -* separator:: -* if block:: -* if table:: -* end:: -* date-format:: -* decimal-mark:: -* newest-first:: -* include:: -* balance-type:: - - -File: hledger.info, Node: skip, Next: fields list, Up: CSV rules - -13.2.1 'skip' -------------- - -skip N - - The word "skip" followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines preceding the CSV data. -(Empty/blank lines are skipped automatically.) You'll need this -whenever your CSV data contains header lines. - - It also has a second purpose: it can be used inside if blocks to -ignore certain CSV records (described below). - - -File: hledger.info, Node: fields list, Next: field assignment, Prev: skip, Up: CSV rules - -13.2.2 'fields' list --------------------- - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word "fields" followed by comma-separated field -names) is the quick way to assign CSV field values to hledger fields. -(The other way is field assignments, see below.) A fields list does -does two things: - - 1. It names the CSV fields. This is optional, but can be convenient - later for interpolating them. - - 2. Whenever you use a standard hledger field name (defined below), the - CSV value is assigned to that part of the hledger 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 - - Tips: - - * The fields list always use commas, even if your CSV data uses - another separator character. - * Currently 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). - * If the CSV contains column headings, it's a good idea to use these, - suitably modified, as the basis for your field names (eg - lower-cased, with underscores instead of spaces). - * If some heading names match standard hledger fields, but you don't - want to set the hledger fields directly, alter those names, eg by - appending an underscore. - * Fields you don't care about can be given a dummy name (eg: '_' ), - or no name. - - -File: hledger.info, Node: field assignment, Next: Field names, Prev: fields list, Up: CSV rules - -13.2.3 field assignment ------------------------ - -HLEDGERFIELDNAME 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 -('%CSVFIELDNAME'). - - 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: separator, Prev: field assignment, Up: CSV rules - -13.2.4 Field names ------------------- - -Here are the standard hledger field (and pseudo-field) names, which you -can use in a fields list and in field assignments. For more about the -transaction parts they refer to, see Transactions. - -* 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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.6 comment field -...................... - -'comment' sets the transaction's comment, if any. - - 'commentN', where N is a number, sets the Nth posting's comment. - - Tips: - - * 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 - -13.2.4.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, and in conditional blocks. - - 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 - -13.2.4.8 amount field -..................... - -'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. - - 'amountN-in' and 'amountN-out' can be used instead, if the CSV uses -separate fields for debits and credits (inflows and outflows). hledger -assumes both of these CSV fields are unsigned, and will automatically -negate the "-out" value. If they are signed, see "Setting amounts" -below. - - 'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep -pre-hledger-1.17 CSV rules files working (and for occasional -convenience). They are suitable only for two-posting transactions; they -set both posting 1's and posting 2's amount. Posting 2's amount will be -negated, and also converted to cost if there's a transaction price. - - If you have an existing rules file using the unnumbered form, you -might want to use the numbered form in certain conditional blocks, -without having to update and retest all the old rules. To facilitate -this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of -'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores -them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned, -avoiding conflicts. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -13.2.4.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 - -13.2.4.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: separator, Next: if block, Prev: Field names, Up: CSV rules - -13.2.5 '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: if block, Next: if table, Prev: separator, Up: CSV rules - -13.2.6 'if' block ------------------ - -if MATCHER - RULE - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - Conditional blocks ("if blocks") are a block of rules that are -applied only to CSV records which match certain patterns. They are -often used for customising account names based on transaction -descriptions. - -* Menu: - -* Matching the whole record:: -* Matching individual fields:: -* Combining matchers:: -* Rules applied on successful match:: - - -File: hledger.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block - -13.2.6.1 Matching the whole record -.................................. - -Each MATCHER can be a record matcher, which looks like this: - -REGEX - - REGEX is a case-insensitive regular expression that tries to match -anywhere within the CSV record. It is a POSIX ERE (extended regular -expression) that also supports GNU word boundaries ('\b', '\B', '\<', -'\>'), and nothing else. If you have trouble, be sure to check our doc: -https://hledger.org/hledger.html#regular-expressions - - Important note: the record that is matched is not the original -record, but a synthetic one, with any enclosing double quotes (but not -enclosing whitespace) removed, and always comma-separated (which means -that a field containing a comma will appear like two fields). Eg, if -the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will -actually see '2020-01-01,Acme, Inc., 1,000'). - - -File: hledger.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block - -13.2.6.2 Matching individual fields -................................... - -Or, MATCHER can be a field matcher, like this: - -%CSVFIELD REGEX - - which matches just the content of a particular CSV field. CSVFIELD -is a percent sign followed by the field's name or column number, like -'%date' or '%1'. - - -File: hledger.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block - -13.2.6.3 Combining matchers -........................... - -A single matcher can be written on the same line as the "if"; or -multiple matchers can be written on the following lines, non-indented. -Multiple matchers are OR'd (any one of them can match), unless one -begins with an '&' symbol, in which case it is AND'ed with the previous -matcher. - -if -MATCHER -& MATCHER - RULE - - -File: hledger.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block - -13.2.6.4 Rules applied on successful match -.......................................... - -After the patterns there should be one or more rules to apply, all -indented by at least one space. Three kinds of rule are allowed in -conditional blocks: - - * field assignments (to set a hledger field) - * skip (to skip the matched CSV record) - * end (to skip all remaining CSV records). - - Examples: - -# if the CSV record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the CSV record contains any of these patterns, set account2 and comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - -File: hledger.info, Node: if table, Next: end, Prev: if block, Up: CSV rules - -13.2.7 'if' table ------------------ - -if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn -MATCHER1,VALUE11,VALUE12,...,VALUE1n -MATCHER2,VALUE21,VALUE22,...,VALUE2n -MATCHER3,VALUE31,VALUE32,...,VALUE3n - - - Conditional tables ("if tables") are a different syntax to specify -field assignments that will be applied only to CSV records which match -certain patterns. - - MATCHER could be either field or record matcher, as described above. -When MATCHER matches, values from that row would be assigned to the CSV -fields named on the 'if' line, in the same order. - - Therefore 'if' table is exactly equivalent to a sequence of of 'if' -blocks: - -if MATCHER1 - CSVFIELDNAME1 VALUE11 - CSVFIELDNAME2 VALUE12 - ... - CSVFIELDNAMEn VALUE1n - -if MATCHER2 - CSVFIELDNAME1 VALUE21 - CSVFIELDNAME2 VALUE22 - ... - CSVFIELDNAMEn VALUE2n - -if MATCHER3 - CSVFIELDNAME1 VALUE31 - CSVFIELDNAME2 VALUE32 - ... - CSVFIELDNAMEn VALUE3n - - Each line starting with MATCHER should contain enough (possibly -empty) values for all the listed fields. - - Rules would be checked and applied in the order they are listed in -the table and, like with 'if' blocks, later rules (in the same or -another table) or 'if' blocks could override the effect of any rule. - - Instead of ',' you can use a variety of other non-alphanumeric -characters as a separator. First character after 'if' is taken to be -the separator for the rest of the table. It is the responsibility of -the user to ensure that separator does not occur inside MATCHERs and -values - there is no way to escape separator. - - 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: end, Next: date-format, Prev: if table, Up: CSV rules - -13.2.8 'end' ------------- - -This rule can be used inside if blocks (only), to make hledger stop -reading this CSV file and move on to the next input file, or to command -execution. Eg: - -# ignore everything following the first empty record -if ,,,, - end - - -File: hledger.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV rules - -13.2.9 '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 -date parsing pattern, which 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 - - For the supported strptime syntax, see: -https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime - - Note that although you can parse date-times which include a time -zone, that time zone is ignored; it will not change the date that is -parsed. This means when reading CSV data with times not in your local -time zone, dates can be "off by one". - - -File: hledger.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV rules - -13.2.10 '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: newest-first, Next: include, Prev: decimal-mark, Up: CSV rules - -13.2.11 'newest-first' ----------------------- - -hledger always sorts the generated transactions by date. Transactions -on the same date should appear in the same order as their CSV records, -as hledger can usually auto-detect whether the CSV's normal order is -oldest first or newest first. But if all of the following are true: - - * the CSV might sometimes contain just one day of data (all records - having the same date) - * the CSV records are normally in reverse chronological order (newest - at the top) - * and you care about preserving the order of same-day transactions - - then, you should add the 'newest-first' rule as a hint. Eg: - -# tell hledger explicitly that the CSV is normally newest first -newest-first - - -File: hledger.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV rules - -13.2.12 '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: balance-type, Prev: include, Up: CSV rules - -13.2.13 '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: Tips, Prev: CSV rules, Up: CSV FORMAT - -13.3 Tips -========= - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* 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:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Tips - -13.3.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: Tips - -13.3.2 Valid CSV ----------------- - -hledger accepts CSV conforming to RFC 4180. When CSV values are -enclosed in quotes, note: - - * they must be double quotes (not single quotes) - * spaces outside the quotes are not allowed - - -File: hledger.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: Tips - -13.3.3 File Extension ---------------------- - -To help hledger identify the format and show the right error messages, -CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or -'.tsv' filename extension. Or, the file path should be prefixed with -'csv:', 'ssv:' or 'tsv:'. Eg: - -$ hledger -f foo.ssv print - - or: - -$ cat foo | hledger -f ssv:- foo - - You can override the file extension with a separator rule if needed. -See also: Input files in the hledger manual. - - -File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: Tips - -13.3.4 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: Tips - -13.3.5 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: Tips - -13.3.6 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: Tips - -13.3.7 Setting amounts ----------------------- - -Some tips on using the amount-setting rules discussed above. - - Here are the ways to set a posting's amount: - - 1. *If the CSV has a single amount field:* - Assign (via a fields list or a field assignment) to 'amountN'. - This sets the Nth posting's amount. N is usually 1 or 2 but can go - up to 99. - - 2. *If the CSV has separate amount fields for debit & credit (in & - out):* - - a. *If both fields are unsigned:* - Assign to 'amountN-in' and 'amountN-out'. This sets posting - N's amount to whichever of these has a non-zero value, and - negates the "-out" value. - - b. *If either field is signed (can contain a minus sign):* - Use a conditional rule to flip the sign (of non-empty values). - Since hledger always negates amountN-out, if it was already - negative, we must undo that by negating once more (but only if - the field is non-empty): - - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields, or neither field, can contain a non-zero - value:* - hledger normally expects exactly one of the fields to have a - non-zero value. Eg, the 'amountN-in'/'amountN-out' rules - would reject value pairs like these: - - "", "" - "0", "0" - "1", "none" - - So, use smarter conditional rules to set the amount from the - appropriate field. Eg, these rules would make it use only the - value containing non-zero digits, handling the above: - - 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:* - Assign to 'amount' (or to 'amount-in' and 'amount-out'). (This is - the legacy numberless syntax, which sets amount1 and amount2 and - converts amount2 to cost.) - - 4. *If the CSV has the balance instead of the transaction amount:* - Assign to 'balanceN', which sets posting N's amount indirectly via - a balance assignment. (Old syntax: 'balance', equivalent to - 'balance1'.) - - * *If hledger guesses the wrong default account name:* - When setting the amount via balance assertion, hledger may - guess the wrong default account name. So, set the account - name explicitly, eg: - - fields date, description, balance1 - account1 assets:checking - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Tips - -13.3.8 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: Tips - -13.3.9 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: Tips - -13.3.10 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: Tips - -13.3.11 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, Prev: Referencing other fields, Up: Tips - -13.3.12 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 %CSVFIELDNAME references), or a - default - * generate a synthetic hledger transaction 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: TIMECLOCK FORMAT, Next: TIMEDOT FORMAT, Prev: CSV FORMAT, Up: Top - -14 TIMECLOCK FORMAT -******************* - -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). - -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 FORMAT, Next: COMMON TASKS, Prev: TIMECLOCK FORMAT, Up: Top - -15 TIMEDOT FORMAT -***************** - -'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.: - - * Lines beginning with '#' or ';', and blank lines, are ignored. - - * 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.) - - * One or more stars ('*') followed by a space, at the start of a - line, is ignored. So date lines or time transaction lines can also - be Org-mode headlines. - - * All Org-mode headlines before the first date line are ignored. - - 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: COMMON TASKS, Next: LIMITATIONS, Prev: TIMEDOT FORMAT, Up: Top - -16 COMMON TASKS -*************** - -Here are some quick examples of how to do some basic tasks with hledger. -For more details, see the reference section below, the -hledger_journal(5) manual, or the more extensive docs at -https://hledger.org. - -* 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: COMMON TASKS - -16.1 Getting help -================= - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show common and command options, and command help -$ hledger help # show available manuals/topics -$ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) -$ hledger help journal -m # show the journal topic, as a man page scrolled to that section -$ hledger help --help # show more detailed help for the help command - - Find more docs, chat, mail list, reddit, issue tracker: -https://hledger.org/support.html-feedback - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS - -16.2 Constructing command lines -=============================== - -hledger has an extensive and powerful command line interface. We strive -to keep it simple and ergonomic, but you may run into one of the -confusing real world details described in OPTIONS, below. If that -happens, here are some tips that may help: - - * command-specific options must go after the command (it's fine to - put all options there) ('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 is being parsed, add '--debug=2'. - - -File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS - -16.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: COMMON TASKS - -16.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: COMMON TASKS - -16.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: COMMON TASKS - -16.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: COMMON TASKS - -16.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 --flat -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 --flat -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: COMMON TASKS - -16.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. - - -File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: COMMON TASKS, Up: Top - -17 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 file -format differences. - - On large data files, hledger is slower and uses more memory than -Ledger. - - -File: hledger.info, Node: TROUBLESHOOTING, Prev: LIMITATIONS, Up: Top - -18 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 - - -Tag Table: -Node: Top208 -Node: OPTIONS2612 -Ref: #options2713 -Node: General options2855 -Ref: #general-options2980 -Node: Command options7193 -Ref: #command-options7344 -Node: Command arguments7744 -Ref: #command-arguments7902 -Node: Special characters8782 -Ref: #special-characters8945 -Node: Single escaping shell metacharacters9108 -Ref: #single-escaping-shell-metacharacters9349 -Node: Double escaping regular expression metacharacters9952 -Ref: #double-escaping-regular-expression-metacharacters10263 -Node: Triple escaping for add-on commands10789 -Ref: #triple-escaping-for-add-on-commands11049 -Node: Less escaping11693 -Ref: #less-escaping11847 -Node: Unicode characters12171 -Ref: #unicode-characters12336 -Node: Regular expressions13748 -Ref: #regular-expressions13888 -Node: ENVIRONMENT15624 -Ref: #environment15740 -Node: DATA FILES17232 -Ref: #data-files17351 -Node: Data formats17890 -Ref: #data-formats18008 -Node: Multiple files19402 -Ref: #multiple-files19544 -Node: Strict mode20013 -Ref: #strict-mode20128 -Node: TIME PERIODS20852 -Ref: #time-periods20969 -Node: Smart dates21067 -Ref: #smart-dates21193 -Node: Report start & end date23023 -Ref: #report-start-end-date23198 -Node: Report intervals24865 -Ref: #report-intervals25033 -Node: Period expressions26772 -Ref: #period-expressions26912 -Node: Period expressions with a report interval28643 -Ref: #period-expressions-with-a-report-interval28875 -Node: More complex report intervals29956 -Ref: #more-complex-report-intervals30205 -Node: Intervals with custom start date30845 -Ref: #intervals-with-custom-start-date31077 -Node: Periods or dates ?32651 -Ref: #periods-or-dates32853 -Node: Events on multiple weekdays33295 -Ref: #events-on-multiple-weekdays33474 -Node: DEPTH34337 -Ref: #depth34437 -Node: QUERIES34771 -Ref: #queries34880 -Node: Query types35821 -Ref: #query-types35940 -Node: Combining query terms39114 -Ref: #combining-query-terms39289 -Node: Queries and command options40092 -Ref: #queries-and-command-options40295 -Node: Queries and account aliases40544 -Ref: #queries-and-account-aliases40747 -Node: Queries and valuation40867 -Ref: #queries-and-valuation41060 -Node: Querying with account aliases41289 -Ref: #querying-with-account-aliases41498 -Node: Querying with cost or value41628 -Ref: #querying-with-cost-or-value41803 -Node: CONVERSION & COST42104 -Ref: #conversion-cost42237 -Node: Recording conversions43126 -Ref: #recording-conversions43298 -Node: Implicit conversion43750 -Ref: #implicit-conversion43907 -Node: Priced conversion44726 -Ref: #priced-conversion44905 -Node: Equity conversion45313 -Ref: #equity-conversion45497 -Node: Priced equity conversion46285 -Ref: #priced-equity-conversion46457 -Node: Inferring missing conversion rates46805 -Ref: #inferring-missing-conversion-rates47045 -Node: Inferring missing equity postings47161 -Ref: #inferring-missing-equity-postings47392 -Node: Cost reporting47540 -Ref: #cost-reporting47717 -Node: Conversion summary48237 -Ref: #conversion-summary48380 -Node: VALUATION49102 -Ref: #valuation49220 -Node: -V Value49987 -Ref: #v-value50111 -Node: -X Value in specified commodity50306 -Ref: #x-value-in-specified-commodity50499 -Node: Valuation date50648 -Ref: #valuation-date50810 -Node: Market prices51247 -Ref: #market-prices51429 -Node: --infer-market-prices market prices from transactions52612 -Ref: #infer-market-prices-market-prices-from-transactions52879 -Node: Valuation commodity54763 -Ref: #valuation-commodity54974 -Node: Simple valuation examples56200 -Ref: #simple-valuation-examples56396 -Node: --value Flexible valuation57055 -Ref: #value-flexible-valuation57257 -Node: More valuation examples58901 -Ref: #more-valuation-examples59108 -Node: Interaction of valuation and queries61107 -Ref: #interaction-of-valuation-and-queries61346 -Node: Effect of valuation on reports61818 -Ref: #effect-of-valuation-on-reports62013 -Node: PIVOTING69710 -Ref: #pivoting69815 -Node: OUTPUT71501 -Ref: #output71603 -Node: Output destination71694 -Ref: #output-destination71828 -Node: Output styling72485 -Ref: #output-styling72633 -Node: Output format73390 -Ref: #output-format73534 -Node: CSV output74898 -Ref: #csv-output75016 -Node: HTML output75119 -Ref: #html-output75259 -Node: JSON output75353 -Ref: #json-output75493 -Node: SQL output76410 -Ref: #sql-output76528 -Node: Commodity styles77029 -Ref: #commodity-styles77156 -Node: COMMANDS77932 -Ref: #commands78044 -Node: accounts81409 -Ref: #accounts81509 -Node: activity82317 -Ref: #activity82429 -Node: add82812 -Ref: #add82915 -Node: aregister85710 -Ref: #aregister85824 -Node: aregister and custom posting dates88493 -Ref: #aregister-and-custom-posting-dates88659 -Node: balance89211 -Ref: #balance89330 -Node: balance features90323 -Ref: #balance-features90463 -Node: Simple balance report92387 -Ref: #simple-balance-report92569 -Node: Filtered balance report94049 -Ref: #filtered-balance-report94236 -Node: List or tree mode94563 -Ref: #list-or-tree-mode94731 -Node: Depth limiting96076 -Ref: #depth-limiting96242 -Node: Dropping top-level accounts96843 -Ref: #dropping-top-level-accounts97045 -Node: Multi-period balance report97355 -Ref: #multi-period-balance-report97568 -Node: Showing declared accounts99843 -Ref: #showing-declared-accounts100036 -Node: Data layout100567 -Ref: #data-layout100722 -Node: Sorting by amount108662 -Ref: #sorting-by-amount108817 -Node: Percentages109487 -Ref: #percentages109645 -Node: Balance change end balance110606 -Ref: #balance-change-end-balance110799 -Node: Balance report types112227 -Ref: #balance-report-types112417 -Node: Useful balance reports116696 -Ref: #useful-balance-reports116877 -Node: Budget report117962 -Ref: #budget-report118146 -Node: Budget report start date123421 -Ref: #budget-report-start-date123599 -Node: Budgets and subaccounts124931 -Ref: #budgets-and-subaccounts125138 -Node: Selecting budget goals128578 -Ref: #selecting-budget-goals128750 -Node: Customising single-period balance reports129784 -Ref: #customising-single-period-balance-reports129993 -Node: balancesheet132168 -Ref: #balancesheet132306 -Node: balancesheetequity133605 -Ref: #balancesheetequity133756 -Node: cashflow135136 -Ref: #cashflow135260 -Node: check136766 -Ref: #check136871 -Node: Basic checks137505 -Ref: #basic-checks137623 -Node: Strict checks138174 -Ref: #strict-checks138315 -Node: Other checks138751 -Ref: #other-checks138891 -Node: Custom checks139248 -Ref: #custom-checks139368 -Node: close139785 -Ref: #close139889 -Node: close and prices141980 -Ref: #close-and-prices142109 -Node: close date142504 -Ref: #close-date142688 -Node: Example close asset/liability accounts for file transition143445 -Ref: #example-close-assetliability-accounts-for-file-transition143746 -Node: Hiding opening/closing transactions144605 -Ref: #hiding-openingclosing-transactions144876 -Node: close and balance assertions146253 -Ref: #close-and-balance-assertions146511 -Node: Example close revenue/expense accounts to retained earnings147865 -Ref: #example-close-revenueexpense-accounts-to-retained-earnings148143 -Node: codes149033 -Ref: #codes149143 -Node: commodities149855 -Ref: #commodities149984 -Node: descriptions150066 -Ref: #descriptions150196 -Node: diff150500 -Ref: #diff150608 -Node: files151655 -Ref: #files151757 -Node: help151904 -Ref: #help152006 -Node: import152824 -Ref: #import152940 -Node: Deduplication154033 -Ref: #deduplication154158 -Node: Import testing156052 -Ref: #import-testing156217 -Node: Importing balance assignments156705 -Ref: #importing-balance-assignments156911 -Node: Commodity display styles157560 -Ref: #commodity-display-styles157733 -Node: incomestatement157862 -Ref: #incomestatement157997 -Node: notes159302 -Ref: #notes159417 -Node: payees159785 -Ref: #payees159893 -Node: prices160419 -Ref: #prices160527 -Node: print160896 -Ref: #print161008 -Node: print-unique166376 -Ref: #print-unique166504 -Node: register166789 -Ref: #register166918 -Node: Custom register output171668 -Ref: #custom-register-output171799 -Node: register-match173136 -Ref: #register-match173272 -Node: rewrite173623 -Ref: #rewrite173740 -Node: Re-write rules in a file175646 -Ref: #re-write-rules-in-a-file175809 -Node: Diff output format176958 -Ref: #diff-output-format177141 -Node: rewrite vs print --auto178233 -Ref: #rewrite-vs.-print---auto178393 -Node: roi178949 -Ref: #roi179049 -Node: Spaces and special characters in --inv and --pnl180774 -Ref: #spaces-and-special-characters-in---inv-and---pnl181014 -Node: Semantics of --inv and --pnl181502 -Ref: #semantics-of---inv-and---pnl181741 -Node: IRR and TWR explained183591 -Ref: #irr-and-twr-explained183751 -Node: stats186837 -Ref: #stats186938 -Node: tags188318 -Ref: #tags188418 -Node: test189432 -Ref: #test189548 -Node: About add-on commands190295 -Ref: #about-add-on-commands190432 -Node: JOURNAL FORMAT191563 -Ref: #journal-format191691 -Node: Transactions193918 -Ref: #transactions194033 -Node: Dates195047 -Ref: #dates195163 -Node: Simple dates195228 -Ref: #simple-dates195348 -Node: Secondary dates195857 -Ref: #secondary-dates196005 -Node: Posting dates197341 -Ref: #posting-dates197464 -Node: Status198836 -Ref: #status198946 -Node: Code200654 -Ref: #code200766 -Node: Description200998 -Ref: #description201126 -Node: Payee and note201446 -Ref: #payee-and-note201554 -Node: Comments201889 -Ref: #comments202011 -Node: Tags203205 -Ref: #tags-1203316 -Node: Postings204709 -Ref: #postings204833 -Node: Virtual postings205859 -Ref: #virtual-postings205970 -Node: Account names207275 -Ref: #account-names207412 -Node: Amounts207900 -Ref: #amounts208037 -Node: Decimal marks digit group marks209022 -Ref: #decimal-marks-digit-group-marks209199 -Node: Commodity210220 -Ref: #commodity210409 -Node: Directives influencing number parsing and display211361 -Ref: #directives-influencing-number-parsing-and-display211622 -Node: Commodity display style212115 -Ref: #commodity-display-style212323 -Node: Rounding214518 -Ref: #rounding214638 -Node: Transaction prices215050 -Ref: #transaction-prices215216 -Node: Lot prices lot dates217647 -Ref: #lot-prices-lot-dates217830 -Node: Balance assertions218318 -Ref: #balance-assertions218496 -Node: Assertions and ordering219569 -Ref: #assertions-and-ordering219760 -Node: Assertions and multiple included files220460 -Ref: #assertions-and-multiple-included-files220722 -Node: Assertions and multiple -f files221222 -Ref: #assertions-and-multiple--f-files221475 -Node: Assertions and commodities221872 -Ref: #assertions-and-commodities222096 -Node: Assertions and prices223276 -Ref: #assertions-and-prices223484 -Node: Assertions and subaccounts223924 -Ref: #assertions-and-subaccounts224147 -Node: Assertions and virtual postings224471 -Ref: #assertions-and-virtual-postings224711 -Node: Assertions and auto postings224843 -Ref: #assertions-and-auto-postings225075 -Node: Assertions and precision225720 -Ref: #assertions-and-precision225904 -Node: Balance assignments226171 -Ref: #balance-assignments226341 -Node: Balance assignments and prices227505 -Ref: #balance-assignments-and-prices227671 -Node: Directives227895 -Ref: #directives228058 -Node: Directives and multiple files232550 -Ref: #directives-and-multiple-files232746 -Node: Comment blocks233438 -Ref: #comment-blocks233615 -Node: Including other files233791 -Ref: #including-other-files233965 -Node: Default year234889 -Ref: #default-year235047 -Node: Declaring payees235454 -Ref: #declaring-payees235625 -Node: Declaring the decimal mark235871 -Ref: #declaring-the-decimal-mark236071 -Node: Declaring commodities236468 -Ref: #declaring-commodities236659 -Node: Commodity error checking239177 -Ref: #commodity-error-checking239327 -Node: Default commodity239842 -Ref: #default-commodity240022 -Node: Declaring market prices241138 -Ref: #declaring-market-prices241327 -Node: Declaring accounts242140 -Ref: #declaring-accounts242320 -Node: Account error checking243544 -Ref: #account-error-checking243710 -Node: Account comments244889 -Ref: #account-comments245073 -Node: Account subdirectives245514 -Ref: #account-subdirectives245699 -Node: Account types246017 -Ref: #account-types246191 -Node: Account display order249866 -Ref: #account-display-order250026 -Node: Rewriting accounts251177 -Ref: #rewriting-accounts251356 -Node: Basic aliases252396 -Ref: #basic-aliases252532 -Node: Regex aliases253276 -Ref: #regex-aliases253438 -Node: Combining aliases254328 -Ref: #combining-aliases254511 -Node: Aliases and multiple files255787 -Ref: #aliases-and-multiple-files255986 -Node: end aliases256565 -Ref: #end-aliases256759 -Node: Aliases can generate bad account names256908 -Ref: #aliases-can-generate-bad-account-names257151 -Node: Aliases and account types257736 -Ref: #aliases-and-account-types257933 -Node: Default parent account258629 -Ref: #default-parent-account258819 -Node: Periodic transactions259703 -Ref: #periodic-transactions259886 -Node: Periodic rule syntax261841 -Ref: #periodic-rule-syntax262021 -Node: Periodic rules and relative dates262480 -Ref: #periodic-rules-and-relative-dates262748 -Node: Two spaces between period expression and description!263259 -Ref: #two-spaces-between-period-expression-and-description263585 -Node: Forecasting with periodic transactions264269 -Ref: #forecasting-with-periodic-transactions264568 -Node: Budgeting with periodic transactions267339 -Ref: #budgeting-with-periodic-transactions267572 -Node: Auto postings267981 -Ref: #auto-postings268117 -Node: Auto postings and multiple files270296 -Ref: #auto-postings-and-multiple-files270494 -Node: Auto postings and dates270703 -Ref: #auto-postings-and-dates270971 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions271146 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions271491 -Node: Auto posting tags271994 -Ref: #auto-posting-tags272203 -Node: CSV FORMAT272839 -Ref: #csv-format272967 -Node: Examples275596 -Ref: #examples275699 -Node: Basic275907 -Ref: #basic276009 -Node: Bank of Ireland276551 -Ref: #bank-of-ireland276688 -Node: Amazon278150 -Ref: #amazon278270 -Node: Paypal279989 -Ref: #paypal280085 -Node: CSV rules287729 -Ref: #csv-rules287847 -Node: skip288180 -Ref: #skip288280 -Node: fields list288655 -Ref: #fields-list288794 -Node: field assignment290360 -Ref: #field-assignment290512 -Node: Field names291547 -Ref: #field-names291687 -Node: date field292067 -Ref: #date-field292187 -Node: date2 field292235 -Ref: #date2-field292378 -Node: status field292434 -Ref: #status-field292579 -Node: code field292628 -Ref: #code-field292775 -Node: description field292820 -Ref: #description-field292982 -Node: comment field293041 -Ref: #comment-field293198 -Node: account field293509 -Ref: #account-field293661 -Node: amount field294236 -Ref: #amount-field294387 -Node: currency field295632 -Ref: #currency-field295787 -Node: balance field296044 -Ref: #balance-field296178 -Node: separator296550 -Ref: #separator296682 -Node: if block297222 -Ref: #if-block297349 -Node: Matching the whole record297750 -Ref: #matching-the-whole-record297927 -Node: Matching individual fields298730 -Ref: #matching-individual-fields298936 -Node: Combining matchers299160 -Ref: #combining-matchers299358 -Node: Rules applied on successful match299671 -Ref: #rules-applied-on-successful-match299864 -Node: if table300518 -Ref: #if-table300639 -Node: end302377 -Ref: #end302491 -Node: date-format302715 -Ref: #date-format302849 -Node: decimal-mark303845 -Ref: #decimal-mark303992 -Node: newest-first304331 -Ref: #newest-first304474 -Node: include305157 -Ref: #include305290 -Node: balance-type305734 -Ref: #balance-type305856 -Node: Tips306556 -Ref: #tips306647 -Node: Rapid feedback306946 -Ref: #rapid-feedback307065 -Node: Valid CSV307517 -Ref: #valid-csv307649 -Node: File Extension307841 -Ref: #file-extension307995 -Node: Reading multiple CSV files308424 -Ref: #reading-multiple-csv-files308611 -Node: Valid transactions308852 -Ref: #valid-transactions309032 -Node: Deduplicating importing309660 -Ref: #deduplicating-importing309841 -Node: Setting amounts310877 -Ref: #setting-amounts311034 -Node: Amount signs313478 -Ref: #amount-signs313632 -Node: Setting currency/commodity314319 -Ref: #setting-currencycommodity314507 -Node: Amount decimal places315681 -Ref: #amount-decimal-places315873 -Node: Referencing other fields316185 -Ref: #referencing-other-fields316384 -Node: How CSV rules are evaluated317281 -Ref: #how-csv-rules-are-evaluated317456 -Node: TIMECLOCK FORMAT318907 -Ref: #timeclock-format319047 -Node: TIMEDOT FORMAT321108 -Ref: #timedot-format321246 -Node: COMMON TASKS325808 -Ref: #common-tasks325937 -Node: Getting help326344 -Ref: #getting-help326478 -Node: Constructing command lines327068 -Ref: #constructing-command-lines327262 -Node: Starting a journal file327959 -Ref: #starting-a-journal-file328159 -Node: Setting opening balances329347 -Ref: #setting-opening-balances329545 -Node: Recording transactions332686 -Ref: #recording-transactions332868 -Node: Reconciling333424 -Ref: #reconciling333569 -Node: Reporting335826 -Ref: #reporting335968 -Node: Migrating to a new file339967 -Ref: #migrating-to-a-new-file340117 -Node: LIMITATIONS340416 -Ref: #limitations340544 -Node: TROUBLESHOOTING341287 -Ref: #troubleshooting341402 +manual is for hledger 1.26.1. + + 'hledger' + + 'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]' + + 'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]' + + hledger is a reliable, cross-platform set of programs for tracking +money, time, or any other commodity, using double-entry accounting and a +simple, editable file format. hledger is inspired by and largely +compatible with ledger(1). + + The basic function of the hledger CLI is to read a plain text file +describing financial transactions (in accounting terms, a general +journal) and print useful reports on standard output, or export them as +CSV. hledger can also read some other file formats such as CSV files, +translating them to journal format. Additionally, hledger lists other +hledger-* executables found in the user's $PATH and can invoke them as +subcommands. + + hledger reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). If using '$LEDGER_FILE', note this +must be a real environment variable, not a shell variable. You can +specify standard input with '-f-'. + + Transactions are dated movements of money between two (or more) named +accounts, and are recorded with journal entries like this: + +2015/10/16 bought food + expenses:food $10 + assets:cash + + Most users use a text editor to edit the journal, usually with an +editor mode such as ledger-mode for added convenience. hledger's +interactive add command is another way to record new transactions. +hledger never changes existing transactions. + + To get started, you can either save some entries like the above in +'~/.hledger.journal', or run 'hledger add' and follow the prompts. Then +try some commands like 'hledger print' or 'hledger balance'. Run +'hledger' with no arguments for a list of commands. + +* Menu: + +* OPTIONS:: +* ENVIRONMENT:: +* DATA FILES:: +* TIME PERIODS:: +* DEPTH:: +* QUERIES:: +* CONVERSION & COST:: +* VALUATION:: +* PIVOTING:: +* OUTPUT:: +* COMMANDS:: +* JOURNAL FORMAT:: +* CSV FORMAT:: +* TIMECLOCK FORMAT:: +* TIMEDOT FORMAT:: +* COMMON TASKS:: +* LIMITATIONS:: +* TROUBLESHOOTING:: + + +File: hledger.info, Node: OPTIONS, Next: ENVIRONMENT, Prev: Top, Up: Top + +1 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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 directives and options: '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: DATA FILES, Prev: OPTIONS, Up: Top + +2 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\MyUserName\.hledger.journal'. You can change this by running +a command like this in a powershell window: + +> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" + + (Let us know if you need to be an Administrator, and if this persists +across a reboot.) + + *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: DATA FILES, Next: TIME PERIODS, Prev: ENVIRONMENT, Up: Top + +3 DATA FILES +************ + +hledger reads transactions from one or more data files. The default +data file is '$HOME/.hledger.journal' (or on Windows, something like +'C:/Users/USER/.hledger.journal'). + + You can override this with the '$LEDGER_FILE' environment variable: + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with 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: DATA FILES + +3.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 their own sections, 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: DATA FILES + +3.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: DATA FILES + +3.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: TIME PERIODS, Next: DEPTH, Prev: DATA FILES, Up: Top + +4 TIME PERIODS +************** + +* Menu: + +* Smart dates:: +* Report start & end date:: +* Report intervals:: +* Period expressions:: + + +File: hledger.info, Node: Smart dates, Next: Report start & end date, Up: TIME PERIODS + +4.1 Smart dates +=============== + +hledger's user interfaces accept a flexible "smart date" syntax. Smart +dates allow some english words, can be relative to today's date, and can +have less-significant date parts omitted (defaulting to 1). + + Examples: + +'2004/10/1', 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 + + 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 + + Note "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; those are not affected by '--today'.) + + +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: TIME PERIODS + +4.2 Report start & end date +=========================== + +By default, most hledger reports will show the full span of time +represented by the journal data. 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. + + 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. + * A report interval (see below) will adjust start/end dates, when + needed, so that they fall on subperiod boundaries. + + 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: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: TIME PERIODS + +4.3 Report intervals +==================== + +A report interval can be specified so that commands like register, +balance and activity become multi-period, showing each subperiod as a +separate row or column. + + The following "standard" report intervals can be enabled by using +their corresponding flag: + + * '-D/--daily' + * '-W/--weekly' + * '-M/--monthly' + * '-Q/--quarterly' + * '-Y/--yearly' + + These standard intervals always start on natural interval boundaries: +eg '--weekly' starts on mondays, '--monthly' starts on the first of the +month, '--yearly' always starts on January 1st, etc. + + Certain more complex intervals, and more flexible boundary dates, can +be specified by '-p/--period'. These are described in period +expressions, below. + + Report intervals can only be specified by the flags above, and not by +query arguments, currently. + + Report intervals have another effect: multi-period reports are always +expanded to fill a whole number of subperiods. So if you use a report +interval (other than '--daily'), and you have specified a start or end +date, you may notice those dates being overridden (ie, the report starts +earlier than your requested start date, or ends later than your +requested end date). This is done to ensure "full" first and last +subperiods, so that all subperiods' numbers are comparable. + + To summarise: + + * In multiperiod reports, all subperiods are forced to be the same + length, to simplify reporting. + * Reports with the standard + '--weekly'/'--monthly'/'--quarterly'/'--yearly' intervals are + required to start on the first day of a week/month/quarter/year. + We'd like more flexibility here but it isn't supported yet. + * '--period' (below) can specify more complex intervals, starting on + any date. + + +File: hledger.info, Node: Period expressions, Prev: Report intervals, Up: TIME PERIODS + +4.4 Period expressions +====================== + +The '-p/--period' option accepts period expressions, a shorthand way of +expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of +2009. Note, hledger always treats start dates as inclusive and end +dates as exclusive: + +'-p "from 2009/1/1 to 2009/4/1"' + + Keywords like "from" and "to" are optional, and so are the spaces, as +long as you don't run two dates together. "to" can also be written as +".." or "-". These are equivalent to the above: + +'-p "2009/1/1 2009/4/1"' +'-p2009/1/1to2009/4/1' +'-p2009/1/1..2009/4/1' + + Dates are smart dates, so if the current year is 2009, the above can +also be written as: + +'-p "1/1 4/1"' +'-p "january-apr"' +'-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction in your journal: + +'-p "from 2009/1/1"' everything after january 1, 2009 +'-p "from 2009/1"' the same +'-p "from 2009"' the same +'-p "to 2009"' everything before january 1, 2009 + + A single date with no "from" or "to" defines both the start and end +date like so: + +'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” +'-p "2009/1"' the month of jan; equivalent to “2009/1/1 to 2009/2/1” +'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2” + + Or you can specify a single quarter like so: + +'-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:: +* Intervals with custom start date:: +* Periods or dates ?:: +* Events on multiple weekdays:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +4.4.1 Period expressions with a report interval +----------------------------------------------- + +'-p/--period''s argument can also begin with, or entirely consist of, a +report interval. This should be separated from the start/end dates (if +any) by a space, or the word 'in'. The basic intervals (which can also +be written as command line flags) are 'daily', 'weekly', 'monthly', +'quarterly', and 'yearly'. Some examples: + +'-p "weekly from 2009/1/1 to 2009/4/1"' +'-p "monthly in 2008"' +'-p "quarterly"' + + As mentioned above, the 'weekly', 'monthly', 'quarterly' and 'yearly' +intervals require a report start date that is the first day of a week, +month, quarter or year. And, report start/end dates will be expanded if +needed to span a whole number of intervals. + + For example: + +'-p "weekly from starts on 2008/12/29, closest preceding +2009/1/1 to 2009/4/1"' Monday +'-p "monthly in starts on 2018/11/01 +2008/11/25"' +'-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, +2009-05-05 to which are first and last days of Q2 2009 +2009-06-01"' +'-p "yearly from starts on 2009/01/01, first day of 2009 +2009-12-29"' + + +File: hledger.info, Node: More complex report intervals, Next: Intervals with custom start date, Prev: Period expressions with a report interval, Up: Period expressions + +4.4.2 More complex report intervals +----------------------------------- + +Some more complex kinds of interval are also supported in period +expressions: + + * 'biweekly' + * 'fortnightly' + * 'bimonthly' + * 'every day|week|month|quarter|year' + * 'every N days|weeks|months|quarters|years' + + These too will cause report start/end dates to be expanded, if +needed, to span a whole number of intervals. Examples: + +'-p "bimonthly from periods will have boundaries on 2008/01/01, +2008"' 2008/03/01, ... +'-p "every 2 weeks"' starts on closest preceding Monday +'-p "every 5 months from periods will have boundaries on 2009/03/01, +2009/03"' 2009/08/01, ... + + +File: hledger.info, Node: Intervals with custom start date, Next: Periods or dates ?, Prev: More complex report intervals, Up: Period expressions + +4.4.3 Intervals with custom start date +-------------------------------------- + +All intervals mentioned above are required to start on their natural +calendar boundaries, but the following intervals can start on any date: + + Weekly on 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 custom day: + + * 'every Nth day [of month]' + * 'every Nth WEEKDAYNAME [of month]' + + Yearly on 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 "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 period boundaries will be on second Monday of +Monday"' each month +'-p "every 11/05"' yearly periods with boundaries on 5th of + November +'-p "every 5th same +November"' +'-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: Periods or dates ?, Next: Events on multiple weekdays, Prev: Intervals with custom start date, Up: Period expressions + +4.4.4 Periods or dates ? +------------------------ + +Report intervals like the above are most often used with '-p|--period', +to divide reports into multiple subperiods - each generated date marks a +subperiod boundary. Here, the periods between the dates are what's +important. + + But report intervals can also be used with '--forecast' to generate +future transactions, or with 'balance --budget' to generate budget +goal-setting transactions. For these, the dates themselves are what +matters. + + +File: hledger.info, Node: Events on multiple weekdays, Prev: Periods or dates ?, Up: Period expressions + +4.4.5 Events on multiple weekdays +--------------------------------- + +The 'every WEEKDAYNAME' form has a special variant with multiple day +names, comma-separated. Eg: 'every mon,thu,sat'. Also, 'weekday' and +'weekendday' are shorthand for 'mon,tue,wed,thu,fri' and 'sat,sun' +respectively. + + This form 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. (Because gaps between periods are not allowed; if you'd like to +change this, see #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 + +5 DEPTH +******* + +With the '--depth NUM' option (short form: '-NUM'), commands like +account, balance and register will show only the uppermost accounts in +the account tree, down to level NUM. 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: CONVERSION & COST, Prev: DEPTH, Up: Top + +6 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 account aliases:: +* Queries and valuation:: +* Querying with account aliases:: +* Querying with cost or value:: + + +File: hledger.info, Node: Query types, Next: Combining query terms, Up: QUERIES + +6.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 + +6.2 Combining 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. + + while the print command shows transactions which: + + * match any of the description terms AND + * have any postings matching any of the positive account terms AND + * have no postings matching any of the negative account terms AND + * match all the other terms. + + You can do more powerful queries (such as AND-ing two like terms) by +running a first query with 'print', and piping the result into a second +hledger command. Eg: how much of food expenses was paid with cash ? + +$ hledger print assets:cash | hledger -f- -I balance expenses:food + + If you are interested in full boolean expressions for queries, see +#203. + + +File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Combining query terms, Up: QUERIES + +6.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 account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: QUERIES + +6.4 Queries and account aliases +=============================== + +When account names are rewritten with '--alias' or 'alias', 'acct:' will +match either the old or the new account name. + + +File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and account aliases, Up: QUERIES + +6.5 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 + +6.6 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 + +6.7 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: CONVERSION & COST, Next: VALUATION, Prev: QUERIES, Up: Top + +7 CONVERSION & COST +******************* + +This section is about converting between commodities. Some definitions: + + * A "commodity conversion" is an exchange of one currency or + commodity for another. Eg a foreign currency exchange, or a + purchase or sale of stock or cryptocurrency. + + * A "conversion transaction" is a transaction involving one or more + such conversions. + + * "Conversion rate" is the exchange rate in a conversion - the cost + per unit of one commodity in the other. + + * "Cost" is how much of one commodity was paid to acquire the other + (when buying), or how much was received in exchange for the other + (when selling). We call both of these "cost" for convenience + (after all, it is cost for one party or the other). + +* Menu: + +* Recording conversions:: +* Inferring missing conversion rates:: +* Inferring missing equity postings:: +* Cost reporting:: +* Conversion summary:: + + +File: hledger.info, Node: Recording conversions, Next: Inferring missing conversion rates, Up: CONVERSION & COST + +7.1 Recording conversions +========================= + +As a concrete example, let's assume 100 EUR was converted to 120 USD. +There are several ways to record this in the journal, each with pros and +cons which will be explained in more detail below. (Also, these +examples use journal format which is properly explained much further +below; sorry about that, you may want to read some of that first.) + +* Menu: + +* Implicit conversion:: +* Priced conversion:: +* Equity conversion:: +* Priced equity conversion:: + + +File: hledger.info, Node: Implicit conversion, Next: Priced conversion, Up: Recording conversions + +7.1.1 Implicit conversion +------------------------- + +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: + + * Easy, concise + * hledger can do cost reporting + + Con: + + * Less error checking - typos in amounts or commodity symbols may not + be detected + * conversion rate is not clear + * disturbs the accounting equation + + 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: Priced conversion, Next: Equity conversion, Prev: Implicit conversion, Up: Recording conversions + +7.1.2 Priced conversion +----------------------- + +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 some error checking + * hledger can do cost reporting + + Con: + + * Disturbs the accounting equation + + +File: hledger.info, Node: Equity conversion, Next: Priced equity conversion, Prev: Priced conversion, Up: Recording conversions + +7.1.3 Equity conversion +----------------------- + +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 + * works in any double entry accounting system + + Con: + + * More verbose + * conversion rate is not clear + * hledger can not do cost reporting + + +File: hledger.info, Node: Priced equity conversion, Prev: Equity conversion, Up: Recording conversions + +7.1.4 Priced equity conversion +------------------------------ + +Another possible notation would be to record both the conversion rate +and the equity postings: + +2021-01-01 + assets:cash -100 EUR @ 1.20 USD + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + hledger currently does not allow this; instead, you can record the +conversion rate as a comment. + + +File: hledger.info, Node: Inferring missing conversion rates, Next: Inferring missing equity postings, Prev: Recording conversions, Up: CONVERSION & COST + +7.2 Inferring missing conversion rates +====================================== + +hledger will do this automatically for implicit conversions. Currently +it can not do this for equity conversions. + + +File: hledger.info, Node: Inferring missing equity postings, Next: Cost reporting, Prev: Inferring missing conversion rates, Up: CONVERSION & COST + +7.3 Inferring missing equity postings +===================================== + +With the '--infer-equity' flag, hledger will add equity postings to +priced and implicit conversions (and move the conversion rate into a +comment). + + +File: hledger.info, Node: Cost reporting, Next: Conversion summary, Prev: Inferring missing equity postings, Up: CONVERSION & COST + +7.4 Cost reporting +================== + +With the '-B/--cost' flag, hledger will convert the amounts in priced +and implicit conversions to their cost in the other commodity. This is +useful to see a report of what you paid for things (or how much you sold +things for). Currently '-B/--cost' does not work on equity conversions, +and it disables '--infer-equity'. + + These operations are transient, only affecting reports. If you want +to change the journal file permanently, you could pipe each entry +through 'hledger -f- -I print [-x] [--infer-equity] [-B]' + + +File: hledger.info, Node: Conversion summary, Prev: Cost reporting, Up: CONVERSION & COST + +7.5 Conversion summary +====================== + + * Recording the conversion rate is good because it makes that clear + and allows cost reporting. + * Recording equity postings is good because it balances the + accounting equation and is correct bookkeeping. + * Combining these is not yet supported, so you have to choose. For + now, priced conversions are a good compromise, so that: + * When you want to see the cost (or sale proceeds) of things, + use '-B/--cost'. + * When you want to see a balanced balance sheet or correct + journal entries, use '--infer-equity'. + * Combining these is not yet supported; '-B/--cost' will take + precedence. + + * Conversion/cost operations are performed before valuation. + + +File: hledger.info, Node: VALUATION, Next: PIVOTING, Prev: CONVERSION & COST, Up: Top + +8 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:: +* Market prices:: +* --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 + +8.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 + +8.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: Market prices, Prev: -X Value in specified commodity, Up: VALUATION + +8.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: Market prices, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: VALUATION + +8.4 Market prices +================= + +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 transaction prices. + + 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: Market prices, Up: VALUATION + +8.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 transaction prices as additional market +prices (as Ledger does) ? We could produce value reports without +needing P directives at all. + + 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. +(And 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.) + + * but not, currently, from "more correct" multicommodity transactions + (no '@', multiple commodities, balanced). + + There is another 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' + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: VALUATION + +8.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, transaction prices 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 + +8.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 + +8.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 + +8.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 + +8.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 + +8.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: PIVOTING, Next: OUTPUT, Prev: VALUATION, Up: Top + +9 PIVOTING +********** + +Normally hledger sums amounts, and organizes them in a hierarchy, based +on account name. The '--pivot FIELD' option causes it to sum and +organize hierarchy based on the value of some other field instead. +FIELD can be: 'status', 'code', 'description', 'payee', 'note', or the +full name (case insensitive) of any tag. As with account names, values +containing 'colon:separated:parts' will be displayed hierarchically in +reports. + + '--pivot' is a general option affecting all reports; you can think of +hledger transforming the journal before any other processing, replacing +every posting's account name with the value of the specified field on +that posting, inheriting it from the transaction or using a blank value +if it's not present. + + An example: + +2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query, +described below): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: OUTPUT, Next: COMMANDS, Prev: PIVOTING, Up: Top + +10 OUTPUT +********* + +* Menu: + +* Output destination:: +* Output styling:: +* Output format:: +* Commodity styles:: + + +File: hledger.info, Node: Output destination, Next: Output styling, Up: OUTPUT + +10.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) + + hledger can optionally produce debug output (if enabled with +'--debug=N'); this goes to stderr, and is not affected by +'-o/--output-file'. If you need to capture it, use shell redirects, eg: +'hledger bal --debug=3 >file 2>&1'. + + +File: hledger.info, Node: Output styling, Next: Output format, Prev: Output destination, Up: OUTPUT + +10.2 Output styling +=================== + +hledger commands can produce colour output when the terminal supports +it. This is controlled by the '--color/--colour' option: - 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. + + hledger commands can also use unicode box-drawing characters to +produce prettier tables and output. This is controlled by the +'--pretty' option: - 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: Output format, Next: Commodity styles, Prev: Output styling, Up: OUTPUT + +10.3 Output format +================== + +Some commands offer additional output formats, other than the usual +plain text terminal output. Here are those commands and the formats +currently supported: + +- txt csv html json sql +------------------------------------------------------------ +aregister 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 + +* Menu: + +* CSV output:: +* HTML output:: +* JSON output:: +* SQL output:: + + +File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format + +10.3.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 + +10.3.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 + +10.3.3 JSON output +------------------ + + * Not yet much used; real-world feedback is welcome. + + * Our JSON is rather large and verbose, as it is quite 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 + +10.3.4 SQL output +----------------- + + * 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, Prev: Output format, Up: OUTPUT + +10.4 Commodity styles +===================== + +The display style of a commodity/currency is inferred according to the +rules described in Commodity display style. The inferred display style +can be overridden by an optional '-c/--commodity-style' option +(Exceptions: as is the case for inferred styles, price amounts, and all +amounts displayed by the 'print' command, will be displayed with all of +their decimal digits visible, regardless of the specified precision). +For example, the following will override the display style for dollars. + +$ hledger print -c '$1.000,0' + + The format specification of the style is identical to the commodity +display style specification for the commodity directive. The command +line option can be supplied repeatedly to override the display style for +multiple commodity/currency symbols. + + +File: hledger.info, Node: COMMANDS, Next: JOURNAL FORMAT, Prev: OUTPUT, Up: Top + +11 COMMANDS +*********** + +hledger provides a number of commands for producing reports and managing +your data. 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'. + + Here are the built-in commands, with the most often-used in bold: + + *Data entry:* + + These data entry commands are the only ones which can modify your +journal file. + + * *add* - add transactions using guided prompts + * *import* - add any new transactions from other files (eg csv) + + *Data management:* + + * check - check for various kinds of issue in the data + * close (equity) - generate balance-resetting transactions + * diff - compare account transactions in two journal files + * rewrite - generate extra postings, similar to print -auto + + *Financial statements:* + + * *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 + * roi - show return on investments + + *Miscellaneous reports:* + + * accounts - show account names + * activity - show postings-per-interval bar charts + * *balance (bal)* - show balance changes/end balances/budgets in any + accounts + * codes - show transaction codes + * commodities - show commodity/currency symbols + * descriptions - show unique transaction descriptions + * files - show input file paths + * help - show hledger user manuals in several formats + * notes - show unique note segments of transaction descriptions + * payees - show unique payee segments of transaction descriptions + * prices - show market price records + * *print* - show transactions (journal entries) + * print-unique - show only transactions with unique descriptions + * *register (reg)* - show postings in one or more accounts & running + total + * register-match - show a recent posting that best matches a + description + * stats - show journal statistics + * tags - show tag names + * test - run self tests + + *Add-on commands:* + + Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on +commands; these appear in the commands list with a '+' mark. Two of +these are maintained and released with hledger: + + * *ui* - an efficient terminal interface (TUI) for hledger + * *web* - a simple web interface (WUI) for hledger + + And these add-ons are maintained separately: + + * iadd - a more interactive alternative for the add command + * interest - generates interest transactions according to various + schemes + * stockquotes - downloads market prices for your commodities from + AlphaVantage _(experimental)_ + + Next, the detailed command docs, in alphabetical order. + +* Menu: + +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* payees:: +* prices:: +* print:: +* print-unique:: +* register:: +* register-match:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: +* About add-on commands:: + + +File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS + +11.1 accounts +============= + +accounts +Show account names. + + This command lists account names, either declared with account +directives (-declared), posted to (-used), or both (the default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +'--tree', it uses indentation to show the account hierarchy. In flat +mode you can add '--drop N' to omit the first few account name +components. Account names can be depth-clipped with 'depth:N' or +'--depth N' or '-N'. + + With '--types', it also shows each account's type, if it's known. +(See Declaring accounts > Account types.) + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS + +11.2 activity +============= + +activity +Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). With query arguments, it counts only matched transactions. + + Examples: + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** + + +File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS + +11.3 add +======== + +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, + 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 the tutorial for a detailed explanation): + +$ hledger add +Adding transactions to journal file /src/hledger/examples/sample.journal +Any command line arguments will be used as defaults. +Use tab key to complete, readline keys to edit, enter to accept defaults. +An optional (CODE) may follow transaction dates. +An optional ; COMMENT may follow descriptions or amounts. +If you make a mistake, enter < at any prompt to 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: COMMANDS + +11.4 aregister +============== + +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. +(Eg if you have 'assets:aaa:checking' and 'assets:bbb:checking' +accounts, 'hledger areg checking' would select 'assets:aaa:checking'.) + + 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 + +11.4.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: COMMANDS + +11.5 balance +============ + +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:: +* Filtered balance report:: +* List or tree mode:: +* Depth limiting:: +* Dropping top-level accounts:: +* Multi-period balance report:: +* Showing declared accounts:: +* Data layout:: +* Sorting by amount:: +* Percentages:: +* Balance change end balance:: +* Balance report types:: +* Useful balance reports:: +* Budget report:: +* Customising single-period balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +11.5.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: Filtered balance report, Prev: balance features, Up: balance + +11.5.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. For real-world +accounts, this should also match 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: Filtered balance report, Next: List or tree mode, Prev: Simple balance report, Up: balance + +11.5.3 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 + +11.5.4 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 + +11.5.5 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: Multi-period balance report, Prev: Depth limiting, Up: balance + +11.5.6 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: Multi-period balance report, Next: Showing declared accounts, Prev: Dropping top-level accounts, Up: balance + +11.5.7 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: Showing declared accounts, Next: Data layout, Prev: Multi-period balance report, Up: balance + +11.5.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: Data layout, Next: Sorting by amount, Prev: Showing declared accounts, Up: balance + +11.5.9 Data layout +------------------ + +The '--layout' option affects how multi-commodity amounts are displayed, +and some other things, influencing the overall layout of the report +data: + + * '--layout=wide[,WIDTH]': commodities are shown on a single line, + possibly elided to the specified width + * '--layout=tall': each commodity is shown on a separate line + * '--layout=bare': amounts are shown as bare numbers, with commodity + symbols in a separate column + * '--layout=tidy': data is normalised to tidy form, with one row per + data value. We currently support this with CSV output only. In + tidy mode, totals and row averages are disabled ('-N/--no-total' is + implied and '-T/--row-total' and '-A/--average' will be ignored). + + These '--layout' modes are supported with some but not all of the +output formats: + +- 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 when 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 + is a column and each row represents a single data point (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). + This kind of data is the easiest to process with other software: + + $ 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: Sorting by amount, Next: Percentages, Prev: Data layout, Up: balance + +11.5.10 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: Balance change end balance, Prev: Sorting by amount, Up: balance + +11.5.11 Percentages +------------------- + +With '-%/--percent', balance reports show each account's value expressed +as a percentage of the (column) total: + +$ hledger -f examples/sample.journal bal expenses -Q -% +Balance changes in 2008: + + || 2008Q1 2008Q2 2008Q3 2008Q4 +===================++================================= + expenses:food || 0 50.0 % 0 0 + expenses:supplies || 0 50.0 % 0 0 +-------------------++--------------------------------- + || 0 100.0 % 0 0 + + 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: Balance change end balance, Next: Balance report types, Prev: Percentages, Up: balance + +11.5.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: Useful balance reports, Prev: Balance change end balance, Up: balance + +11.5.13 Balance report types +---------------------------- + +For more flexible reporting, there are three important option groups: + + 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] +...' + + The first two are the most important: calculation type selects the +basic calculation to perform for each table cell, while accumulation +type says which postings should be included in each cell's calculation. +Typically one or both of these are selected by default, so you don't +need to write them explicitly. A valuation type can be added if you +want to convert the basic report to value or cost. + + *Calculation type:* +The basic calculation to perform for each table cell. It is one of: + + * '--sum' : sum the posting amounts (*default*) + * '--budget' : like -sum but also show a goal amount + * '--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) + + *Accumulation type:* +Which postings should be included in each cell's calculation. It is one +of: + + * '--change' : postings from column start to column end, ie within + the cell's period. Typically used to see revenues/expenses. + (*default for balance, incomestatement*) + + * '--cumulative' : postings from report start to column end, eg to + show changes accumulated since the report's start date. Rarely + used. + + * '--historical/-H' : postings from journal start to column end, ie + all postings from account creation to the end of the cell's period. + Typically used to see historical end balances of + assets/liabilities/equity. (*default for balancesheet, + balancesheetequity, cashflow*) + + *Valuation type:* +Which kind of valuation, valuation date(s) and optionally a target +valuation commodity to use. It is one of: + + * no valuation, show amounts in their original commodities + (*default*) + * '--value=cost[,COMM]' : no valuation, show amounts converted to + cost + * '--value=then[,COMM]' : show value at transaction dates + * '--value=end[,COMM]' : show value at period end date(s) (*default + with '--valuechange', '--gain'*) + * '--value=now[,COMM]' : show value at today's date + * '--value=YYYY-MM-DD[,COMM]' : show value at another date + + or one of their aliases: '--cost/-B', '--market/-V' or +'--exchange/-X'. + + 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: YYYY-MM-DD +v /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: Useful balance reports, Next: Budget report, Prev: Balance report types, Up: balance + +11.5.14 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: Budget report, Next: Customising single-period balance reports, Prev: Useful balance reports, Up: balance + +11.5.15 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 very 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] + + For more examples and notes, see Budgeting. + +* Menu: + +* Budget report start date:: +* Budgets and subaccounts:: +* Selecting budget goals:: + + +File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report + +11.5.15.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 + +11.5.15.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, Prev: Budgets and subaccounts, Up: Budget report + +11.5.15.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 the +print command 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: Customising single-period balance reports, Prev: Budget report, Up: balance + +11.5.16 Customising single-period balance reports +------------------------------------------------- + +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 (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS + +11.6 balancesheet +================= + +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: COMMANDS + +11.7 balancesheetequity +======================= + +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: COMMANDS + +11.8 cashflow +============= + +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: COMMANDS + +11.9 check +========== + +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 + + Here are the checks currently available: + +* Menu: + +* Basic checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: + + +File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check + +11.9.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 transaction prices or automatically-inferred + transaction prices + + * *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 + +11.9.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 transaction prices but not inferred ones + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +11.9.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 + + * *uniqueleafnames* - all account leaf names are unique + + +File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check + +11.9.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: close, Next: codes, Prev: check, Up: COMMANDS + +11.10 close +=========== + +close, equity +Prints a sample "closing" transaction bringing specified account +balances to zero, and an inverse "opening" transaction restoring the +same account balances. + + If like most people you split your journal files by time, eg by year: +at the end of the year you can use this command to "close out" your +asset and liability (and perhaps equity) balances in the old file, and +reinitialise them in the new file. This helps ensure that report +balances remain correct whether you are including old files or not. +(Because all closing/opening transactions except the very first will +cancel out - see example below.) + + Some people also use this command to close out revenue and expense +balances at the end of an accounting period. This properly records the +period's profit/loss as "retained earnings" (part of equity), and allows +the accounting equation (A-L=E) to balance, which you could then check +by the bse report's zero total. + + You can print just the closing transaction by using the '--close' +flag, or just the opening transaction with the '--open' flag. + + Their descriptions are 'closing balances' and 'opening balances' by +default; you can customise these with the '--close-desc' and +'--open-desc' options. + + Just one balancing equity posting is used by default, with the amount +left implicit. The default account name is 'equity:opening/closing +balances'. You can customise the account name(s) with '--close-acct' +and '--open-acct'. (If you specify only one of these, it will be used +for both.) + + With '--x/--explicit', the equity posting's amount will be shown +explicitly, and if it involves multiple commodities, there will be a +separate equity posting for each commodity (as in the print command). + + With '--interleaved', each equity posting is shown next to the +posting it balances (good for troubleshooting). + +* Menu: + +* close and prices:: +* close date:: +* Example close asset/liability accounts for file transition:: +* Hiding opening/closing transactions:: +* close and balance assertions:: +* Example close revenue/expense accounts to retained earnings:: + + +File: hledger.info, Node: close and prices, Next: close date, Up: close + +11.10.1 close and prices +------------------------ + +Transaction prices are ignored (and discarded) by closing/opening +transactions, by default. With '--show-costs', they are preserved; +there will be a separate equity posting for each cost in each commodity. +This means 'balance -B' reports will look the same after the transition. +Note if you have many foreign currency or investment transactions, this +will generate very large journal entries. + + +File: hledger.info, Node: close date, Next: Example close asset/liability accounts for file transition, Prev: close and prices, Up: close + +11.10.2 close date +------------------ + +The default closing date is yesterday, or the journal's end date, +whichever is later. + + Unless you are running 'close' on exactly the first day of the new +period, you'll want to override the closing date. This is done by +specifying a report end date, where "last day of the report period" will +be the closing date. The opening date is always the following day. So +to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any +of these will work: + +end date explanation +argument +------------------------------------------------------------------- +'-e 2021-01-01' end dates are exclusive +'-e 2021' equivalent, per smart dates +'-p 2020' equivalent, the period's begin date is ignored +'date:2020' equivalent query + + +File: hledger.info, Node: Example close asset/liability accounts for file transition, Next: Hiding opening/closing transactions, Prev: close date, Up: close + +11.10.3 Example: close asset/liability accounts for file transition +------------------------------------------------------------------- + +Carrying asset/liability balances from 2020.journal into a new file for +2021: + +$ hledger close -f 2020.journal -p 2020 assets liabilities +# copy/paste the closing transaction to the end of 2020.journal +# copy/paste the opening transaction to the start of 2021.journal + + Or: + +$ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction +$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction + + Now, + +$ hledger bs -f 2021.journal # just new file - balances correct +$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct +$ hledger bs -f 2020.journal # just old files - balances are zero ? + # (exclude final closing txn, see below) + + +File: hledger.info, Node: Hiding opening/closing transactions, Next: close and balance assertions, Prev: Example close asset/liability accounts for file transition, Up: close + +11.10.4 Hiding opening/closing transactions +------------------------------------------- + +Although the closing/opening transactions cancel out, they will be +visible in reports like 'print' and 'register', creating some visual +clutter. You can exclude them all with a query, like: + +$ hledger print not:desc:'opening|closing' # less typing +$ hledger print not:'equity:opening/closing balances' # more precise + + But when reporting on multiple files, this can get a bit tricky; you +may need to keep the earliest opening balances, for a historical +register report; or you may need to suppress a closing transaction, to +see year-end balances. If you find yourself needing more precise +queries, here's one solution: add more easily-matched tags to +opening/closing transactions, like this: + +; 2019.journal +2019-01-01 opening balances ; earliest opening txn, no tag here +... +2019-12-31 closing balances ; clopen:2020 +... + +; 2020.journal +2020-01-01 opening balances ; clopen:2020 +... +2020-12-31 closing balances ; clopen:2021 +... + +; 2021.journal +2021-01-01 opening balances ; clopen:2021 +... + + Now with + +; all.journal +include 2019.journal +include 2020.journal +include 2021.journal + + you could do eg: + +$ hledger -f all.journal reg -H checking not:tag:clopen + # all years checking register, hiding non-essential opening/closing txns + +$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 + # 2020 year end balances, suppressing 2020 closing txn + + +File: hledger.info, Node: close and balance assertions, Next: Example close revenue/expense accounts to retained earnings, Prev: Hiding opening/closing transactions, Up: close + +11.10.5 close and balance assertions +------------------------------------ + +The closing and opening transactions will include balance assertions, +verifying that the accounts have first been reset to zero and then +restored to their previous balance. These provide valuable error +checking, alerting you when things get out of line, but you can ignore +them temporarily with '-I' or just remove them if you prefer. + + You probably shouldn't use status or realness filters (like -C or -R +or 'status:') with 'close', or the generated balance assertions will +depend on these flags. Likewise, if you run this command with '--auto', +the balance assertions would probably always require '--auto'. + + Multi-day transactions (where some postings have a different date) +break the balance assertions, because the money is temporarily +"invisible" while in transit: + +2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + assets:bank:checking -5 ; date: 2021/1/2 + + To fix the assertions, you can add a temporary account to track such +in-transit money (splitting the multi-day transaction into two +single-day transactions): + +; in 2020.journal: +2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + liabilities:pending + +; in 2021.journal: +2021/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:bank:checking + + +File: hledger.info, Node: Example close revenue/expense accounts to retained earnings, Prev: close and balance assertions, Up: close + +11.10.6 Example: close revenue/expense accounts to retained earnings +-------------------------------------------------------------------- + +For this, use '--close' to suppress the opening transaction, as it's not +needed. Also you'll want to change the equity account name to your +equivalent of "equity:retained earnings". + + Closing 2021's first quarter revenues/expenses: + +$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ + --close-acct='equity:retained earnings' >> 2021.journal + + The same, using the default journal and current year: + +$ hledger close --close revenues expenses -p Q1 \ + --close-acct='equity:retained earnings' >> $LEDGER_FILE + + Now, the first quarter's balance sheet should show a zero (unless you +are using @/@@ notation without equity postings): + +$ hledger bse -p Q1 + + And we must suppress the closing transaction to see the first +quarter's income statement (using the description; 'not:'retained +earnings'' won't work here): + +$ hledger is -p Q1 not:desc:'closing balances' + + +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS + +11.11 codes +=========== + +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: + +1/1 (123) + (a) 1 + +1/1 () + (a) 1 + +1/1 + (a) 1 + +1/1 (126) + (a) 1 + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + + +126 + + +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS + +11.12 commodities +================= + +commodities +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS + +11.13 descriptions +================== + +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: COMMANDS + +11.14 diff +========== + +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: COMMANDS + +11.15 files +=========== + +files +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + + +File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS + +11.16 help +========== + +help +Show the hledger user manual in one of several formats, optionally +positioned at a given TOPIC (if possible). + + TOPIC is any heading in the manual, or the start of any heading (but +not the middle). It is case insensitive. + + Some examples: 'commands', 'print', 'forecast', '"auto postings"', +'"commodity column"'. + + This command shows the user manual built in to this hledger version. +It can be useful if the correct version of the hledger manual, or the +usual viewing tools, are not installed on your system. + + By default it uses the best viewer it can find in $PATH, in this +order: 'info', 'man', $PAGER (unless a topic is specified), 'less', or +stdout. When run non-interactively, it always uses stdout. Or you can +select a particular viewer with the '-i' (info), '-m' (man), or '-p' +(pager) flags. + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS + +11.17 import +============ + +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 + +11.17.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 + +11.17.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' + + +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import + +11.17.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 + +11.17.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: COMMANDS + +11.18 incomestatement +===================== + +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: COMMANDS + +11.19 notes +=========== + +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: COMMANDS + +11.20 payees +============ + +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: COMMANDS + +11.21 prices +============ + +prices +Print market price directives from the journal. With +-infer-market-prices, generate additional market prices from transaction +prices. With -infer-reverse-prices, also generate market prices by +inverting transaction prices. Prices (and postings providing +transaction prices) can be filtered by a query. Price amounts are +displayed with their full precision. + + +File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS + +11.22 print +=========== + +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 transaction price is +implied but not written, it will not appear in the output. You can use +the '-x'/'--explicit' flag to make all amounts and transaction prices +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 transaction prices are converted to +cost using that price. This can be used for troubleshooting. + + With '-m'/'--match' and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there +is no similar-enough match, no transaction will be shown. + + With '--new', 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: print-unique, Next: register, Prev: print, Up: COMMANDS + +11.23 print-unique +================== + +print-unique +Print transactions which do not reuse an already-seen description. + + Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 + + +File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS + +11.24 register +============== + +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. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +11.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: register-match, Next: rewrite, Prev: register, Up: COMMANDS + +11.25 register-match +==================== + +register-match +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. If there are multiple equally +good matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS + +11.26 rewrite +============= + +rewrite +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +$ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +11.26.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 + +11.26.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 + +11.26.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: COMMANDS + +11.27 roi +========= + +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 + +11.27.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 + +11.27.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 + +11.27.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: COMMANDS + +11.28 stats +=========== + +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 also supports output destination and output format +selection. + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS + +11.29 tags +========== + +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, Next: About add-on commands, Prev: tags, Up: COMMANDS + +11.30 test +========== + +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: About add-on commands, Prev: test, Up: COMMANDS + +11.31 About add-on commands +=========================== + +Add-on commands are 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. + + Add-ons are a relatively easy way to add local features or experiment +with new ideas. They can be written in any language, but haskell +scripts have a big advantage: they can use the same hledger library +functions that built-in commands use for command-line options, parsing +and reporting. Some experimental/example add-on scripts can be found in +the hledger repo's bin/ directory. + + 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: JOURNAL FORMAT, Next: CSV FORMAT, Prev: COMMANDS, Up: Top + +12 JOURNAL FORMAT +***************** + +hledger's default file format, representing a General Journal. + + 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). These are mostly in the order you'll use them, but in some +cases related concepts have been grouped together for easy reference, or +linked before they are introduced, so feel free to skip over anything +that looks unnecessary right now. + +* Menu: + +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Comments:: +* Tags:: +* Postings:: +* Account names:: +* Amounts:: +* Transaction prices:: +* Lot prices lot dates:: +* Balance assertions:: +* Balance assignments:: +* Directives:: +* Directives and multiple files:: +* Comment blocks:: +* Including other files:: +* Default year:: +* Declaring payees:: +* Declaring the decimal mark:: +* Declaring commodities:: +* Default commodity:: +* Declaring market prices:: +* Declaring accounts:: +* Rewriting accounts:: +* Default parent account:: +* Periodic transactions:: +* Auto postings:: + + +File: hledger.info, Node: Transactions, Next: Dates, Up: JOURNAL FORMAT + +12.1 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 FORMAT + +12.2 Dates +========== + +* Menu: + +* Simple dates:: +* Secondary dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Secondary dates, Up: Dates + +12.2.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 default year 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: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates + +12.2.2 Secondary dates +---------------------- + +Real-life transactions sometimes involve more than one date - eg the +date you write a cheque, and the date it clears in your bank. When you +want to model this, for more accurate daily balances, you can specify +individual posting dates. + + Or, you can use the older _secondary date_ feature (Ledger calls it +auxiliary date or effective date). Note: we support this for +compatibility, but I usually recommend avoiding this feature; posting +dates are almost always clearer and simpler. + + 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", as shown here: + +2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + +$ hledger register checking +2010-02-23 movie ticket assets:checking $-10 $-10 + +$ hledger register checking --date2 +2010-02-19 movie ticket assets:checking $-10 $-10 + + +File: hledger.info, Node: Posting dates, Prev: Secondary dates, Up: Dates + +12.2.3 Posting dates +-------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like 'date:DATE'. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction's date. You can set the secondary date +similarly, with 'date2:DATE2'. The 'date:' or 'date2:' tags must have a +valid simple date value if they are present, eg a 'date:' tag with no +value is not allowed. + + Ledger's earlier, more compact bracketed date syntax is also +supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'. hledger will attempt +to parse any square-bracketed sequence of the '0123456789/-.=' +characters in this way. With this syntax, DATE infers its year from the +transaction and DATE2 infers its year from DATE. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: JOURNAL FORMAT + +12.3 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 FORMAT + +12.4 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: Comments, Prev: Code, Up: JOURNAL FORMAT + +12.5 Description +================ + +A transaction's description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +12.5.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: Comments, Next: Tags, Prev: Description, Up: JOURNAL FORMAT + +12.6 Comments +============= + +Lines in the journal beginning with a semicolon (';') or hash ('#') or +star ('*') are comments, and will be ignored. (Star comments cause +org-mode nodes to be ignored, allowing emacs users to fold and navigate +their journals with org-mode or orgstruct-mode.) + + You can attach comments to a transaction by writing them after the +description and/or indented on the following lines (before the +postings). Similarly, you can attach comments to an individual posting +by writing them after the amount and/or indented on the following lines. +Transaction and posting comments must begin with a semicolon (';'). + + Some examples: + +# a file comment +; another file comment +* also a file comment, useful in org/orgstruct mode + +comment +A multiline file comment, which continues +until a line containing just "end comment" +(or end of file). +end comment + +2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 +; a file comment (because not indented) + + You can also comment larger regions of a file using 'comment' and +'end comment' directives. + + +File: hledger.info, Node: Tags, Next: Postings, Prev: Comments, Up: JOURNAL FORMAT + +12.7 Tags +========= + +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: + +2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the +next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or +newlines. Ending at commas means you can write multiple short tags on +one line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + * "'a comment containing'" is just comment text, not a tag + * "'tag1'" is a tag with no value + * "'tag2'" is another tag, whose value is "'some value ...'" + + Tags in a transaction comment affect the transaction and all of its +postings, while tags in a posting comment affect only that posting. For +example, the following transaction has three tags ('A', 'TAG2', +'third-tag') and the posting has four (those plus 'posting-tag'): + +1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values +are simple strings. + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Tags, Up: JOURNAL FORMAT + +12.8 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. + +* Menu: + +* Virtual postings:: + + +File: hledger.info, Node: Virtual postings, Up: Postings + +12.8.1 Virtual postings +----------------------- + +A posting with a parenthesised 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 accounting, 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: + +1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with a bracketed 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: + +1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance + + Ordinary non-parenthesised, non-bracketed postings are called _real +postings_. You can exclude virtual postings from reports with the +'-R/--real' flag or 'real:1' query. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: JOURNAL FORMAT + +12.9 Account names +================== + +Account names typically have several parts separated by a full colon, +from which hledger derives a hierarchical chart of accounts. They can +be anything you like, but in finance there are traditionally five +top-level accounts: 'assets', 'liabilities', 'revenue', 'expenses', and +'equity'. + + Account names may contain single spaces, eg: 'assets:accounts +receivable'. Because of this, they must always be followed by *two or +more spaces* (or newline). + + Account names can be aliased. + + +File: hledger.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: JOURNAL FORMAT + +12.10 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 + +12.10.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 detail below. + + +File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts + +12.10.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 + +12.10.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, in JOURNAL FORMAT -> Declaring commodities. 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 + +12.10.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. + + Transaction price 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 transaction price). 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 + +12.10.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"). (Guaranteed since hledger 1.17.1; in older versions +this could vary if hledger was built with Decimal < 0.5.1.) + + +File: hledger.info, Node: Transaction prices, Next: Lot prices lot dates, Prev: Amounts, Up: JOURNAL FORMAT + +12.11 Transaction prices +======================== + +Within a transaction, you can note an amount's price in another +commodity. This can be used to document the cost (in a purchase) or +selling price (in a sale). For example, transaction prices are useful +to record purchases of a foreign currency. Note transaction prices are +fixed at the time of the transaction, and do not change over time. See +also market prices, which represent prevailing exchange rates on a +certain date. + + There are several ways to record a transaction price: + + 1. Write the price per unit, as '@ UNITPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as '@@ TOTALPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + 4. Like 1, but the '@' is parenthesised, i.e. '(@)'; this is for + compatibility with Ledger journals (Virtual posting costs), and is + equivalent to 1 in hledger. + + 5. Like 2, but as in 4 the '@@' is parenthesised, i.e. '(@@)'; in + hledger, this is equivalent to 2. + + Use the '-B/--cost' flag to convert amounts to their transaction +price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in +Ledger). Eg here is how -B affects the balance report for the example +above: + +$ hledger bal -N --flat + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction +price is inferred: the inferred price will be in the commodity of the +last amount. So if example 3's postings are reversed, while the +transaction is equivalent, -B shows something different: + +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N --flat -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros + + +File: hledger.info, Node: Lot prices lot dates, Next: Balance assertions, Prev: Transaction prices, Up: JOURNAL FORMAT + +12.12 Lot prices, lot dates +=========================== + +Ledger allows another kind of price, lot price (four variants: +'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}', +'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified. +These are normally used to select a lot when selling investments. +hledger will parse these, for compatibility with Ledger journals, but +currently ignores them. A transaction price, lot price and/or lot date +may appear in any order, after the posting amount and before the balance +assertion if any. + + +File: hledger.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices lot dates, Up: JOURNAL FORMAT + +12.13 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, 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 + +12.13.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 + +12.13.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 + +12.13.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 + +12.13.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 + +12.13.5 Assertions and prices +----------------------------- + +Balance assertions ignore transaction prices, and should normally be +written without one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below). + + +File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions + +12.13.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 + +12.13.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 + +12.13.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 + +12.13.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: Balance assignments, Next: Directives, Prev: Balance assertions, Up: JOURNAL FORMAT + +12.14 Balance assignments +========================= + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). Note that using balance assignments makes your journal a +little less explicit; to know the exact amount posted, you have to run +hledger or do the calculations yourself, instead of just reading it. + +* Menu: + +* Balance assignments and prices:: + + +File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments + +12.14.1 Balance assignments and prices +-------------------------------------- + +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019-01-01 + (a) $1 @ €2 = $1 @ €2 + + +File: hledger.info, Node: Directives, Next: Directives and multiple files, Prev: Balance assignments, Up: JOURNAL FORMAT + +12.15 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 add some as your needs grow. Here is an overview of +directives by purpose: + +purpose directives command line + options with + similar effect +--------------------------------------------------------------------------- +*READING/GENERATING DATA:* +Declare a commodity's or 'commodity', 'D', +file's decimal mark to help 'decimal-mark' +parse amounts accurately +Apply changes to the data 'alias', 'apply '--alias' +while parsing account', 'comment', + 'D', 'Y' +Inline extra data files 'include' multiple + '-f/--file''s +Generate extra transactions or '~' +budget goals +Generate extra postings '=' +*CHECKING FOR ERRORS:* +Define valid entities to allow 'account', +stricter error checking 'commodity', 'payee' +*DISPLAYING REPORTS:* +Declare accounts' display 'account' +order and accounting type +Declare commodity display 'commodity', 'D' '-c/--commodity-style' +styles + + And here are all the directives and their precise effects: + +directiveeffects ends + at + file + end? +--------------------------------------------------------------------------- +*'account'*Declares an account, for checking all entries in all files; + and its display order and type, for reports. Subdirectives: + any text, ignored. +*'alias'*Rewrites account names, in following entries until end of Y + current file or 'end aliases'. +*'applyPrepends a common parent account to all account names, in Y +account'*following entries until end of current file or 'end apply + account'. +*'comment'*Ignores part of the journal file, until end of current fileY + or 'end comment'. +*'commodity'*Declares a commodity, for checking all entries in all files;N, + the decimal mark for parsing amounts of this commodity, for Y + following entries until end of current file; and its display + style, for reports. Takes precedence over 'D'. + Subdirectives: 'format' (alternate syntax). +*'D'* Sets a default commodity to use for no-symbol amounts, and Y + its decimal mark for parsing amounts of this commodity in + following entries until end of current file; and its display + style, for reports. +*'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 they + were written inline. +*'payee'*Declares a payee name, for checking all entries in all files. +*'P'* Declares a market price for a commodity on some date, for + valuation reports. +*'Y'* Declares a year for yearless dates, for following entries Y + until end of current file. +*'~'* Declares a periodic transaction rule that generates future +(tilde)transactions with '--forecast' and budget goals with 'balance + --budget'. +*'='* Declares an auto posting rule that generates extra postings partly +(equals)on matched transactions with '--auto', in current, parent, + and child files (but not sibling files, see #1212). + + +File: hledger.info, Node: Directives and multiple files, Next: Comment blocks, Prev: Directives, Up: JOURNAL FORMAT + +12.16 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: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: JOURNAL FORMAT + +12.17 Comment blocks +==================== + +A line containing just 'comment' starts a commented region of the file, +and a line containing just 'end comment' (or the end of the current +file) ends it. See also comments. + + +File: hledger.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: JOURNAL FORMAT + +12.18 Including other files +=========================== + +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: Default year, Next: Declaring payees, Prev: Including other files, Up: JOURNAL FORMAT + +12.19 Default year +================== + +You can set a default year to be used for subsequent dates which don't +specify a year. This is a line beginning with 'Y' followed by the year. +Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +Y2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + +File: hledger.info, Node: Declaring payees, Next: Declaring the decimal mark, Prev: Default year, Up: JOURNAL FORMAT + +12.20 Declaring payees +====================== + +The 'payee' 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 + + +File: hledger.info, Node: Declaring the decimal mark, Next: Declaring commodities, Prev: Declaring payees, Up: JOURNAL FORMAT + +12.21 Declaring the decimal mark +================================ + +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: Declaring commodities, Next: Default commodity, Prev: Declaring the decimal mark, Up: JOURNAL FORMAT + +12.22 Declaring commodities +=========================== + +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 + + 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: Declaring commodities + +12.22.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: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: JOURNAL FORMAT + +12.23 Default commodity +======================= + +The 'D' 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). + + The syntax is 'D AMOUNT'. As with 'commodity', 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 + + If both 'commodity' and 'D' directives are found for a commodity, +'commodity' takes precedence for setting decimal mark and display style. + + If you are using 'D' and also checking commodities, you will need to +add a 'commodity' directive similar to the 'D'. (The 'hledger check +commodities' command expects 'commodity' directives, and ignores 'D'). + + +File: hledger.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: JOURNAL FORMAT + +12.24 Declaring market prices +============================= + +The 'P' directive declares a market price, which is an exchange rate +between two commodities on a certain date. (In Ledger, they are called +"historical prices".) These are often obtained from a stock exchange, +cryptocurrency exchange, or the 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: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: JOURNAL FORMAT + +12.25 Declaring accounts +======================== + +'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. + * They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + * They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and + incomestatement. + * They can store other account information, as comments or as tags + which can be used to filter reports. + * They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + * In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + + The simplest form is just the word 'account' followed by a +hledger-style account name, eg this account directive declares the +'assets:bank:checking' account: + +account assets:bank:checking + +* Menu: + +* Account error checking:: +* Account comments:: +* Account subdirectives:: +* Account types:: +* Account display order:: + + +File: hledger.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts + +12.25.1 Account error checking +------------------------------ + +By default, accounts come into existence when a transaction references +them by name. 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 +the 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 in other formats). + * 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 comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts + +12.25.2 Account comments +------------------------ + +Comments, beginning with a semicolon, can be added: + + * on the same line, *after two or more spaces* (because ; is allowed + in account names) + * on the next lines, indented + + An example of both: + +account assets:bank:checking ; same-line comment, note 2+ spaces required before ; + ; next-line comment + ; some tags, type:A, acctnum:12345 + + Compatibility note: same-line comments are not supported by Ledger or +hledger <1.13. + + +File: hledger.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts + +12.25.3 Account subdirectives +----------------------------- + +We also allow (and ignore) Ledger-style indented subdirectives, just for +compatibility.: + +account assets:bank:checking + format blah blah ; <- subdirective, ignored + + Here is the full syntax of account directives: + +account ACCTNAME [;type:ACCTTYPE] [COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] + + +File: hledger.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts + +12.25.4 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 + CONVERSION & COST).) + + 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. Note the Cash + regexp changed in hledger 1.24.99.2. + + 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 each of them, 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: Account display order, Prev: Account types, Up: Declaring accounts + +12.25.5 Account display order +----------------------------- + +Account directives also set the order in which accounts are displayed, +eg in reports, the hledger-ui accounts screen, and the hledger-web +sidebar. By default accounts are listed in alphabetical order. But if +you have these account directives in the journal: + +account assets +account liabilities +account equity +account revenues +account expenses + + you'll see those accounts displayed in declaration order, not +alphabetically: + +$ hledger accounts -1 +assets +liabilities +equity +revenues +expenses + + Undeclared accounts, if any, are displayed last, in alphabetical +order. + + Note that sorting is done at each level of the account tree (within +each group of sibling accounts under the same parent). And currently, +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: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: JOURNAL FORMAT + +12.26 Rewriting accounts +======================== + +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:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts + +12.26.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: Rewriting accounts + +12.26.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: Rewriting accounts + +12.26.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, Prev: Combining aliases, Up: Rewriting accounts + +12.26.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, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: Rewriting accounts + +12.26.5 'end aliases' +--------------------- + +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, Up: Rewriting accounts + +12.26.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: Rewriting accounts + +12.26.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: Default parent account, Next: Periodic transactions, Prev: Rewriting accounts, Up: JOURNAL FORMAT + +12.27 Default parent account +============================ + +You can specify a parent account which will be prepended to all accounts +within a section of the journal. Use the 'apply account' and 'end apply +account' directives like so: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + which is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + If 'end apply account' is omitted, the effect lasts to the end of the +file. Included files are also affected, eg: + +apply account business +include biz.journal +end apply account +apply account personal +include personal.journal + + Prior to hledger 1.0, legacy 'account' and 'end' spellings were also +supported. + + A default parent account also affects account directives. It does +not affect account names being entered via hledger add or hledger-web. +If account aliases are present, they are applied after the default +parent account. + + +File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: Default parent account, Up: JOURNAL FORMAT + +12.28 Periodic transactions +=========================== + +Periodic transaction rules describe transactions that recur. They allow +hledger to generate temporary future transactions to help with +forecasting, so you don't have to write out each one in the journal, and +it's easy to try out different forecasts. + + 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. + + Periodic transaction rules also have a second meaning: they are used +to define budget goals, shown in budget reports. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: +* Forecasting with periodic transactions:: +* Budgeting with periodic transactions:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +12.28.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.): + +~ monthly + expenses:rent $2000 + assets:bank:checking + + There is an additional constraint on the period expression: the start +date must fall on a natural boundary of the interval. Eg 'monthly from +2018/1/1' is valid, but 'monthly from 2018/1/15' is not. + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +12.28.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!, Next: Forecasting with periodic transactions, Prev: Periodic rules and relative dates, Up: Periodic transactions + +12.28.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: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions + +12.28.4 Forecasting with periodic transactions +---------------------------------------------- + +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 with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions + +12.28.5 Budgeting with periodic transactions +-------------------------------------------- + +With the '--budget' flag, currently supported by the balance command, +each periodic transaction rule declares recurring budget goals for the +specified accounts. Eg the first example above declares a goal of +spending $2000 on rent (and also, a goal of depositing $2000 into +checking) every month. Goals and actual performance can then be +compared in budget reports. + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Auto postings, Prev: Periodic transactions, Up: JOURNAL FORMAT + +12.29 Auto postings +=================== + +"Automated postings" or "auto postings" are extra postings which get +added automatically to transactions which match certain queries, defined +by "auto posting rules", when you use the '--auto' flag. + + 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 + +12.29.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 + +12.29.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 + +12.29.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 + +12.29.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: CSV FORMAT, Next: TIMECLOCK FORMAT, Prev: JOURNAL FORMAT, Up: Top + +13 CSV FORMAT +************* + +How hledger reads CSV data, and the CSV rules file format. + + hledger can read CSV files (Character Separated Value - usually +comma, semicolon, or tab) containing dated records as if they were +journal files, automatically converting each CSV record into a +transaction. + + (To learn about _writing_ CSV, see CSV output.) + + We describe each CSV file's format with a corresponding _rules file_. +By default this is named like the CSV file with a '.rules' extension +added. Eg when reading 'FILE.csv', hledger also looks for +'FILE.csv.rules' in the same directory as 'FILE.csv'. You can specify a +different rules file with the '--rules-file' option. If a rules file is +not found, hledger will create a sample rules file, which you'll need to +adjust. + + This file contains rules describing the CSV data (header line, fields +layout, date format etc.), and how to construct hledger journal entries +(transactions) from it. Often there will also be a list of conditional +rules for categorising transactions based on their descriptions. Here's +an overview of the CSV rules; these are described more fully below, +after the examples: + +*'skip'* skip one or more header lines or matched + CSV records +*'fields' list* name CSV fields, assign them to hledger + fields +*field assignment* assign a value to one hledger field, with + interpolation +*Field names* hledger field names, used in the fields + list and field assignments +*'separator'* a custom field separator +*'if' block* apply some rules to CSV records matched by + patterns +*'if' table* apply some rules to CSV records matched by + patterns, alternate syntax +*'end'* skip the remaining CSV records +*'date-format'* how to parse dates in CSV records +*'decimal-mark'* the decimal mark used in CSV amounts, if + ambiguous +*'newest-first'* disambiguate record order when there's only + one date +*'include'* inline another CSV rules file +*'balance-type'* choose which type of balance assignments to + use + + Note, for best error messages when reading CSV files, use a '.csv', +'.tsv' or '.ssv' file extension or file prefix - see File Extension +below. + + There's an introductory Convert CSV files tutorial on hledger.org. + +* Menu: + +* Examples:: +* CSV rules:: +* Tips:: + + +File: hledger.info, Node: Examples, Next: CSV rules, Up: CSV FORMAT + +13.1 Examples +============= + +Here are some sample hledger CSV rules files. See also the full +collection at: +https://github.com/simonmichael/hledger/tree/master/examples/csv + +* Menu: + +* Basic:: +* Bank of Ireland:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Basic, Next: Bank of Ireland, Up: Examples + +13.1.1 Basic +------------ + +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 + + Default account names are chosen, since we didn't set them. + + +File: hledger.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: Examples + +13.1.2 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: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: Examples + +13.1.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: Examples + +13.1.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: CSV rules, Next: Tips, Prev: Examples, Up: CSV FORMAT + +13.2 CSV rules +============== + +The following kinds of rule can appear in the rules file, in any order. +Blank lines and lines beginning with '#' or ';' are ignored. + +* Menu: + +* skip:: +* fields list:: +* field assignment:: +* Field names:: +* separator:: +* if block:: +* if table:: +* end:: +* date-format:: +* decimal-mark:: +* newest-first:: +* include:: +* balance-type:: + + +File: hledger.info, Node: skip, Next: fields list, Up: CSV rules + +13.2.1 'skip' +------------- + +skip N + + The word "skip" followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines preceding the CSV data. +(Empty/blank lines are skipped automatically.) You'll need this +whenever your CSV data contains header lines. + + It also has a second purpose: it can be used inside if blocks to +ignore certain CSV records (described below). + + +File: hledger.info, Node: fields list, Next: field assignment, Prev: skip, Up: CSV rules + +13.2.2 'fields' list +-------------------- + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word "fields" followed by comma-separated field +names) is the quick way to assign CSV field values to hledger fields. +(The other way is field assignments, see below.) A fields list does +does two things: + + 1. It names the CSV fields. This is optional, but can be convenient + later for interpolating them. + + 2. Whenever you use a standard hledger field name (defined below), the + CSV value is assigned to that part of the hledger 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 + + Tips: + + * The fields list always use commas, even if your CSV data uses + another separator character. + * Currently 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). + * If the CSV contains column headings, it's a good idea to use these, + suitably modified, as the basis for your field names (eg + lower-cased, with underscores instead of spaces). + * If some heading names match standard hledger fields, but you don't + want to set the hledger fields directly, alter those names, eg by + appending an underscore. + * Fields you don't care about can be given a dummy name (eg: '_' ), + or no name. + + +File: hledger.info, Node: field assignment, Next: Field names, Prev: fields list, Up: CSV rules + +13.2.3 field assignment +----------------------- + +HLEDGERFIELDNAME 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 +('%CSVFIELDNAME'). + + 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: separator, Prev: field assignment, Up: CSV rules + +13.2.4 Field names +------------------ + +Here are the standard hledger field (and pseudo-field) names, which you +can use in a fields list and in field assignments. For more about the +transaction parts they refer to, see Transactions. + +* 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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.6 comment field +...................... + +'comment' sets the transaction's comment, if any. + + 'commentN', where N is a number, sets the Nth posting's comment. + + Tips: + + * 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 + +13.2.4.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, and in conditional blocks. + + 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 + +13.2.4.8 amount field +..................... + +'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. + + 'amountN-in' and 'amountN-out' can be used instead, if the CSV uses +separate fields for debits and credits (inflows and outflows). hledger +assumes both of these CSV fields are unsigned, and will automatically +negate the "-out" value. If they are signed, see "Setting amounts" +below. + + 'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep +pre-hledger-1.17 CSV rules files working (and for occasional +convenience). They are suitable only for two-posting transactions; they +set both posting 1's and posting 2's amount. Posting 2's amount will be +negated, and also converted to cost if there's a transaction price. + + If you have an existing rules file using the unnumbered form, you +might want to use the numbered form in certain conditional blocks, +without having to update and retest all the old rules. To facilitate +this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of +'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores +them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned, +avoiding conflicts. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +13.2.4.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 + +13.2.4.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: separator, Next: if block, Prev: Field names, Up: CSV rules + +13.2.5 '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: if block, Next: if table, Prev: separator, Up: CSV rules + +13.2.6 'if' block +----------------- + +if MATCHER + RULE + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + Conditional blocks ("if blocks") are a block of rules that are +applied only to CSV records which match certain patterns. They are +often used for customising account names based on transaction +descriptions. + +* Menu: + +* Matching the whole record:: +* Matching individual fields:: +* Combining matchers:: +* Rules applied on successful match:: + + +File: hledger.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block + +13.2.6.1 Matching the whole record +.................................. + +Each MATCHER can be a record matcher, which looks like this: + +REGEX + + REGEX is a case-insensitive regular expression that tries to match +anywhere within the CSV record. It is a POSIX ERE (extended regular +expression) that also supports GNU word boundaries ('\b', '\B', '\<', +'\>'), and nothing else. If you have trouble, be sure to check our doc: +https://hledger.org/hledger.html#regular-expressions + + Important note: the record that is matched is not the original +record, but a synthetic one, with any enclosing double quotes (but not +enclosing whitespace) removed, and always comma-separated (which means +that a field containing a comma will appear like two fields). Eg, if +the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will +actually see '2020-01-01,Acme, Inc., 1,000'). + + +File: hledger.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block + +13.2.6.2 Matching individual fields +................................... + +Or, MATCHER can be a field matcher, like this: + +%CSVFIELD REGEX + + which matches just the content of a particular CSV field. CSVFIELD +is a percent sign followed by the field's name or column number, like +'%date' or '%1'. + + +File: hledger.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block + +13.2.6.3 Combining matchers +........................... + +A single matcher can be written on the same line as the "if"; or +multiple matchers can be written on the following lines, non-indented. +Multiple matchers are OR'd (any one of them can match), unless one +begins with an '&' symbol, in which case it is AND'ed with the previous +matcher. + +if +MATCHER +& MATCHER + RULE + + +File: hledger.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block + +13.2.6.4 Rules applied on successful match +.......................................... + +After the patterns there should be one or more rules to apply, all +indented by at least one space. Three kinds of rule are allowed in +conditional blocks: + + * field assignments (to set a hledger field) + * skip (to skip the matched CSV record) + * end (to skip all remaining CSV records). + + Examples: + +# if the CSV record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the CSV record contains any of these patterns, set account2 and comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + +File: hledger.info, Node: if table, Next: end, Prev: if block, Up: CSV rules + +13.2.7 'if' table +----------------- + +if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn +MATCHER1,VALUE11,VALUE12,...,VALUE1n +MATCHER2,VALUE21,VALUE22,...,VALUE2n +MATCHER3,VALUE31,VALUE32,...,VALUE3n + + + Conditional tables ("if tables") are a different syntax to specify +field assignments that will be applied only to CSV records which match +certain patterns. + + MATCHER could be either field or record matcher, as described above. +When MATCHER matches, values from that row would be assigned to the CSV +fields named on the 'if' line, in the same order. + + Therefore 'if' table is exactly equivalent to a sequence of of 'if' +blocks: + +if MATCHER1 + CSVFIELDNAME1 VALUE11 + CSVFIELDNAME2 VALUE12 + ... + CSVFIELDNAMEn VALUE1n + +if MATCHER2 + CSVFIELDNAME1 VALUE21 + CSVFIELDNAME2 VALUE22 + ... + CSVFIELDNAMEn VALUE2n + +if MATCHER3 + CSVFIELDNAME1 VALUE31 + CSVFIELDNAME2 VALUE32 + ... + CSVFIELDNAMEn VALUE3n + + Each line starting with MATCHER should contain enough (possibly +empty) values for all the listed fields. + + Rules would be checked and applied in the order they are listed in +the table and, like with 'if' blocks, later rules (in the same or +another table) or 'if' blocks could override the effect of any rule. + + Instead of ',' you can use a variety of other non-alphanumeric +characters as a separator. First character after 'if' is taken to be +the separator for the rest of the table. It is the responsibility of +the user to ensure that separator does not occur inside MATCHERs and +values - there is no way to escape separator. + + 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: end, Next: date-format, Prev: if table, Up: CSV rules + +13.2.8 'end' +------------ + +This rule can be used inside if blocks (only), to make hledger stop +reading this CSV file and move on to the next input file, or to command +execution. Eg: + +# ignore everything following the first empty record +if ,,,, + end + + +File: hledger.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV rules + +13.2.9 '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 +date parsing pattern, which 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 + + For the supported strptime syntax, see: +https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime + + Note that although you can parse date-times which include a time +zone, that time zone is ignored; it will not change the date that is +parsed. This means when reading CSV data with times not in your local +time zone, dates can be "off by one". + + +File: hledger.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV rules + +13.2.10 '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: newest-first, Next: include, Prev: decimal-mark, Up: CSV rules + +13.2.11 'newest-first' +---------------------- + +hledger always sorts the generated transactions by date. Transactions +on the same date should appear in the same order as their CSV records, +as hledger can usually auto-detect whether the CSV's normal order is +oldest first or newest first. But if all of the following are true: + + * the CSV might sometimes contain just one day of data (all records + having the same date) + * the CSV records are normally in reverse chronological order (newest + at the top) + * and you care about preserving the order of same-day transactions + + then, you should add the 'newest-first' rule as a hint. Eg: + +# tell hledger explicitly that the CSV is normally newest first +newest-first + + +File: hledger.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV rules + +13.2.12 '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: balance-type, Prev: include, Up: CSV rules + +13.2.13 '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: Tips, Prev: CSV rules, Up: CSV FORMAT + +13.3 Tips +========= + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* 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:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Tips + +13.3.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: Tips + +13.3.2 Valid CSV +---------------- + +hledger accepts CSV conforming to RFC 4180. When CSV values are +enclosed in quotes, note: + + * they must be double quotes (not single quotes) + * spaces outside the quotes are not allowed + + +File: hledger.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: Tips + +13.3.3 File Extension +--------------------- + +To help hledger identify the format and show the right error messages, +CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or +'.tsv' filename extension. Or, the file path should be prefixed with +'csv:', 'ssv:' or 'tsv:'. Eg: + +$ hledger -f foo.ssv print + + or: + +$ cat foo | hledger -f ssv:- foo + + You can override the file extension with a separator rule if needed. +See also: Input files in the hledger manual. + + +File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: Tips + +13.3.4 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: Tips + +13.3.5 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: Tips + +13.3.6 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: Tips + +13.3.7 Setting amounts +---------------------- + +Some tips on using the amount-setting rules discussed above. + + Here are the ways to set a posting's amount: + + 1. *If the CSV has a single amount field:* + Assign (via a fields list or a field assignment) to 'amountN'. + This sets the Nth posting's amount. N is usually 1 or 2 but can go + up to 99. + + 2. *If the CSV has separate amount fields for debit & credit (in & + out):* + + a. *If both fields are unsigned:* + Assign to 'amountN-in' and 'amountN-out'. This sets posting + N's amount to whichever of these has a non-zero value, and + negates the "-out" value. + + b. *If either field is signed (can contain a minus sign):* + Use a conditional rule to flip the sign (of non-empty values). + Since hledger always negates amountN-out, if it was already + negative, we must undo that by negating once more (but only if + the field is non-empty): + + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields, or neither field, can contain a non-zero + value:* + hledger normally expects exactly one of the fields to have a + non-zero value. Eg, the 'amountN-in'/'amountN-out' rules + would reject value pairs like these: + + "", "" + "0", "0" + "1", "none" + + So, use smarter conditional rules to set the amount from the + appropriate field. Eg, these rules would make it use only the + value containing non-zero digits, handling the above: + + 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:* + Assign to 'amount' (or to 'amount-in' and 'amount-out'). (This is + the legacy numberless syntax, which sets amount1 and amount2 and + converts amount2 to cost.) + + 4. *If the CSV has the balance instead of the transaction amount:* + Assign to 'balanceN', which sets posting N's amount indirectly via + a balance assignment. (Old syntax: 'balance', equivalent to + 'balance1'.) + + * *If hledger guesses the wrong default account name:* + When setting the amount via balance assertion, hledger may + guess the wrong default account name. So, set the account + name explicitly, eg: + + fields date, description, balance1 + account1 assets:checking + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Tips + +13.3.8 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: Tips + +13.3.9 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: Tips + +13.3.10 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: Tips + +13.3.11 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, Prev: Referencing other fields, Up: Tips + +13.3.12 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 %CSVFIELDNAME references), or a + default + * generate a synthetic hledger transaction 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: TIMECLOCK FORMAT, Next: TIMEDOT FORMAT, Prev: CSV FORMAT, Up: Top + +14 TIMECLOCK FORMAT +******************* + +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). + +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 FORMAT, Next: COMMON TASKS, Prev: TIMECLOCK FORMAT, Up: Top + +15 TIMEDOT FORMAT +***************** + +'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.: + + * Lines beginning with '#' or ';', and blank lines, are ignored. + + * 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.) + + * One or more stars ('*') followed by a space, at the start of a + line, is ignored. So date lines or time transaction lines can also + be Org-mode headlines. + + * All Org-mode headlines before the first date line are ignored. + + 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: COMMON TASKS, Next: LIMITATIONS, Prev: TIMEDOT FORMAT, Up: Top + +16 COMMON TASKS +*************** + +Here are some quick examples of how to do some basic tasks with hledger. +For more details, see the reference section below, the +hledger_journal(5) manual, or the more extensive docs at +https://hledger.org. + +* 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: COMMON TASKS + +16.1 Getting help +================= + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show common and command options, and command help +$ hledger help # show available manuals/topics +$ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) +$ hledger help journal -m # show the journal topic, as a man page scrolled to that section +$ hledger help --help # show more detailed help for the help command + + Find more docs, chat, mail list, reddit, issue tracker: +https://hledger.org/support.html-feedback + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS + +16.2 Constructing command lines +=============================== + +hledger has an extensive and powerful command line interface. We strive +to keep it simple and ergonomic, but you may run into one of the +confusing real world details described in OPTIONS, below. If that +happens, here are some tips that may help: + + * command-specific options must go after the command (it's fine to + put all options there) ('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 is being parsed, add '--debug=2'. + + +File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS + +16.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: COMMON TASKS + +16.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: COMMON TASKS + +16.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: COMMON TASKS + +16.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: COMMON TASKS + +16.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 --flat -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 --flat -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: COMMON TASKS + +16.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. + + +File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: COMMON TASKS, Up: Top + +17 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 file +format differences. + + On large data files, hledger is slower and uses more memory than +Ledger. + + +File: hledger.info, Node: TROUBLESHOOTING, Prev: LIMITATIONS, Up: Top + +18 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 + + +Tag Table: +Node: Top208 +Node: OPTIONS2614 +Ref: #options2715 +Node: General options2857 +Ref: #general-options2982 +Node: Command options7195 +Ref: #command-options7346 +Node: Command arguments7746 +Ref: #command-arguments7904 +Node: Special characters8784 +Ref: #special-characters8947 +Node: Single escaping shell metacharacters9110 +Ref: #single-escaping-shell-metacharacters9351 +Node: Double escaping regular expression metacharacters9954 +Ref: #double-escaping-regular-expression-metacharacters10265 +Node: Triple escaping for add-on commands10791 +Ref: #triple-escaping-for-add-on-commands11051 +Node: Less escaping11695 +Ref: #less-escaping11849 +Node: Unicode characters12173 +Ref: #unicode-characters12338 +Node: Regular expressions13750 +Ref: #regular-expressions13890 +Node: ENVIRONMENT15626 +Ref: #environment15742 +Node: DATA FILES17234 +Ref: #data-files17353 +Node: Data formats17892 +Ref: #data-formats18010 +Node: Multiple files19404 +Ref: #multiple-files19546 +Node: Strict mode20015 +Ref: #strict-mode20130 +Node: TIME PERIODS20854 +Ref: #time-periods20971 +Node: Smart dates21069 +Ref: #smart-dates21195 +Node: Report start & end date23025 +Ref: #report-start-end-date23200 +Node: Report intervals24867 +Ref: #report-intervals25035 +Node: Period expressions26774 +Ref: #period-expressions26914 +Node: Period expressions with a report interval28645 +Ref: #period-expressions-with-a-report-interval28877 +Node: More complex report intervals29958 +Ref: #more-complex-report-intervals30207 +Node: Intervals with custom start date30847 +Ref: #intervals-with-custom-start-date31079 +Node: Periods or dates ?32653 +Ref: #periods-or-dates32855 +Node: Events on multiple weekdays33297 +Ref: #events-on-multiple-weekdays33476 +Node: DEPTH34339 +Ref: #depth34439 +Node: QUERIES34773 +Ref: #queries34882 +Node: Query types35823 +Ref: #query-types35942 +Node: Combining query terms39116 +Ref: #combining-query-terms39291 +Node: Queries and command options40094 +Ref: #queries-and-command-options40297 +Node: Queries and account aliases40546 +Ref: #queries-and-account-aliases40749 +Node: Queries and valuation40869 +Ref: #queries-and-valuation41062 +Node: Querying with account aliases41291 +Ref: #querying-with-account-aliases41500 +Node: Querying with cost or value41630 +Ref: #querying-with-cost-or-value41805 +Node: CONVERSION & COST42106 +Ref: #conversion-cost42239 +Node: Recording conversions43128 +Ref: #recording-conversions43300 +Node: Implicit conversion43752 +Ref: #implicit-conversion43909 +Node: Priced conversion44728 +Ref: #priced-conversion44907 +Node: Equity conversion45315 +Ref: #equity-conversion45499 +Node: Priced equity conversion46287 +Ref: #priced-equity-conversion46459 +Node: Inferring missing conversion rates46807 +Ref: #inferring-missing-conversion-rates47047 +Node: Inferring missing equity postings47163 +Ref: #inferring-missing-equity-postings47394 +Node: Cost reporting47542 +Ref: #cost-reporting47719 +Node: Conversion summary48239 +Ref: #conversion-summary48382 +Node: VALUATION49104 +Ref: #valuation49222 +Node: -V Value49989 +Ref: #v-value50113 +Node: -X Value in specified commodity50308 +Ref: #x-value-in-specified-commodity50501 +Node: Valuation date50650 +Ref: #valuation-date50812 +Node: Market prices51249 +Ref: #market-prices51431 +Node: --infer-market-prices market prices from transactions52614 +Ref: #infer-market-prices-market-prices-from-transactions52881 +Node: Valuation commodity54765 +Ref: #valuation-commodity54976 +Node: Simple valuation examples56202 +Ref: #simple-valuation-examples56398 +Node: --value Flexible valuation57057 +Ref: #value-flexible-valuation57259 +Node: More valuation examples58903 +Ref: #more-valuation-examples59110 +Node: Interaction of valuation and queries61109 +Ref: #interaction-of-valuation-and-queries61348 +Node: Effect of valuation on reports61820 +Ref: #effect-of-valuation-on-reports62015 +Node: PIVOTING69712 +Ref: #pivoting69817 +Node: OUTPUT71503 +Ref: #output71605 +Node: Output destination71696 +Ref: #output-destination71830 +Node: Output styling72487 +Ref: #output-styling72635 +Node: Output format73392 +Ref: #output-format73536 +Node: CSV output74900 +Ref: #csv-output75018 +Node: HTML output75121 +Ref: #html-output75261 +Node: JSON output75355 +Ref: #json-output75495 +Node: SQL output76412 +Ref: #sql-output76530 +Node: Commodity styles77031 +Ref: #commodity-styles77158 +Node: COMMANDS77934 +Ref: #commands78046 +Node: accounts81411 +Ref: #accounts81511 +Node: activity82319 +Ref: #activity82431 +Node: add82814 +Ref: #add82917 +Node: aregister85712 +Ref: #aregister85826 +Node: aregister and custom posting dates88495 +Ref: #aregister-and-custom-posting-dates88661 +Node: balance89213 +Ref: #balance89332 +Node: balance features90325 +Ref: #balance-features90465 +Node: Simple balance report92389 +Ref: #simple-balance-report92571 +Node: Filtered balance report94051 +Ref: #filtered-balance-report94238 +Node: List or tree mode94565 +Ref: #list-or-tree-mode94733 +Node: Depth limiting96078 +Ref: #depth-limiting96244 +Node: Dropping top-level accounts96845 +Ref: #dropping-top-level-accounts97047 +Node: Multi-period balance report97357 +Ref: #multi-period-balance-report97570 +Node: Showing declared accounts99845 +Ref: #showing-declared-accounts100038 +Node: Data layout100569 +Ref: #data-layout100724 +Node: Sorting by amount108664 +Ref: #sorting-by-amount108819 +Node: Percentages109489 +Ref: #percentages109647 +Node: Balance change end balance110608 +Ref: #balance-change-end-balance110801 +Node: Balance report types112229 +Ref: #balance-report-types112419 +Node: Useful balance reports116698 +Ref: #useful-balance-reports116879 +Node: Budget report117964 +Ref: #budget-report118148 +Node: Budget report start date123423 +Ref: #budget-report-start-date123601 +Node: Budgets and subaccounts124933 +Ref: #budgets-and-subaccounts125140 +Node: Selecting budget goals128580 +Ref: #selecting-budget-goals128752 +Node: Customising single-period balance reports129786 +Ref: #customising-single-period-balance-reports129995 +Node: balancesheet132170 +Ref: #balancesheet132308 +Node: balancesheetequity133636 +Ref: #balancesheetequity133787 +Node: cashflow135190 +Ref: #cashflow135314 +Node: check136746 +Ref: #check136851 +Node: Basic checks137485 +Ref: #basic-checks137603 +Node: Strict checks138154 +Ref: #strict-checks138295 +Node: Other checks138731 +Ref: #other-checks138871 +Node: Custom checks139228 +Ref: #custom-checks139348 +Node: close139765 +Ref: #close139869 +Node: close and prices141960 +Ref: #close-and-prices142089 +Node: close date142484 +Ref: #close-date142668 +Node: Example close asset/liability accounts for file transition143425 +Ref: #example-close-assetliability-accounts-for-file-transition143726 +Node: Hiding opening/closing transactions144585 +Ref: #hiding-openingclosing-transactions144856 +Node: close and balance assertions146233 +Ref: #close-and-balance-assertions146491 +Node: Example close revenue/expense accounts to retained earnings147845 +Ref: #example-close-revenueexpense-accounts-to-retained-earnings148123 +Node: codes149013 +Ref: #codes149123 +Node: commodities149835 +Ref: #commodities149964 +Node: descriptions150046 +Ref: #descriptions150176 +Node: diff150480 +Ref: #diff150588 +Node: files151635 +Ref: #files151737 +Node: help151884 +Ref: #help151986 +Node: import152804 +Ref: #import152920 +Node: Deduplication154013 +Ref: #deduplication154138 +Node: Import testing156032 +Ref: #import-testing156197 +Node: Importing balance assignments156685 +Ref: #importing-balance-assignments156891 +Node: Commodity display styles157540 +Ref: #commodity-display-styles157713 +Node: incomestatement157842 +Ref: #incomestatement157977 +Node: notes159309 +Ref: #notes159424 +Node: payees159792 +Ref: #payees159900 +Node: prices160426 +Ref: #prices160534 +Node: print160903 +Ref: #print161015 +Node: print-unique166383 +Ref: #print-unique166511 +Node: register166796 +Ref: #register166925 +Node: Custom register output171675 +Ref: #custom-register-output171806 +Node: register-match173143 +Ref: #register-match173279 +Node: rewrite173630 +Ref: #rewrite173747 +Node: Re-write rules in a file175653 +Ref: #re-write-rules-in-a-file175816 +Node: Diff output format176965 +Ref: #diff-output-format177148 +Node: rewrite vs print --auto178240 +Ref: #rewrite-vs.-print---auto178400 +Node: roi178956 +Ref: #roi179056 +Node: Spaces and special characters in --inv and --pnl180781 +Ref: #spaces-and-special-characters-in---inv-and---pnl181021 +Node: Semantics of --inv and --pnl181509 +Ref: #semantics-of---inv-and---pnl181748 +Node: IRR and TWR explained183598 +Ref: #irr-and-twr-explained183758 +Node: stats186844 +Ref: #stats186945 +Node: tags188325 +Ref: #tags188425 +Node: test189439 +Ref: #test189555 +Node: About add-on commands190302 +Ref: #about-add-on-commands190439 +Node: JOURNAL FORMAT191570 +Ref: #journal-format191698 +Node: Transactions193925 +Ref: #transactions194040 +Node: Dates195054 +Ref: #dates195170 +Node: Simple dates195235 +Ref: #simple-dates195355 +Node: Secondary dates195864 +Ref: #secondary-dates196012 +Node: Posting dates197348 +Ref: #posting-dates197471 +Node: Status198843 +Ref: #status198953 +Node: Code200661 +Ref: #code200773 +Node: Description201005 +Ref: #description201133 +Node: Payee and note201453 +Ref: #payee-and-note201561 +Node: Comments201896 +Ref: #comments202018 +Node: Tags203212 +Ref: #tags-1203323 +Node: Postings204716 +Ref: #postings204840 +Node: Virtual postings205866 +Ref: #virtual-postings205977 +Node: Account names207282 +Ref: #account-names207419 +Node: Amounts207907 +Ref: #amounts208044 +Node: Decimal marks digit group marks209029 +Ref: #decimal-marks-digit-group-marks209206 +Node: Commodity210227 +Ref: #commodity210416 +Node: Directives influencing number parsing and display211368 +Ref: #directives-influencing-number-parsing-and-display211629 +Node: Commodity display style212122 +Ref: #commodity-display-style212330 +Node: Rounding214525 +Ref: #rounding214645 +Node: Transaction prices215057 +Ref: #transaction-prices215223 +Node: Lot prices lot dates217654 +Ref: #lot-prices-lot-dates217837 +Node: Balance assertions218325 +Ref: #balance-assertions218503 +Node: Assertions and ordering219576 +Ref: #assertions-and-ordering219767 +Node: Assertions and multiple included files220467 +Ref: #assertions-and-multiple-included-files220729 +Node: Assertions and multiple -f files221229 +Ref: #assertions-and-multiple--f-files221482 +Node: Assertions and commodities221879 +Ref: #assertions-and-commodities222103 +Node: Assertions and prices223283 +Ref: #assertions-and-prices223491 +Node: Assertions and subaccounts223931 +Ref: #assertions-and-subaccounts224154 +Node: Assertions and virtual postings224478 +Ref: #assertions-and-virtual-postings224718 +Node: Assertions and auto postings224850 +Ref: #assertions-and-auto-postings225082 +Node: Assertions and precision225727 +Ref: #assertions-and-precision225911 +Node: Balance assignments226178 +Ref: #balance-assignments226348 +Node: Balance assignments and prices227512 +Ref: #balance-assignments-and-prices227678 +Node: Directives227902 +Ref: #directives228065 +Node: Directives and multiple files232557 +Ref: #directives-and-multiple-files232753 +Node: Comment blocks233445 +Ref: #comment-blocks233622 +Node: Including other files233798 +Ref: #including-other-files233972 +Node: Default year234896 +Ref: #default-year235054 +Node: Declaring payees235461 +Ref: #declaring-payees235632 +Node: Declaring the decimal mark235878 +Ref: #declaring-the-decimal-mark236078 +Node: Declaring commodities236475 +Ref: #declaring-commodities236666 +Node: Commodity error checking239184 +Ref: #commodity-error-checking239334 +Node: Default commodity239849 +Ref: #default-commodity240029 +Node: Declaring market prices241145 +Ref: #declaring-market-prices241334 +Node: Declaring accounts242147 +Ref: #declaring-accounts242327 +Node: Account error checking243551 +Ref: #account-error-checking243717 +Node: Account comments244896 +Ref: #account-comments245080 +Node: Account subdirectives245521 +Ref: #account-subdirectives245706 +Node: Account types246024 +Ref: #account-types246198 +Node: Account display order249873 +Ref: #account-display-order250033 +Node: Rewriting accounts251184 +Ref: #rewriting-accounts251363 +Node: Basic aliases252403 +Ref: #basic-aliases252539 +Node: Regex aliases253283 +Ref: #regex-aliases253445 +Node: Combining aliases254335 +Ref: #combining-aliases254518 +Node: Aliases and multiple files255794 +Ref: #aliases-and-multiple-files255993 +Node: end aliases256572 +Ref: #end-aliases256766 +Node: Aliases can generate bad account names256915 +Ref: #aliases-can-generate-bad-account-names257158 +Node: Aliases and account types257743 +Ref: #aliases-and-account-types257940 +Node: Default parent account258636 +Ref: #default-parent-account258826 +Node: Periodic transactions259710 +Ref: #periodic-transactions259893 +Node: Periodic rule syntax261848 +Ref: #periodic-rule-syntax262028 +Node: Periodic rules and relative dates262487 +Ref: #periodic-rules-and-relative-dates262755 +Node: Two spaces between period expression and description!263266 +Ref: #two-spaces-between-period-expression-and-description263592 +Node: Forecasting with periodic transactions264276 +Ref: #forecasting-with-periodic-transactions264575 +Node: Budgeting with periodic transactions267346 +Ref: #budgeting-with-periodic-transactions267579 +Node: Auto postings267988 +Ref: #auto-postings268124 +Node: Auto postings and multiple files270303 +Ref: #auto-postings-and-multiple-files270501 +Node: Auto postings and dates270710 +Ref: #auto-postings-and-dates270978 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions271153 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions271498 +Node: Auto posting tags272001 +Ref: #auto-posting-tags272210 +Node: CSV FORMAT272846 +Ref: #csv-format272974 +Node: Examples275603 +Ref: #examples275706 +Node: Basic275914 +Ref: #basic276016 +Node: Bank of Ireland276558 +Ref: #bank-of-ireland276695 +Node: Amazon278157 +Ref: #amazon278277 +Node: Paypal279996 +Ref: #paypal280092 +Node: CSV rules287736 +Ref: #csv-rules287854 +Node: skip288187 +Ref: #skip288287 +Node: fields list288662 +Ref: #fields-list288801 +Node: field assignment290367 +Ref: #field-assignment290519 +Node: Field names291554 +Ref: #field-names291694 +Node: date field292074 +Ref: #date-field292194 +Node: date2 field292242 +Ref: #date2-field292385 +Node: status field292441 +Ref: #status-field292586 +Node: code field292635 +Ref: #code-field292782 +Node: description field292827 +Ref: #description-field292989 +Node: comment field293048 +Ref: #comment-field293205 +Node: account field293516 +Ref: #account-field293668 +Node: amount field294243 +Ref: #amount-field294394 +Node: currency field295639 +Ref: #currency-field295794 +Node: balance field296051 +Ref: #balance-field296185 +Node: separator296557 +Ref: #separator296689 +Node: if block297229 +Ref: #if-block297356 +Node: Matching the whole record297757 +Ref: #matching-the-whole-record297934 +Node: Matching individual fields298737 +Ref: #matching-individual-fields298943 +Node: Combining matchers299167 +Ref: #combining-matchers299365 +Node: Rules applied on successful match299678 +Ref: #rules-applied-on-successful-match299871 +Node: if table300525 +Ref: #if-table300646 +Node: end302384 +Ref: #end302498 +Node: date-format302722 +Ref: #date-format302856 +Node: decimal-mark303852 +Ref: #decimal-mark303999 +Node: newest-first304338 +Ref: #newest-first304481 +Node: include305164 +Ref: #include305297 +Node: balance-type305741 +Ref: #balance-type305863 +Node: Tips306563 +Ref: #tips306654 +Node: Rapid feedback306953 +Ref: #rapid-feedback307072 +Node: Valid CSV307524 +Ref: #valid-csv307656 +Node: File Extension307848 +Ref: #file-extension308002 +Node: Reading multiple CSV files308431 +Ref: #reading-multiple-csv-files308618 +Node: Valid transactions308859 +Ref: #valid-transactions309039 +Node: Deduplicating importing309667 +Ref: #deduplicating-importing309848 +Node: Setting amounts310884 +Ref: #setting-amounts311041 +Node: Amount signs313485 +Ref: #amount-signs313639 +Node: Setting currency/commodity314326 +Ref: #setting-currencycommodity314514 +Node: Amount decimal places315688 +Ref: #amount-decimal-places315880 +Node: Referencing other fields316192 +Ref: #referencing-other-fields316391 +Node: How CSV rules are evaluated317288 +Ref: #how-csv-rules-are-evaluated317463 +Node: TIMECLOCK FORMAT318914 +Ref: #timeclock-format319054 +Node: TIMEDOT FORMAT321115 +Ref: #timedot-format321253 +Node: COMMON TASKS325815 +Ref: #common-tasks325944 +Node: Getting help326351 +Ref: #getting-help326485 +Node: Constructing command lines327075 +Ref: #constructing-command-lines327269 +Node: Starting a journal file327966 +Ref: #starting-a-journal-file328166 +Node: Setting opening balances329354 +Ref: #setting-opening-balances329552 +Node: Recording transactions332693 +Ref: #recording-transactions332875 +Node: Reconciling333431 +Ref: #reconciling333576 +Node: Reporting335833 +Ref: #reporting335975 +Node: Migrating to a new file339974 +Ref: #migrating-to-a-new-file340124 +Node: LIMITATIONS340423 +Ref: #limitations340551 +Node: TROUBLESHOOTING341294 +Ref: #troubleshooting341409  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -6,8004 +6,7998 @@ NAME This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger's concepts and file formats. This - manual is for hledger 1.26. - -SYNOPSIS - hledger - - hledger [-f FILE] COMMAND [OPTIONS] [ARGS] - - hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] - -DESCRIPTION - hledger is a reliable, cross-platform set of programs for tracking - money, time, or any other commodity, using double-entry accounting and - a simple, editable file format. hledger is inspired by and largely - compatible with ledger(1). - - The basic function of the hledger CLI is to read a plain text file - describing financial transactions (in accounting terms, a general jour- - nal) and print useful reports on standard output, or export them as - CSV. hledger can also read some other file formats such as CSV files, - translating them to journal format. Additionally, hledger lists other - hledger-* executables found in the user's $PATH and can invoke them as - subcommands. - - hledger reads data from one or more files in hledger journal, time- - clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must - be a real environment variable, not a shell variable. You can specify - standard input with -f-. - - Transactions are dated movements of money between two (or more) named - accounts, and are recorded with journal entries like this: - - 2015/10/16 bought food - expenses:food $10 - assets:cash - - Most users use a text editor to edit the journal, usually with an edi- - tor mode such as ledger-mode for added convenience. hledger's interac- - tive add command is another way to record new transactions. hledger - never changes existing transactions. - - To get started, you can either save some entries like the above in - ~/.hledger.journal, or run hledger add and follow the prompts. Then - try some commands like hledger print or hledger balance. Run hledger - with no arguments for a list of commands. - -OPTIONS - General options - To see general usage help, including general options which are sup- - ported by most hledger commands, run hledger -h. - - General help options: - - -h --help - show general 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 fol- - lowing 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 com- - modities - - -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 charac- - ters. 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. - - 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. - - 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 noth- - ing). 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. - - Special characters - 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 dou- - ble 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. - - 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:\\$ - - 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 argu- - ments 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:\\$ - - 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: - - o an @argumentfile - - o hledger-ui's filter field - - o hledger-web's search form - - o GHCI's prompt (used by developers). - - Unicode characters - hledger is expected to handle non-ascii characters correctly: - - o 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.) - - o 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: - - o 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 Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- - grams). - - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode - - o the terminal must be using a font which includes the required unicode - glyphs - - o the terminal should be configured to display wide characters as dou- - ble width (for report alignment) - - o 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 stan- - dard 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). - - Regular expressions - hledger uses regular expressions in a number of places: - - o query terms, on the command line and in the hledger-web search form: - REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX - - o CSV rules conditional blocks: if REGEX ... - - o account alias directives and options: alias /REGEX/ = REPLACEMENT, - --alias /REGEX/=REPLACEMENT - - hledger's regular expressions come from the regex-tdfa library. 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: - - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, - these are not required. - - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts - with the dollar sign in hledger-web, write cur:\$. - - o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped at least once more. See Spe- - cial characters. - -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\MyUser- - Name\.hledger.journal. You can change this by running a command like - this in a powershell window: - - > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - - (Let us know if you need to be an Administrator, and if this persists - across a reboot.) - - 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. - -DATA FILES - hledger reads transactions from one or more data files. The default - data file is $HOME/.hledger.journal (or on Windows, something like - C:/Users/USER/.hledger.journal). - - You can override this with the $LEDGER_FILE environment variable: - - $ setenv LEDGER_FILE ~/finance/2016.journal - $ hledger stats - - or with 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- - - 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 exten- - sions: - ----------------------------------------------------------------------------- - journal hledger journal files and some Ledger .journal .j .hledger - journals, for transactions .ledger - time- timeclock files, for precise time log- .timeclock - clock ging - 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 their own sections, 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:- - - Multiple files - You can specify multiple -f options, to read multiple files as one big - journal. There are some limitations with this: - - o most directives do not affect sibling files - - o balance assertions will not see any account balances from previous - files - - If you need either of those things, you can - - o use a single parent file which includes the others - - o or concatenate the files into one before reading, eg: cat a.journal - b.journal | hledger -f- CMD. - - Strict mode - hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files - without a lot of declarations: - - o Are the input files parseable, with valid syntax ? - - o Are all transactions balanced ? - - o Do all balance assertions pass ? - - With the -s/--strict flag, additional checks are performed: - - o Are all accounts posted to, declared with an account directive ? - (Account error checking) - - o Are all commodities declared with a commodity directive ? (Commodity - error checking) - - o Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks -- the ones - listed above and some more. - -TIME PERIODS - Smart dates - hledger's user interfaces accept a flexible "smart date" syntax. Smart - dates allow some english words, can be relative to today's date, and - can have less-significant date parts omitted (defaulting to 1). - - Examples: - - - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year - 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 - 2004 start of year - 2004/10 start of month - 10/1 month and day in current year - 21 day in current month - october, oct start of month in current year - yesterday, today, tomor- -1, 0, 1 days from today - row - last/this/next -1, 0, 1 periods from the current period - day/week/month/quar- - ter/year - in n n periods from the current period - days/weeks/months/quar- - ters/years - n n periods from the current period - days/weeks/months/quar- - ters/years ahead - n -n periods from the current period - days/weeks/months/quar- - ters/years ago - 20181201 8 digit YYYYMMDD with valid year month and day - 201812 6 digit YYYYMM with valid year and month - - Counterexamples - malformed digit sequences might give surprising - results: - - - 201813 6 digits with an invalid month is parsed as start of - 6-digit year - 20181301 8 digits with an invalid month is parsed as start of - 8-digit year - 20181232 8 digits with an invalid day gives an error - 201801012 9+ digits beginning with a valid YYYYMMDD gives an error - - Note "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; those are not affected by --today.) - - - Report start & end date - By default, most hledger reports will show the full span of time repre- - sented by the journal data. 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. - - Some notes: - - o End dates are exclusive, as in Ledger, so you should write the date - after the last day you want to see in the report. - - o As noted in reporting options: among start/end dates specified with - options, the last (i.e. right-most) option takes precedence. - - o 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. - - o A report interval (see below) will adjust start/end dates, when - needed, so that they fall on subperiod boundaries. - - Examples: - - - -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year - (11/30 will be the last date included) - -b thismonth all transactions on or after the 1st of the current month - -p thismonth all transactions in the current month - date:2016/3/17.. the above written as queries instead (.. can also be - replaced with -) - date:..12/1 - date:thismonth.. - date:thismonth - - Report intervals - A report interval can be specified so that commands like register, bal- - ance and activity become multi-period, showing each subperiod as a sep- - arate row or column. - - The following "standard" report intervals can be enabled by using their - corresponding flag: - - o -D/--daily - - o -W/--weekly - - o -M/--monthly - - o -Q/--quarterly - - o -Y/--yearly - - These standard intervals always start on natural interval boundaries: - eg --weekly starts on mondays, --monthly starts on the first of the - month, --yearly always starts on January 1st, etc. - - Certain more complex intervals, and more flexible boundary dates, can - be specified by -p/--period. These are described in period expres- - sions, below. - - Report intervals can only be specified by the flags above, and not by - query arguments, currently. - - Report intervals have another effect: multi-period reports are always - expanded to fill a whole number of subperiods. So if you use a report - interval (other than --daily), and you have specified a start or end - date, you may notice those dates being overridden (ie, the report - starts earlier than your requested start date, or ends later than your - requested end date). This is done to ensure "full" first and last sub- - periods, so that all subperiods' numbers are comparable. - - To summarise: - - o In multiperiod reports, all subperiods are forced to be the same - length, to simplify reporting. - - o Reports with the standard --weekly/--monthly/--quarterly/--yearly - intervals are required to start on the first day of a - week/month/quarter/year. We'd like more flexibility here but it - isn't supported yet. - - o --period (below) can specify more complex intervals, starting on any - date. - - Period expressions - The -p/--period option accepts period expressions, a shorthand way of - expressing a start date, end date, and/or report interval all at once. - - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as - exclusive: - - - -p "from 2009/1/1 to 2009/4/1" - - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as - ".." or "-". These are equivalent to the above: - - - -p "2009/1/1 2009/4/1" - -p2009/1/1to2009/4/1 - -p2009/1/1..2009/4/1 - - Dates are smart dates, so if the current year is 2009, the above can - also be written as: - - - -p "1/1 4/1" - -p "january-apr" - -p "this year to 4/1" - - If you specify only one date, the missing start or end date will be the - earliest or latest transaction in your journal: - - - -p "from 2009/1/1" everything after january - 1, 2009 - -p "from 2009/1" the same - -p "from 2009" the same - -p "to 2009" everything before january - 1, 2009 - - A single date with no "from" or "to" defines both the start and end - date like so: - - - -p "2009" the year 2009; equivalent - to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- - lent to "2009/1/1 to - 2009/2/1" - -p "2009/1/1" just that day; equivalent - to "2009/1/1 to 2009/1/2" - - Or you can specify a single quarter like so: - - - -p "2009Q1" first quarter of 2009, - equivalent to "2009/1/1 to - 2009/4/1" - -p "q4" fourth quarter of the cur- - rent year - - Period expressions with a report interval - -p/--period's argument can also begin with, or entirely consist of, a - report interval. This should be separated from the start/end dates (if - any) by a space, or the word in. The basic intervals (which can also - be written as command line flags) are daily, weekly, monthly, quar- - terly, and yearly. Some examples: - - - -p "weekly from 2009/1/1 to 2009/4/1" - -p "monthly in 2008" - -p "quarterly" - - As mentioned above, the weekly, monthly, quarterly and yearly intervals - require a report start date that is the first day of a week, month, - quarter or year. And, report start/end dates will be expanded if - needed to span a whole number of intervals. - - For example: - - - -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- - to 2009/4/1" day - -p "monthly in starts on 2018/11/01 - 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, - 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 - -p "yearly from starts on 2009/01/01, first day of 2009 - 2009-12-29" - - More complex report intervals - Some more complex kinds of interval are also supported in period - expressions: - - o biweekly - - o fortnightly - - o bimonthly - - o every day|week|month|quarter|year - - o every N days|weeks|months|quarters|years - - These too will cause report start/end dates to be expanded, if needed, - to span a whole number of intervals. Examples: - - - -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, - 2008/03/01, ... - -p "every 2 weeks" starts on closest preceding Monday - -p "every 5 months from periods will have boundaries on 2009/03/01, - 2009/03" 2009/08/01, ... - - Intervals with custom start date - All intervals mentioned above are required to start on their natural - calendar boundaries, but the following intervals can start on any date: - - Weekly on custom day: - - o every Nth day of week (th, nd, rd, or st are all accepted after the - number) - - o every WEEKDAYNAME (full or three-letter english weekday name, case - insensitive) - - Monthly on custom day: - - o every Nth day [of month] - - o every Nth WEEKDAYNAME [of month] - - Yearly on custom day: - - o every MM/DD [of year] (month number and day of month number) - - o every MONTHNAME DDth [of year] (full or three-letter english month - name, case insensitive, and day of month number) - - o every DDth MONTHNAME [of year] (equivalent to the above) - - Examples: - - - - - -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" - - Periods or dates ? - Report intervals like the above are most often used with -p|--period, - to divide reports into multiple subperiods - each generated date marks - a subperiod boundary. Here, the periods between the dates are what's - important. - - But report intervals can also be used with --forecast to generate - future transactions, or with balance --budget to generate budget goal- - setting transactions. For these, the dates themselves are what mat- - ters. - - Events on multiple weekdays - The every WEEKDAYNAME form has a special variant with multiple day - names, comma-separated. Eg: every mon,thu,sat. Also, weekday and - weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec- - tively. - - This form is mainly intended for use with --forecast, to generate peri- - odic transactions on arbitrary days of the week. It may be less useful - with -p, since it divides each week into subperiods of unequal length. - (Because gaps between periods are not allowed; if you'd like to change - this, see #1632.) - - Examples: - - - -p "every dates will be Mon, Wed, Fri; periods will be Mon- - mon,wed,fri" Tue, Wed-Thu, Fri-Sun - -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will - be Mon, Tue, Wed, Thu, Fri-Sun - -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri - day" - -DEPTH - With the --depth NUM option (short form: -NUM), commands like account, - balance and register will show only the uppermost accounts in the - account tree, down to level NUM. 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. - -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 argu- - ments to restrict their scope. The syntax is as follows: - - o Zero or more space-separated query terms. These are most often - account name substrings: - - utilities food:groceries - - o Terms with spaces or other special characters should be enclosed in - quotes: - - "personal care" - - o Regular expressions are also supported: - - "^expenses\b" "accounts (payable|receivable)" - - o Add a query type prefix to match other parts of the data: - - date:202012- desc:amazon cur:USD amt:">100" status: - - o Add a not: prefix to negate a term: - - not:cur:USD - - 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 expres- - sion. This is the default query type when there is no prefix, and reg- - ular 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. Oth- - erwise, the absolute magnitudes are compared, ignoring sign. - - code:REGEX - Match by transaction code (eg check number). - - cur:REGEX - Match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a 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). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, - case insensitive. Note type:A and type:E will also match their respec- - tive 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: - - o Accounts also inherit the tags of their parent accounts - - o Postings also inherit the tags of their account and their transaction - - o 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.) - - Combining query terms - Most commands select things which match: - - o any of the description terms AND - - o any of the account terms AND - - o any of the status terms AND - - o all the other terms. - - while the print command shows transactions which: - - o match any of the description terms AND - - o have any postings matching any of the positive account terms AND - - o have no postings matching any of the negative account terms AND - - o match all the other terms. - - You can do more powerful queries (such as AND-ing two like terms) by - running a first query with print, and piping the result into a second - hledger command. Eg: how much of food expenses was paid with cash ? - - $ hledger print assets:cash | hledger -f- -I balance expenses:food - - If you are interested in full boolean expressions for queries, see - #203. - - 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. - - Queries and account aliases - When account names are rewritten with --alias or alias, acct: will - match either the old or the new account name. - - 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). - - 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. - - 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. - -CONVERSION & COST - This section is about converting between commodities. Some defini- - tions: - - o A "commodity conversion" is an exchange of one currency or commodity - for another. Eg a foreign currency exchange, or a purchase or sale - of stock or cryptocurrency. - - o A "conversion transaction" is a transaction involving one or more - such conversions. - - o "Conversion rate" is the exchange rate in a conversion - the cost per - unit of one commodity in the other. - - o "Cost" is how much of one commodity was paid to acquire the other - (when buying), or how much was received in exchange for the other - (when selling). We call both of these "cost" for convenience (after - all, it is cost for one party or the other). - - Recording conversions - As a concrete example, let's assume 100 EUR was converted to 120 USD. - There are several ways to record this in the journal, each with pros - and cons which will be explained in more detail below. (Also, these - examples use journal format which is properly explained much further - below; sorry about that, you may want to read some of that first.) - - Implicit conversion - 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: - - o Easy, concise - - o hledger can do cost reporting - - Con: - - o Less error checking - typos in amounts or commodity symbols may not - be detected - - o conversion rate is not clear - - o disturbs the accounting equation - - You can prevent accidental implicit conversions due to a mistyped com- - modity symbol, by using hledger check commodities. You can prevent - implicit conversions entirely, by using hledger check balancednoauto- - conversion, or -s/--strict. - - Priced conversion - 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: - - o Still concise - - o makes the conversion rate clear - - o provides some error checking - - o hledger can do cost reporting - - Con: - - o Disturbs the accounting equation - - Equity conversion - In strict double entry bookkeeping, the above transaction is not bal- - anced 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: - - o Preserves the accounting equation - - o keeps track of conversions and related gains/losses in one place - - o works in any double entry accounting system - - Con: - - o More verbose - - o conversion rate is not clear - - o hledger can not do cost reporting - - Priced equity conversion - Another possible notation would be to record both the conversion rate - and the equity postings: - - 2021-01-01 - assets:cash -100 EUR @ 1.20 USD - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - hledger currently does not allow this; instead, you can record the con- - version rate as a comment. - - Inferring missing conversion rates - hledger will do this automatically for implicit conversions. Currently - it can not do this for equity conversions. - - Inferring missing equity postings - With the --infer-equity flag, hledger will add equity postings to - priced and implicit conversions (and move the conversion rate into a - comment). - - Cost reporting - With the -B/--cost flag, hledger will convert the amounts in priced and - implicit conversions to their cost in the other commodity. This is - useful to see a report of what you paid for things (or how much you - sold things for). Currently -B/--cost does not work on equity conver- - sions, and it disables --infer-equity. - - These operations are transient, only affecting reports. If you want to - change the journal file permanently, you could pipe each entry through - hledger -f- -I print [-x] [--infer-equity] [-B] - - Conversion summary - o Recording the conversion rate is good because it makes that clear and - allows cost reporting. - - o Recording equity postings is good because it balances the accounting - equation and is correct bookkeeping. - - o Combining these is not yet supported, so you have to choose. For - now, priced conversions are a good compromise, so that: - - o When you want to see the cost (or sale proceeds) of things, use - -B/--cost. - - o When you want to see a balanced balance sheet or correct journal - entries, use --infer-equity. - - o Combining these is not yet supported; -B/--cost will take prece- - dence. - - o Conversion/cost operations are performed before valuation. - -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: - - -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. - - -X: Value in specified commodity - The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to - that. - - 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. - - Market prices - 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 direc- - tive, or (with the --infer-market-prices flag) inferred from trans- - action prices. - - 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 com- - bining 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 con- - verted. - - --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 transaction prices as additional market - prices (as Ledger does) ? We could produce value reports without need- - ing P directives at all. - - 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. (And if - both occur on the same day, the P directive takes precedence). - - There is a downside: value reports can sometimes be affected in confus- - ing/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: - - o multicommodity transactions with explicit prices (@/@@) - - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. - hledger print -x can be useful for troubleshooting.) - - o but not, currently, from "more correct" multicommodity transactions - (no @, multiple commodities, balanced). - - There is another 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 con- - version might not happen because no valuation commodity was detected - (--debug=2 will show this). To be safe, specify the valuation commmod- - ity, eg: - - o -X EUR --infer-market-prices, not -V --infer-market-prices - - o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- - ket-prices - - 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 suit- - able 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: - - o If you have P directives, they determine which commodities -V will - convert, and to what. - - o If you have no P directives, and use the --infer-market-prices flag, - transaction prices determine it. - - Amounts for which no valuation commodity can be found are not con- - verted. - - Simple valuation examples - Here are some quick examples of -V: - - ; one euro is worth this many dollars from nov 1 - P 2016/11/01 EUR $1.10 - - ; purchase some euros on nov 3 - 2016/11/3 - assets:euros EUR100 - assets:checking - - ; the euro is worth fewer dollars by dec 21 - P 2016/12/21 EUR $1.03 - - How many euros do I have ? - - $ hledger -f t.j bal -N euros - EUR100 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 - - --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 commod- - ity, using market prices on each posting's date. - - --value=end - Convert amounts to their value in the default valuation commod- - ity, 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 commod- - ity using current market prices (as of when report is gener- - ated). - - --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- - ity 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. - - 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 specify- - ing a display style for A, 0.5A gets the default style, which shows no - decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- - modity 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 - - 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 - - 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, --cost -V, -X --value=then --value=end --value=DATE, - type --value=now - ----------------------------------------------------------------------------------------------- - print - posting cost value at value at posting value at value at - amounts report end date report or DATE/today - or today journal end - balance unchanged unchanged unchanged unchanged unchanged - asser- - tions/assign- - ments - - register - starting bal- cost value at valued at day value at value at - ance (-H) report or each historical report or DATE/today - journal end posting was made journal end - starting bal- cost value at day valued at day value at day value at - ance (-H) before each historical before DATE/today - with report report or posting was made report or - interval journal journal - start start - posting cost value at value at posting value at value at - amounts report or date report or DATE/today - journal end journal end - summary post- summarised value at sum of postings value at value at - ing amounts cost period ends in interval, val- period ends DATE/today - with report ued at interval - interval start - running sum/average sum/average sum/average of sum/average sum/average - total/average of displayed of displayed displayed values of displayed of displayed - values values values values - - balance (bs, - bse, cf, is) - balance sums of value at value at posting value at value at - changes costs report end date report or DATE/today of - or today of journal end sums of post- - sums of of sums of ings - postings postings - budget like balance like balance like balance like bal- like balance - amounts changes changes changes ances changes - (--budget) - grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- - played val- played val- valued played val- played values - ues ues ues - - - - balance (bs, - bse, cf, is) - with report - interval - starting bal- sums of value at sums of values of value at sums of post- - ances (-H) costs of report start postings before report start ings before - postings of sums of report start at of sums of report start - before all postings respective post- all postings - report start before ing dates before - report start report start - balance sums of same as sums of values of balance value at - changes (bal, costs of --value=end postings in change in DATE/today of - is, bs postings in period at respec- each period, sums of post- - --change, cf period tive posting valued at ings - --change) dates period ends - end balances sums of same as sums of values of period end value at - (bal -H, is costs of --value=end postings from balances, DATE/today of - --H, bs, cf) postings before period valued at sums of post- - from before start to period period ends ings - report start end at respective - to period posting dates - end - budget like balance like balance like balance like bal- like balance - amounts changes/end changes/end changes/end bal- ances changes/end - (--budget) balances balances ances balances - row totals, sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- - (-T, -A) played val- played val- played val- played values - ues ues ues - column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- - played val- played val- values played val- played values - ues ues ues - grand total, sum, average sum, average sum, average of sum, average sum, average - grand average of column of column column totals of column of column - totals totals totals 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 subperi- - ods). - -PIVOTING - Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD - can be: status, code, description, payee, note, or the full name (case - insensitive) of any tag. As with account names, values containing - colon:separated:parts will be displayed hierarchically in reports. - - --pivot is a general option affecting all reports; you can think of - hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on - that posting, inheriting it from the transaction or using a blank value - if it's not present. - - An example: - - 2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe - - Normal balance report showing account names: - - $ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees - -------------------- - 0 - - Pivoted balance report, using member: tag values instead: - - $ hledger balance --pivot member - 2 EUR - -2 EUR John Doe - -------------------- - 0 - - One way to show only amounts with a member: value (using a query, - described below): - - $ hledger balance --pivot member tag:member=. - -2 EUR John Doe - -------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account - name"): - - $ hledger balance --pivot member acct:. - -2 EUR John Doe - -------------------- - -2 EUR - -OUTPUT - 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 pro- - vide 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) - - hledger can optionally produce debug output (if enabled with - --debug=N); this goes to stderr, and is not affected by -o/--output- - file. If you need to capture it, use shell redirects, eg: hledger bal - --debug=3 >file 2>&1. - - Output styling - hledger commands can produce colour output when the terminal supports - it. This is controlled by the --color/--colour option: - 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. - - hledger commands can also use unicode box-drawing characters to produce - prettier tables and output. This is controlled by the --pretty option: - - 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. - - Output format - Some commands offer additional output formats, other than the usual - plain text terminal output. Here are those commands and the formats - currently supported: - - - - txt csv html json sql - --------------------------------------------- - aregister Y Y Y - balance Y 1 Y 1 Y 1,2 Y - bal- Y 1 Y 1 Y 1 Y - ancesheet - bal- Y 1 Y 1 Y 1 Y - ancesheete- - quity - cashflow Y 1 Y 1 Y 1 Y - incomes- Y 1 Y 1 Y 1 Y - tatement - print Y Y Y Y - register Y Y Y - - o 1 Also affected by the balance commands' --layout option. - - o 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 - - CSV output - o In CSV output, digit group marks (such as thousands separators) are - disabled automatically. - - HTML output - o HTML output can be styled by an optional hledger.css file in the same - directory. - - JSON output - o Not yet much used; real-world feedback is welcome. - - o Our JSON is rather large and verbose, as it is quite a faithful rep- - resentation 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. - - o 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) - - SQL output - o Not yet much used; real-world feedback is welcome. - - o SQL output is expected to work with sqlite, MySQL and PostgreSQL - - o SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables cre- - ated 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. - - Commodity styles - The display style of a commodity/currency is inferred according to the - rules described in Commodity display style. The inferred display style - can be overridden by an optional -c/--commodity-style option (Excep- - tions: as is the case for inferred styles, price amounts, and all - amounts displayed by the print command, will be displayed with all of - their decimal digits visible, regardless of the specified precision). - For example, the following will override the display style for dollars. - - $ hledger print -c '$1.000,0' - - The format specification of the style is identical to the commodity - display style specification for the commodity directive. The command - line option can be supplied repeatedly to override the display style - for multiple commodity/currency symbols. - -COMMANDS - hledger provides a number of commands for producing reports and manag- - ing your data. Run hledger with no arguments to list the commands - available, and hledger CMD to run a command. CMD can be the full com- - mand name, or its standard abbreviation shown in the commands list, or - any unambiguous prefix of the name. Eg: hledger bal. - - Here are the built-in commands, with the most often-used in bold: - - Data entry: - - These data entry commands are the only ones which can modify your jour- - nal file. - - o add - add transactions using guided prompts - - o import - add any new transactions from other files (eg csv) - - Data management: - - o check - check for various kinds of issue in the data - - o close (equity) - generate balance-resetting transactions - - o diff - compare account transactions in two journal files - - o rewrite - generate extra postings, similar to print --auto - - Financial statements: - - o aregister (areg) - show transactions in a particular account - - o balancesheet (bs) - show assets, liabilities and net worth - - o balancesheetequity (bse) - show assets, liabilities and equity - - o cashflow (cf) - show changes in liquid assets - - o incomestatement (is) - show revenues and expenses - - o roi - show return on investments - - Miscellaneous reports: - - o accounts - show account names - - o activity - show postings-per-interval bar charts - - o balance (bal) - show balance changes/end balances/budgets in any - accounts - - o codes - show transaction codes - - o commodities - show commodity/currency symbols - - o descriptions - show unique transaction descriptions - - o files - show input file paths - - o help - show hledger user manuals in several formats - - o notes - show unique note segments of transaction descriptions - - o payees - show unique payee segments of transaction descriptions - - o prices - show market price records - - o print - show transactions (journal entries) - - o print-unique - show only transactions with unique descriptions - - o register (reg) - show postings in one or more accounts & running - total - - o register-match - show a recent posting that best matches a descrip- - tion - - o stats - show journal statistics - - o tags - show tag names - - o test - run self tests - - Add-on commands: - - Programs or scripts named hledger-SOMETHING in your PATH are add-on - commands; these appear in the commands list with a + mark. Two of - these are maintained and released with hledger: - - o ui - an efficient terminal interface (TUI) for hledger - - o web - a simple web interface (WUI) for hledger - - And these add-ons are maintained separately: - - o iadd - a more interactive alternative for the add command - - o interest - generates interest transactions according to various - schemes - - o stockquotes - downloads market prices for your commodities from - AlphaVantage (experimental) - - Next, the detailed command docs, in alphabetical order. - - accounts - accounts - Show account names. - - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N - or -N. - - With --types, it also shows each account's type, if it's known. (See - Declaring accounts > Account types.) - - Examples: - - $ hledger accounts - assets:bank:checking - assets:bank:saving - assets:cash - expenses:food - expenses:supplies - income:gifts - income:salary - liabilities:debts - - activity - activity - Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the - default). With query arguments, it counts only matched transactions. - - Examples: - - $ hledger activity --quarterly - 2008-01-01 ** - 2008-04-01 ******* - 2008-07-01 - 2008-10-01 ** - - add - add - Prompt for transactions and add them to the journal. 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 trans- - actions, 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: - - o add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as a - template. - - o You can also set the initial defaults with command line arguments. - - o Readline-style edit keys can be used during data entry. - - o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is - empty, it will insert the default value. - - o If the journal defines a default commodity, it will be added to any - bare numbers entered. - - o A parenthesised transaction code may be entered following a date. - - o Comments and tags may be entered following a description or amount. - - o If you make a mistake, enter < at any prompt to go one step backward. - - o Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see the tutorial for a detailed explanation): - - $ hledger add - Adding transactions to journal file /src/hledger/examples/sample.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to 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). - - aregister - 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 areg- - ister 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. - (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, - hledger areg checking would select assets:aaa:checking.) - - 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 transac- - tions shown. Note some queries will disturb the running balance, caus- - ing 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: - - o the transaction's date (or the relevant posting's date if different, - see below) - - o the names of all the other account(s) involved in this transaction - (probably abbreviated) - - o the total change to this account's balance from this transaction - - o 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. - - 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. - - balance - 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, bal- - ancesheetequity, cashflow and incomestatement. When you need more con- - trol, then use balance. - - 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.. - - o accounts as a list (-l) or a tree (-t) - - o optionally depth-limited (-[1-9]) - - o sorted by declaration order and name, or by amount - - ..and their.. - - o balance changes (the default) - - o or actual and planned balance changes (--budget) - - o or value of balance changes (-V) - - o or change of balance values (--valuechange) - - o or unrealised capital gain/loss (--gain) - - ..in.. - - o one time period (the whole journal period by default) - - o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) - - ..either.. - - o per period (the default) - - o or accumulated since report start date (--cumulative) - - o or accumulated since account creation (--historical/-H) - - ..possibly converted to.. - - o cost (--value=cost[,COMM]/--cost/-B) - - o or market value, as of transaction dates (--value=then[,COMM]) - - o or at period ends (--value=end[,COMM]) - - o or now (--value=now) - - o or at some other date (--value=YYYY-MM-DD) - - ..with.. - - o totals (-T), averages (-A), percentages (-%), inverted sign - (--invert) - - o rows and columns swapped (--transpose) - - o another field used as account name (--pivot) - - o custom-formatted line items (single-period reports only) (--format) - - o 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. - - 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. For real-world - accounts, this should also match their end balance at the end of the - journal period (more on this below). - - Accounts are sorted by declaration order if any, and then alphabeti- - cally 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. - - 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 - - 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: - - o "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). - - o 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-plaintextac- - counting-users. A tree mode report's final total is the sum of the - top-level balances shown, not of all the balances shown. - - o Each group of sibling accounts (ie, under a common parent) is sorted - separately. - - 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 - - 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 - - - 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), bal- - ance 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: - - o The report's start/end dates will be expanded, if necessary, to fully - encompass the displayed subperiods (so that the first and last subpe- - riods have the same duration as the others). - - o Leading and trailing periods (columns) containing all zeroes are not - shown, unless -E/--empty is used. - - o Accounts (rows) containing all zeroes are not shown, unless - -E/--empty is used. - - o Amounts with many commodities are shown in abbreviated form, unless - --no-elide is used. (experimental) - - o Average and/or total columns can be added with the -A/--average and - -T/--row-total flags. - - o The --transpose flag can be used to exchange rows and columns. - - o 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: - - o Hide the totals row with -N/--no-total - - o Convert to a single currency with -V - - o Maximize the terminal window - - o Reduce the terminal's font size - - o View with a pager like less, eg: hledger bal -D --color=yes | less - -RS - - o 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) - - o Output as HTML and view with a browser: hledger bal -D -o a.html && - open a.html - - 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. - - Data layout - The --layout option affects how multi-commodity amounts are displayed, - and some other things, influencing the overall layout of the report - data: - - o --layout=wide[,WIDTH]: commodities are shown on a single line, possi- - bly elided to the specified width - - o --layout=tall: each commodity is shown on a separate line - - o --layout=bare: amounts are shown as bare numbers, with commodity sym- - bols in a separate column - - o --layout=tidy: data is normalised to tidy form, with one row per data - value. We currently support this with CSV output only. In tidy - mode, totals and row averages are disabled (-N/--no-total is implied - and -T/--row-total and -A/--average will be ignored). - - These --layout modes are supported with some but not all of the output - formats: - - - - txt csv html json sql - ------------------------------------- - wide Y Y Y - tall Y Y Y - bare Y Y Y - tidy Y - - Examples: - - o 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 - - o Limited wide layout. A width limit reduces the width, but some com- - modities 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.. - - o 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 - - o Bare layout. Commodity symbols are kept in one column, each commod- - ity 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 - - o Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg when 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" - - o Tidy layout produces normalised "tidy data", where every variable is - a column and each row represents a single data point (see - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- - data.html). This kind of data is the easiest to process with other - software: - - $ 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" - - Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. Eg: hledger bal expenses -MAS shows your big- - gest 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). - - - Percentages - With -%/--percent, balance reports show each account's value expressed - as a percentage of the (column) total: - - $ hledger -f examples/sample.journal bal expenses -Q -% - Balance changes in 2008: - - || 2008Q1 2008Q2 2008Q3 2008Q4 - ===================++================================= - expenses:food || 0 50.0 % 0 0 - expenses:supplies || 0 50.0 % 0 0 - -------------------++--------------------------------- - || 0 100.0 % 0 0 - - Note it is not useful to calculate percentages if the amounts in a col- - umn 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:EUR - - Balance change, end balance - It's important to be clear on the meaning of the numbers shown in bal- - ance 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 post- - ings.) - - Balance report types - For more flexible reporting, there are three important option groups: - - hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] - ... - - The first two are the most important: calculation type selects the - basic calculation to perform for each table cell, while accumulation - type says which postings should be included in each cell's calculation. - Typically one or both of these are selected by default, so you don't - need to write them explicitly. A valuation type can be added if you - want to convert the basic report to value or cost. - - Calculation type: - The basic calculation to perform for each table cell. It is one of: - - o --sum : sum the posting amounts (default) - - o --budget : like --sum but also show a goal amount - - o --valuechange : show the change in period-end historical balance val- - ues (caused by deposits, withdrawals, and/or market price fluctua- - tions) - - o --gain : show the unrealised capital gain/loss, (the current valued - balance minus each amount's original cost) - - Accumulation type: - Which postings should be included in each cell's calculation. It is - one of: - - o --change : postings from column start to column end, ie within the - cell's period. Typically used to see revenues/expenses. (default - for balance, incomestatement) - - o --cumulative : postings from report start to column end, eg to show - changes accumulated since the report's start date. Rarely used. - - o --historical/-H : postings from journal start to column end, ie all - postings from account creation to the end of the cell's period. Typ- - ically used to see historical end balances of assets/liabili- - ties/equity. (default for balancesheet, balancesheetequity, cash- - flow) - - Valuation type: - Which kind of valuation, valuation date(s) and optionally a target val- - uation commodity to use. It is one of: - - o no valuation, show amounts in their original commodities (default) - - o --value=cost[,COMM] : no valuation, show amounts converted to cost - - o --value=then[,COMM] : show value at transaction dates - - o --value=end[,COMM] : show value at period end date(s) (default with - --valuechange, --gain) - - o --value=now[,COMM] : show value at today's date - - o --value=YYYY-MM-DD[,COMM] : show value at another date - - or one of their aliases: --cost/-B, --market/-V or --exchange/-X. - - 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: - - o --valuechange implies --value=end - - o --valuechange makes --change the default when used with the bal- - ancesheet/balancesheetequity commands - - o --cumulative or --historical disables --row-total/-T - - For reference, here is what the combinations of accumulation and valua- - tion show: - - - - Valua- no valuation --value= then --value= end --value= YYYY- - tion: MM-DD /now - >Accumu- - lation: - v - ------------------------------------------------------------------------------------ - --change change in period sum of posting- period-end DATE-value of - date market val- value of change change in - ues in period in period period - --cumu- change from sum of posting- period-end DATE-value of - lative report start to date market val- value of change change from - period end ues from report from report report start - start to period start to period to period end - end end - --his- change from sum of posting- period-end DATE-value of - torical journal start to date market val- value of change change from - /-H period end (his- ues from journal from journal journal start - torical end bal- start to period start to period to period end - ance) end end - - Useful balance reports - Some frequently used balance options/reports are: - - o bal -M revenues expenses - Show revenues/expenses in each month. Also available as the incomes- - tatement command. - - o bal -M -H assets liabilities - Show historical asset/liability balances at each month end. Also - available as the balancesheet command. - - o bal -M -H assets liabilities equity - Show historical asset/liability/equity balances at each month end. - Also available as the balancesheetequity command. - - o bal -M assets not:receivable - Show changes to liquid assets in each month. Also available as the - cashflow command. - - Also: - - o bal -M expenses -2 -SA - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - o bal -M --budget expenses - Show monthly expenses and budget goals. - - o bal -M --valuechange investments - Show monthly change in market value of investment assets. - - o bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert] - Show top gainers [or losers] last week - - 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 very 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: - - o Only accounts with budget goals during the report period are shown, - by default. - - o In each column, in square brackets after the actual amount, budget - goal amounts are shown, and the actual/goal percentage. (Note: bud- - get goals should be in the same commodity as the actual amount.) - - o All parent accounts are always shown, even in list mode. Eg assets, - assets:bank, and expenses above. - - o 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 transac- - tions, 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] - - For more examples and notes, see Budgeting. - - 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] - - 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 bud- - get(s) of the child account(s) would be added to the budget of their - parent, much like account balances behave. - - In the most simple case this means that once you add a budget to any - account, all its parents would have budget as well. - - To illustrate this, consider the following budget: - - ~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which 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 transac- - tions in any other subaccount of expenses:personal would be counted - towards only towards the budget of expenses:personal. - - For example, let's consider these transactions: - - ~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - 2019/01/01 Google home hub - expenses:personal:electronics $90.00 - liabilities $-90.00 - - 2019/01/02 Phone screen protector - expenses:personal:electronics:upgrades $10.00 - liabilities - - 2019/01/02 Weekly train ticket - expenses:personal:train tickets $153.00 - liabilities - - 2019/01/03 Flowers - expenses:personal $30.00 - liabilities - - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- - tions would be counted towards budgets of expenses:personal:electronics - and expenses:personal accordingly: - - $ hledger balance --budget -M - Budget performance in 2019/01: - - || Jan - ===============================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] - -------------------------------++------------------------------- - || 0 [ 0] - - And with --empty, we can get a better picture of budget allocation and - consumption: - - $ hledger balance --budget -M --empty - Budget performance in 2019/01: - - || Jan - ========================================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] - ----------------------------------------++------------------------------- - || 0 [ 0] - - Selecting budget goals - The budget report evaluates periodic transaction rules to generate spe- - cial "goal transactions", which generate the goal amounts for each - account in each report subperiod. When troubleshooting, you can use - the print command 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. - - Customising single-period balance reports - 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 (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with - data fields interpolated like so: - - %[MIN][.MAX](FIELDNAME) - - o MIN pads with spaces to at least this width (optional) - - o MAX truncates at this width (optional) - - o FIELDNAME must be enclosed in parentheses, and can be one of: - - o depth_spacer - a number of spaces equal to the account's depth, or - if MIN is specified, MIN * depth spaces. - - o account - the account's name - - o total - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how multi-com- - modity amounts are rendered: - - o %_ - render on multiple lines, bottom-aligned (the default) - - o %^ - render on multiple lines, top-aligned - - o %, - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, %(depth_spacer) has no - effect, instead %(account) has indentation built in. Experimentation - may be needed to get pleasing results. - - Some example formats: - - o %(total) - the account's total - - o %-20.20(account) - the account's name, left justified, padded to 20 - characters and clipped at 20 characters - - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on - one line - - o %20(total) %2(depth_spacer)%-(account) - the default format for the - single-column balance report - - balancesheet - balancesheet, bs - This command displays a balance sheet, showing historical ending bal- - ances 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. - - The asset and liability accounts shown are those accounts declared with - the Asset or Cash or Liability type, or otherwise all accounts under a - top-level asset or liability account (case insensitive, plurals - allowed). - - 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 sup- - ports 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 (experi- - mental) json. - - balancesheetequity - balancesheetequity, bse - This command displays a balance sheet, showing historical ending bal- - ances of asset, liability and equity accounts. Amounts are shown with - normal positive sign, as in conventional financial statements. - - The asset, liability and equity accounts shown are those accounts - declared with the Asset, Cash, Liability or Equity type, or otherwise - all accounts under a top-level asset, liability or equity account (case - insensitive, plurals allowed). - - 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 sup- - ports 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 (experi- - mental) json. - - cashflow - 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 finan- - cial statements. - - "Cash" assets are those accounts which are (or whose parents are) - declared as Cash by an account directive, like this: - - account some:liquid:asset ; type:C - - Or if there are no such declarations, all accounts - - o under a top-level asset account (case insensitive, plural allowed) - - o with some variation of cash, bank, checking or saving in their name. - - 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 sup- - ports 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 (experi- - mental) json. - - check - 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 - - Here are the checks currently available: - - Basic checks - These checks are always run automatically, by (almost) all hledger com- - mands, including check: - - o parseable - data files are well-formed and can be successfully parsed - - o balancedwithautoconversion - all transactions are balanced, inferring - missing amounts where necessary, and possibly converting commodities - using transaction prices or automatically-inferred transaction prices - - o assertions - all balance assertions in the journal are passing. - (This check can be disabled with -I/--ignore-assertions.) - - 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: - - o accounts - all account names used by transactions have been declared - - o commodities - all commodity symbols used have been declared - - o balancednoautoconversion - transactions are balanced, possibly using - explicit transaction prices but not inferred ones - - 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: - - o ordereddates - transactions are ordered by date within each file - - o payees - all payees used by transactions have been declared - - o uniqueleafnames - all account leaf names are unique - - Custom checks - A few more checks are are available as separate add-on commands, in - https://github.com/simonmichael/hledger/tree/master/bin: - - o hledger-check-tagfiles - all tag values containing / (a forward - slash) exist as file paths - - o hledger-check-fancyassertions - more complex balance assertions are - passing - - You could make similar scripts to perform your own custom checks. See: - Cookbook -> Scripting. - - close - close, equity - Prints a sample "closing" transaction bringing specified account bal- - ances to zero, and an inverse "opening" transaction restoring the same - account balances. - - If like most people you split your journal files by time, eg by year: - at the end of the year you can use this command to "close out" your - asset and liability (and perhaps equity) balances in the old file, and - reinitialise them in the new file. This helps ensure that report bal- - ances remain correct whether you are including old files or not. - (Because all closing/opening transactions except the very first will - cancel out - see example below.) - - Some people also use this command to close out revenue and expense bal- - ances at the end of an accounting period. This properly records the - period's profit/loss as "retained earnings" (part of equity), and - allows the accounting equation (A-L=E) to balance, which you could then - check by the bse report's zero total. - - You can print just the closing transaction by using the --close flag, - or just the opening transaction with the --open flag. - - Their descriptions are closing balances and opening balances by - default; you can customise these with the --close-desc and --open-desc - options. - - Just one balancing equity posting is used by default, with the amount - left implicit. The default account name is equity:opening/closing bal- - ances. You can customise the account name(s) with --close-acct and - --open-acct. (If you specify only one of these, it will be used for - both.) - - With --x/--explicit, the equity posting's amount will be shown explic- - itly, and if it involves multiple commodities, there will be a separate - equity posting for each commodity (as in the print command). - - With --interleaved, each equity posting is shown next to the posting it - balances (good for troubleshooting). - - close and prices - Transaction prices are ignored (and discarded) by closing/opening - transactions, by default. With --show-costs, they are preserved; there - will be a separate equity posting for each cost in each commodity. - This means balance -B reports will look the same after the transition. - Note if you have many foreign currency or investment transactions, this - will generate very large journal entries. - - close date - The default closing date is yesterday, or the journal's end date, - whichever is later. - - Unless you are running close on exactly the first day of the new - period, you'll want to override the closing date. This is done by - specifying a report end date, where "last day of the report period" - will be the closing date. The opening date is always the following - day. So to close on (end of) 2020-12-31 and open on (start of) - 2021-01-01, any of these will work: - - - end date argument explanation - ----------------------------------------------- - -e 2021-01-01 end dates are exclusive - -e 2021 equivalent, per smart - dates - -p 2020 equivalent, the period's - begin date is ignored - date:2020 equivalent query - - Example: close asset/liability accounts for file transition - Carrying asset/liability balances from 2020.journal into a new file for - 2021: - - $ hledger close -f 2020.journal -p 2020 assets liabilities - # copy/paste the closing transaction to the end of 2020.journal - # copy/paste the opening transaction to the start of 2021.journal - - Or: - - $ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction - $ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction - - Now, - - $ hledger bs -f 2021.journal # just new file - balances correct - $ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct - $ hledger bs -f 2020.journal # just old files - balances are zero ? - # (exclude final closing txn, see below) - - Hiding opening/closing transactions - Although the closing/opening transactions cancel out, they will be vis- - ible in reports like print and register, creating some visual clutter. - You can exclude them all with a query, like: - - $ hledger print not:desc:'opening|closing' # less typing - $ hledger print not:'equity:opening/closing balances' # more precise - - But when reporting on multiple files, this can get a bit tricky; you - may need to keep the earliest opening balances, for a historical regis- - ter report; or you may need to suppress a closing transaction, to see - year-end balances. If you find yourself needing more precise queries, - here's one solution: add more easily-matched tags to opening/closing - transactions, like this: - - ; 2019.journal - 2019-01-01 opening balances ; earliest opening txn, no tag here - ... - 2019-12-31 closing balances ; clopen:2020 - ... - - ; 2020.journal - 2020-01-01 opening balances ; clopen:2020 - ... - 2020-12-31 closing balances ; clopen:2021 - ... - - ; 2021.journal - 2021-01-01 opening balances ; clopen:2021 - ... - - Now with - - ; all.journal - include 2019.journal - include 2020.journal - include 2021.journal - - you could do eg: - - $ hledger -f all.journal reg -H checking not:tag:clopen - # all years checking register, hiding non-essential opening/closing txns - - $ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 - # 2020 year end balances, suppressing 2020 closing txn - - close and balance assertions - The closing and opening transactions will include balance assertions, - verifying that the accounts have first been reset to zero and then - restored to their previous balance. These provide valuable error - checking, alerting you when things get out of line, but you can ignore - them temporarily with -I or just remove them if you prefer. - - You probably shouldn't use status or realness filters (like -C or -R or - status:) with close, or the generated balance assertions will depend on - these flags. Likewise, if you run this command with --auto, the bal- - ance assertions would probably always require --auto. - - Multi-day transactions (where some postings have a different date) - break the balance assertions, because the money is temporarily "invisi- - ble" while in transit: - - 2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - assets:bank:checking -5 ; date: 2021/1/2 - - To fix the assertions, you can add a temporary account to track such - in-transit money (splitting the multi-day transaction into two single- - day transactions): - - ; in 2020.journal: - 2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - liabilities:pending - - ; in 2021.journal: - 2021/1/2 clearance of last year's pending transactions - liabilities:pending 5 = 0 - assets:bank:checking - - Example: close revenue/expense accounts to retained earnings - For this, use --close to suppress the opening transaction, as it's not - needed. Also you'll want to change the equity account name to your - equivalent of "equity:retained earnings". - - Closing 2021's first quarter revenues/expenses: - - $ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ - --close-acct='equity:retained earnings' >> 2021.journal - - The same, using the default journal and current year: - - $ hledger close --close revenues expenses -p Q1 \ - --close-acct='equity:retained earnings' >> $LEDGER_FILE - - Now, the first quarter's balance sheet should show a zero (unless you - are using @/@@ notation without equity postings): - - $ hledger bse -p Q1 - - And we must suppress the closing transaction to see the first quarter's - income statement (using the description; not:'retained earnings' won't - work here): - - $ hledger is -p Q1 not:desc:'closing balances' - - codes - 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: - - 1/1 (123) - (a) 1 - - 1/1 () - (a) 1 - - 1/1 - (a) 1 - - 1/1 (126) - (a) 1 - - $ hledger codes - 123 - 124 - 126 - - $ hledger codes -E - 123 - 124 - - - 126 - - commodities - commodities - List all commodity/currency symbols used or declared in the journal. - - descriptions - 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 trans- - actions. - - Example: - - $ hledger descriptions - Store Name - Gas Station | Petrol - Person A - - diff - 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 mul- - tiple 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: - - files - files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - help - help - Show the hledger user manual in one of several formats, optionally - positioned at a given TOPIC (if possible). - - TOPIC is any heading in the manual, or the start of any heading (but - not the middle). It is case insensitive. - - Some examples: commands, print, forecast, "auto postings", "commodity - column". - - This command shows the user manual built in to this hledger version. - It can be useful if the correct version of the hledger manual, or the - usual viewing tools, are not installed on your system. - - By default it uses the best viewer it can find in $PATH, in this order: - info, man, $PAGER (unless a topic is specified), less, or stdout. When - run non-interactively, it always uses stdout. Or you can select a par- - ticular viewer with the -i (info), -m (man), or -p (pager) flags. - - import - 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' trans- - actions 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 out- - put 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. - - 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 idem- - potent.) - - 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 sav- - ing a hidden ".latest" state file in the same directory. Eg when read- - ing finance/bank.csv, it will look for and update the finance/.lat- - est.bank.csv state file. The format is simple: one or more lines con- - taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- - cessed 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 cer- - tain date. - - Note deduplication (and updating of state files) can also be done by - print --new, but this is less often used. - - 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' - - 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.) - - Commodity display styles - Imported amounts will be formatted according to the canonical commodity - styles (declared or inferred) in the main journal file. - - incomestatement - 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. - - The revenue and expense accounts shown are those accounts declared with - the Revenue or Expense type, or otherwise all accounts under a top- - level revenue or income or expense account (case insensitive, plurals - allowed). - - 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 sup- - ports 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 (experi- - mental) json. - - notes - 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 transac- - tions. 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 - - payees - 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 - - prices - prices - Print market price directives from the journal. With --infer-market- - prices, generate additional market prices from transaction prices. - With --infer-reverse-prices, also generate market prices by inverting - transaction prices. Prices (and postings providing transaction prices) - can be filtered by a query. Price amounts are displayed with their - full precision. - - print - 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 deci- - mal places are shown, as in the original journal entry (with one alter- - ation: 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: - - o Valuation affects posting amounts but not balance assertion or bal- - ance assignment amounts, potentially causing those to fail. - - o Auto postings can generate postings with too many missing amounts. - - o Account aliases can generate bad account names. - - Normally, the journal entry's explicit or implicit amount style is pre- - served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a transaction price is - implied but not written, it will not appear in the output. You can use - the -x/--explicit flag to make all amounts and transaction prices - 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 transaction prices are converted to cost - using that price. This can be used for troubleshooting. - - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is - no similar-enough match, no transaction will be shown. - - With --new, hledger prints only transactions it has not seen on a pre- - vious run. This uses the same deduplication system as the import com- - mand. (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","","","" - - o There is one CSV record per posting, with the parent transaction's - fields repeated. - - o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different - order, etc.) - - o The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - - o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or - greater amounts under debit.) - - print-unique - print-unique - Print transactions which do not reuse an already-seen description. - - Example: - - $ cat unique.journal - 1/1 test - (acct:one) 1 - 2/2 test - (acct:two) 2 - $ LEDGER_FILE=unique.journal hledger print-unique - (-f option not supported) - 2015/01/01 test - (acct:one) 1 - - register - register, reg - 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 num- - bers. 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. - - 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. - - register-match - register-match - Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger- - autosync detect already-seen transactions when importing. - - rewrite - rewrite - Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print - --auto. - - This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds - one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- - tion's first posting amount. - - Examples: - - $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' - $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' - $ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - - = ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the - two spaces between account and amount. - - More: - - $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... - $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' - $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' - $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can - use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount - includes a commodity name, the new posting amount will be in the new - commodity; otherwise, it will be in the matched posting amount's com- - modity. - - Re-write rules in a file - During the run this tool will execute so called "Automated Transac- - tions" found in any journal it process. I.e instead of specifying this - operations in command line you can put them in a journal file. - - $ rewrite-rules.journal - - Make contents look like this: - - = ^income - (liabilities:tax) *.33 - - = expenses:gifts - budget:gifts *-1 - assets:budget *1 - - Note that '=' (equality symbol) that is used instead of date in trans- - actions you usually write. It indicates the query by which you want to - match the posting to add new ones. - - $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal - - This is something similar to the commands pipeline: - - $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ - | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ - --add-posting 'assets:budget *1' \ - > rewritten-tidy-output.journal - - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- - ings. - - Diff output format - To use this tool for batch modification of your journal files you may - find useful output in form of unified diff. - - $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' - - Output might look like: - - --- /tmp/examples/sample.journal - +++ /tmp/examples/sample.journal - @@ -18,3 +18,4 @@ - 2008/01/01 income - - assets:bank:checking $1 - + assets:bank:checking $1 - income:salary - + (liabilities:tax) 0 - @@ -22,3 +23,4 @@ - 2008/06/01 gift - - assets:bank:checking $1 - + assets:bank:checking $1 - income:gifts - + (liabilities:tax) 0 - - If you'll pass this through patch tool you'll get transactions contain- - ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via - --file options and include directives inside of these files. - - Be careful. Whole transaction being re-formatted in a style of output - from hledger print. - - See also: - - https://github.com/simonmichael/hledger/issues/99 - - rewrite vs. print --auto - This command predates print --auto, and currently does much the same - thing, but with these differences: - - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect - only child files. - - o rewrite's query limits which transactions can be rewritten; all are - printed. print --auto's query limits which transactions are printed. - - o rewrite applies rules specified on command line or in the journal. - print --auto applies rules specified in the journal. - - roi - roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return - on your investments. - - 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: - - o 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. - - o Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or con- - verges too slowly. - - Examples: - - o Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/invest- - ing/roi-unrealised.ledger - - o Cookbook > Return on Investment: https://hledger.org/roi.html - - 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'" - - 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. - - o "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 - - o "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 - - IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- - tial value, expressed in percentage of the initial value. - - However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of - growth is fixed over time. For more complex scenarios you need differ- - ent 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 percent- - age of your initial investment, and if you are adding to your invest- - ment, 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 "unreal- - ized 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: - - o Explanation of rate of return - - o Explanation of IRR - - o Explanation of TWR - - o Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - stats - 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 also supports output destination and output format selec- - tion. - - tags - tags - List the tags used in the journal, or their values. - - This command lists the tag names used in the journal, whether on trans- - actions, postings, or account declarations. - - With a TAGREGEX argument, only tag names matching this regular expres- - sion (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. - - test - 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). - - About add-on commands - Add-on commands are programs or scripts in your PATH - - o whose name starts with hledger- - - o whose name ends with a recognised file extension: .bat,.com,.exe, - .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none - - o and (on unix, mac) which are executable by the current user. - - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger library - functions that built-in commands use for command-line options, parsing - and reporting. Some experimental/example add-on scripts can be found - in the hledger repo's bin/ directory. - - 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 - -JOURNAL FORMAT - hledger's default file format, representing a General Journal. - - hledger's usual data source is a plain text file containing journal - entries in hledger journal format. This file represents a standard - accounting general journal. I use file names ending in .journal, but - that's not required. The journal file contains a number of transaction - entries, each describing a transfer of money (or any commodity) between - two or more named accounts, in a simple format readable by both hledger - and humans. - - hledger's journal format is a compatible subset, mostly, of ledger's - journal format, so hledger can work with compatible ledger journal - files as well. It's safe, and encouraged, to run both hledger and - ledger on the same journal file, eg to validate the results you're get- - ting. - - You can use hledger without learning any more about this file; just use - the add or web 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 configura- - tion at hledger.org for the full list. - - Here's a description of each part of the file format (and hledger's - data model). These are mostly in the order you'll use them, but in - some cases related concepts have been grouped together for easy refer- - ence, or linked before they are introduced, so feel free to skip over - anything that looks unnecessary right now. - - 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 sim- - ple date in column 0. This can be followed by any of the following - optional fields, separated by spaces: - - o a status character (empty, !, or *) - - o a code (any short number or text, enclosed in parentheses) - - o a description (any remaining text until end of line or a semicolon) - - o a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - - o 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 - - Dates - 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 cur- - rent transaction, the default year set with a default year 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.) - - Secondary dates - Real-life transactions sometimes involve more than one date - eg the - date you write a cheque, and the date it clears in your bank. When you - want to model this, for more accurate daily balances, you can specify - individual posting dates. - - Or, you can use the older secondary date feature (Ledger calls it aux- - iliary date or effective date). Note: we support this for compatibil- - ity, but I usually recommend avoiding this feature; posting dates are - almost always clearer and simpler. - - 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", as shown here: - - 2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking - - $ hledger register checking - 2010-02-23 movie ticket assets:checking $-10 $-10 - - $ hledger register checking --date2 - 2010-02-19 movie ticket assets:checking $-10 $-10 - - Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) - like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May - reports, and the deduction from checking should be reported on 6/1 for - easy bank reconciliation: - - 2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - - $ hledger -f t.j register food - 2015-05-30 expenses:food $10 $10 - - $ hledger -f t.j register checking - 2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. You can set the secondary date - similarly, with date2:DATE2. The date: or date2: tags must have a - valid simple date value if they are present, eg a date: tag with no - value is not allowed. - - Ledger's earlier, more compact bracketed date syntax is also supported: - [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any - square-bracketed sequence of the 0123456789/-.= characters in this way. - With this syntax, DATE infers its year from the transaction and DATE2 - infers its year from DATE. - - Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction - description or posting account name, separated from it by a space, - indicating one of three statuses: - - - mark status - ------------------ - unmarked - ! pending - * cleared - - When reporting, you can filter by status with the -U/--unmarked, - -P/--pending, and -C/--cleared flags; or the status:, status:!, and - status:* queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" state - is called "uncleared". As of hledger 1.3 we have renamed it to - unmarked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching pend- - ing, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with - real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle - transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to you. - Here's one suggestion: - - - status meaning - -------------------------------------------------------------------------- - uncleared recorded but not yet reconciled; needs review - pending tentatively reconciled (if needed, eg during a big reconcil- - iation) - cleared complete, reconciled as far as possible, and considered cor- - rect - - With this scheme, you would use -PC to see the current balance at your - bank, -U to see things which will probably hit your bank soon (like - uncashed checks), and no flags to see the most up-to-date state of your - finances. - - 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. - - Description - A transaction's description is the rest of the line following the date - and status mark (or until a comment begins). Sometimes called the - "narration" in traditional bookkeeping, it can be used for whatever you - wish, or left blank. Transaction descriptions can be queried, unlike - comments. - - Payee and note - You can optionally include a | (pipe) character in descriptions to sub- - divide 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. - - Comments - Lines in the journal beginning with a semicolon (;) or hash (#) or star - (*) are comments, and will be ignored. (Star comments cause org-mode - nodes to be ignored, allowing emacs users to fold and navigate their - journals with org-mode or orgstruct-mode.) - - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. - Transaction and posting comments must begin with a semicolon (;). - - Some examples: - - # a file comment - ; another file comment - * also a file comment, useful in org/orgstruct mode - - comment - A multiline file comment, which continues - until a line containing just "end comment" - (or end of file). - end comment - - 2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 - ; a file comment (because not indented) - - You can also comment larger regions of a file using comment and end - comment directives. - - Tags - Tags are a way to add extra labels or labelled data to postings and - transactions, which you can then search or pivot on. - - A simple tag is a word (which may contain hyphens) followed by a full - colon, written inside a transaction or posting comment line: - - 2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the - next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or new- - lines. Ending at commas means you can write multiple short tags on one - line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - o "a comment containing" is just comment text, not a tag - - o "tag1" is a tag with no value - - o "tag2" is another tag, whose value is "some value ..." - - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, third- - tag) and the posting has four (those plus posting-tag): - - 1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values - are simple strings. - - Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or - tab (2 or 4 spaces is common), followed by: - - o (optional) a status character (empty, !, or *), followed by a space - - o (required) an account name (any text, optionally containing single - spaces, until end of line or a double space) - - o (optional) two or more spaces or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are - being removed. - - The amounts within a transaction must always sum up to zero. As a con- - venience, one amount may be left blank; it will be inferred so as to - balance the transaction. - - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing spa- - ces. But if you accidentally leave only one space (or tab) before the - amount, the amount will be considered part of the account name. - - Virtual postings - A posting with a parenthesised 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 accounting, 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: - - 1/1 opening balances - (assets:checking) $1000 - (assets:savings) $2000 - - A posting with a bracketed 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: - - 1/1 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- not required to balance - - Ordinary non-parenthesised, non-bracketed postings are called real - postings. You can exclude virtual postings from reports with the - -R/--real flag or real:1 query. - - Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five top- - level accounts: assets, liabilities, revenue, expenses, and equity. - - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more - spaces (or newline). - - Account names can be aliased. - - Amounts - After the account name, there is usually an amount. (Important: - between account name and amount, there must be two or more spaces.) - - hledger's amount format is flexible, supporting several international - formats. Here are some examples. Amounts have a number (the "quan- - tity"): - - 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 com- - modity 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 - - 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 jour- - nal 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 detail below. - - 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 punctu- - ation), 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.) - - 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, in JOURNAL FORMAT -> Declaring commodities. - 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 - - - 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: - - o The commodity directive for that commodity (including the no-symbol - commodity), if any. - - o The amounts in that commodity seen in the journal's transactions. - (Posting amounts only; prices and periodic or auto rules are ignored, - currently.) - - o The built-in fallback style, which looks like this: $1000.00. (Sym- - bol on the left, period decimal mark, two decimal places.) - - A style is inferred from journal amounts as follows: - - o Use the general style (decimal mark, symbol placement) of the first - amount - - o Use the first-seen digit group style (digit group mark, digit group - sizes), if any - - o Use the maximum number of decimal places of all. - - Transaction price amounts don't affect the commodity display style - directly, but occasionally they can do so indirectly (eg when a post- - ing's amount is inferred using a transaction price). 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. - - 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"). (Guaranteed since hledger 1.17.1; in older versions - this could vary if hledger was built with Decimal < 0.5.1.) - - Transaction prices - Within a transaction, you can note an amount's price in another commod- - ity. This can be used to document the cost (in a purchase) or selling - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are - fixed at the time of the transaction, and do not change over time. See - also market prices, which represent prevailing exchange rates on a cer- - tain date. - - There are several ways to record a transaction price: - - 1. Write the price per unit, as @ UNITPRICE after the amount: - - 2009/1/1 - assets:euros EUR100 @ $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 EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, and - let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros EUR100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati- - bility with Ledger journals (Virtual posting costs), and is equiva- - lent to 1 in hledger. - - 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger, - this is equivalent to 2. - - Use the -B/--cost flag to convert amounts to their transaction price's - commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). - Eg here is how -B affects the balance report for the example above: - - $ hledger bal -N --flat - $-135 assets:dollars - EUR100 assets:euros - $ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last - amount. So if example 3's postings are reversed, while the transaction - is equivalent, -B shows something different: - - 2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros EUR100 ; for 100 euros - - $ hledger bal -N --flat -B - EUR-100 assets:dollars # <- the dollars' selling price - EUR100 assets:euros - - Lot prices, lot dates - Ledger allows another kind of price, lot price (four variants: {UNIT- - PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), - and/or a lot date ([DATE]) to be specified. These are normally used to - select a lot when selling investments. hledger will parse these, for - compatibility with Ledger journals, but currently ignores them. A - transaction price, lot price and/or lot date may appear in any order, - after the posting amount and before the balance assertion if any. - - 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 pro- - tect 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, below). - - Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- - ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- - ings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder 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. - - 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. - - 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 bal- - ance from earlier files. This can be useful when you do not want prob- - lems 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. - - 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 1EUR - b $-1 - c -1EUR - - 2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1EUR - b 0 == $-1 - c 0 == -1EUR - - 2013/1/3 ; This assertion fails as 'a' also contains 1EUR - 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 1EUR - b - - 2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1EUR - - Assertions and prices - Balance assertions ignore transaction prices, and should normally be - written without one: - - 2019/1/1 - (a) $1 @ EUR1 = $1 - - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- - ments do use them (see below). - - Assertions and subaccounts - 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 - - 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. - - 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: - - o assert the balance calculated with --auto, and always use --auto with - that file - - o or assert the balance calculated without --auto, and never use --auto - with that file - - o or avoid balance assertions on accounts affected by auto postings (or - avoid auto postings entirely). - - Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- - tions. Balance assertion failure messages show exact amounts. - - Balance assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when - setting opening balances: - - ; starting a new journal, set asset account balances - 2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - - ; no cash left; update balance, record any untracked spending as a generic expense - 2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- - ment). Note that using balance assignments makes your journal a little - less explicit; to know the exact amount posted, you have to run hledger - or do the calculations yourself, instead of just reading it. - - Balance assignments and prices - A transaction price in a balance assignment will cause the calculated - amount to have that price attached: - - 2019/1/1 - (a) = $1 @ EUR2 - - $ hledger print --explicit - 2019-01-01 - (a) $1 @ EUR2 = $1 @ EUR2 - - 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: - - o subdirective - Some directives support subdirectives, written - indented below the parent directive. - - o decimal mark - The character to interpret as a decimal mark (period - or comma) when parsing amounts of a commodity. - - o display style - How to display amounts of a commodity in output: sym- - bol side and spacing, digit groups, decimal mark, and number of deci- - mal places. - - Directives are not required when starting out with hledger, but you - will probably add some as your needs grow. Here is an overview of - directives by purpose: - - - purpose directives command line - options with sim- - ilar effect - ----------------------------------------------------------------------------- - READING/GENERATING DATA: - Declare a commodity's or file's commodity, D, decimal- - decimal mark to help parse mark - amounts accurately - Apply changes to the data while alias, apply account, --alias - parsing comment, D, Y - Inline extra data files include multiple - -f/--file's - Generate extra transactions or ~ - budget goals - Generate extra postings = - CHECKING FOR ERRORS: - Define valid entities to allow account, commodity, - stricter error checking payee - DISPLAYING REPORTS: - Declare accounts' display order account - and accounting type - Declare commodity display commodity, D -c/--commodity- - styles style - - And here are all the directives and their precise effects: - - - direc- effects ends - tive at - file - end? - ---------------------------------------------------------------------------------- - account Declares an account, for checking all entries in all files; - and its display order and type, for reports. Subdirectives: - any text, ignored. - alias Rewrites account names, in following entries until end of Y - current file or end aliases. - apply Prepends a common parent account to all account names, in Y - account following entries until end of current file or end apply - account. - comment Ignores part of the journal file, until end of current file Y - or end comment. - commod- Declares a commodity, for checking all entries in all files; N, Y - ity the decimal mark for parsing amounts of this commodity, for - following entries until end of current file; and its display - style, for reports. Takes precedence over D. Subdirectives: - format (alternate syntax). - - - - - D Sets a default commodity to use for no-symbol amounts, and Y - its decimal mark for parsing amounts of this commodity in - following entries until end of current file; and its display - style, for reports. - deci- Declares the decimal mark, for parsing amounts of all com- Y - mal- modities in following entries until next decimal-mark or end - mark of current file. Included files can override. Takes prece- - dence over commodity and D. - include Includes entries and directives from another file, as if they - were written inline. - payee Declares a payee name, for checking all entries in all files. - P Declares a market price for a commodity on some date, for - valuation reports. - Y Declares a year for yearless dates, for following entries Y - until end of current file. - ~ Declares a periodic transaction rule that generates future - (tilde) transactions with --forecast and budget goals with balance - --budget. - = Declares an auto posting rule that generates extra postings partly - (equals) on matched transactions with --auto, in current, parent, and - child files (but not sibling files, see #1212). - - 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 sta- - ble 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 direc- - tives do not affect parent or sibling files (see below). - - Comment blocks - A line containing just comment starts a commented region of the file, - and a line containing just end comment (or the end of the current file) - ends it. See also comments. - - Including other files - You can pull in the content of additional files by writing an include - 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, overrid- - ing the file extension (as described in hledger.1 -> Input files): - include timedot:~/notes/2020*.md. - - Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. - Eg: - - Y2009 ; set default year to 2009 - - 12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - - Y2010 ; change default year to 2010 - - 2009/1/30 ; specifies the year, not affected - expenses 1 - assets - - 1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Declaring payees - The payee 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 - - Declaring the decimal mark - 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). - - Declaring commodities - 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 Com- - modity 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 dec- - imal 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 subdirec- - tive, 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 - - 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. - - 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 cur- - rently 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. - - Default commodity - The D directive sets a default commodity, to be used for any subsequent - commodityless amounts (ie, plain numbers) seen while parsing the jour- - nal. 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). - - The syntax is D AMOUNT. As with commodity, 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 - - If both commodity and D directives are found for a commodity, commodity - takes precedence for setting decimal mark and display style. - - If you are using D and also checking commodities, you will need to add - a commodity directive similar to the D. (The hledger check commodities - command expects commodity directives, and ignores D). - - Declaring market prices - The P directive declares a market price, which is an exchange rate - between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, - cryptocurrency exchange, or the 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 EUR $1.35 - - # and $1.40 from 2010-01-01 onward: - P 2010-01-01 EUR $1.40 - - The -V, -X and --value flags use these market prices to show amount - values in another commodity. See Valuation. - - Declaring accounts - account directives can be used to declare accounts (ie, the places that - amounts are transferred from and to). Though not required, these dec- - larations can provide several benefits: - - o They can document your intended chart of accounts, providing a refer- - ence. - - o They control account display order in reports, allowing non-alpha- - betic sorting (eg Revenues to appear above Expenses). - - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and - incomestatement. - - o They can store other account information, as comments or as tags - which can be used to filter reports. - - o They help with account name completion (in hledger add, hledger-web, - hledger-iadd, ledger-mode, etc.) - - o In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - - The simplest form is just the word account followed by a hledger-style - account name, eg this account directive declares the assets:bank:check- - ing account: - - account assets:bank:checking - - Account error checking - By default, accounts come into existence when a transaction references - them by name. 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 - the error later, as an extra account in balance reports, or an incor- - rect 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: - - o The declaration is case-sensitive; transactions must use the correct - account name capitalisation. - - o The account directive's scope is "whole file and below" (see direc- - tives). 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. - - o Accounts can only be declared in journal files (but will affect - included files in other formats). - - o It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - Account comments - Comments, beginning with a semicolon, can be added: - - o on the same line, after two or more spaces (because ; is allowed in - account names) - - o on the next lines, indented - - An example of both: - - account assets:bank:checking ; same-line comment, note 2+ spaces required before ; - ; next-line comment - ; some tags, type:A, acctnum:12345 - - Compatibility note: same-line comments are not supported by Ledger or - hledger <1.13. - - Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just - for compatibility.: - - account assets:bank:checking - format blah blah ; <- subdirective, ignored - - Here is the full syntax of account directives: - - account ACCTNAME [;type:ACCTTYPE] [COMMENT] - [;COMMENTS] - [LEDGER-STYLE SUBDIRECTIVES, IGNORED] - - 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: - - o A or Asset (things you own) - - o L or Liability (things you owe) - - o E or Equity (investment/ownership; balanced counterpart of assets & - liabilities) - - o R or Revenue (what you received money from, AKA income; technically - part of Equity) - - o X or Expense (what you spend money on; technically part of Equity) - - or, it can be (these are used less often): - - o C or Cash (a subtype of Asset, indicating liquid assets for the cash- - flow report) - - o V or Conversion (a subtype of Equity, for conversions (see CONVERSION - & COST).) - - 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. - - o 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. Note the Cash regexp changed - in hledger 1.24.99.2. - - 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 - - o If you declare any account types, it's a good idea to declare an - account for each of them, because a mixture of declared and name- - inferred types can disrupt certain reports. - - o Certain uses of account aliases can disrupt account types. See - Rewriting accounts > Aliases and account types. - - o 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. - - o For troubleshooting, you can list accounts and their types with: - - $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] - - Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web - sidebar. By default accounts are listed in alphabetical order. But if - you have these account directives in the journal: - - account assets - account liabilities - account equity - account revenues - account expenses - - you'll see those accounts displayed in declaration order, not alphabet- - ically: - - $ hledger accounts -1 - assets - liabilities - equity - revenues - expenses - - Undeclared accounts, if any, are displayed last, in alphabetical order. - - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, - 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: - - o you will sometimes declare parent accounts (eg account other above) - that you don't intend to post to, just to customize their display - order - - o sibling accounts stay together (you couldn't display x:y in between - a:b and a:c). - - Rewriting accounts - You can define account alias rules which rewrite your account names, or - parts of them, before generating reports. This can be useful for: - - o expanding shorthand account names to their full form, allowing easier - data entry and a less verbose journal - - o adapting old journals to your current chart of accounts - - o experimenting with new account organisations, like a new hierarchy - - o combining two accounts into one, eg to see their sum or difference on - one line - - o 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 cor- - rectly, but you can also generate invalid account names with them; more - on this below. - - See also Rewrite account names. - - Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its - included files (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. Sub- - accounts are also affected. Eg: - - alias checking = assets:bank:wells fargo:checking - ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - Regex aliases - There is also a more powerful variant that uses a regular expression, - 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. - - 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: - - o the nearest alias declaration before/above the entry is applied first - - o the next alias before/above that will be be applied next, and so on - - o aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- - pendent 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. - - 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 - - end aliases - You can clear (forget) all currently defined aliases (seen in the jour- - nal so far, or defined on the command line) with this directive: - - end aliases - - 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 exam- - ple, 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 - - 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, renam- - ing 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 - - Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and - end apply account directives like so: - - apply account home - - 2010/1/1 - food $10 - cash - - end apply account - - which is equivalent to: - - 2010/01/01 - home:food $10 - home:cash $-10 - - If end apply account is omitted, the effect lasts to the end of the - file. Included files are also affected, eg: - - apply account business - include biz.journal - end apply account - apply account personal - include personal.journal - - Prior to hledger 1.0, legacy account and end spellings were also sup- - ported. - - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent - account. - - Periodic transactions - Periodic transaction rules describe transactions that recur. They - allow hledger to generate temporary future transactions to help with - forecasting, so you don't have to write out each one in the journal, - and it's easy to try out different forecasts. - - 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-fore- - casted 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. - - Periodic transaction rules also have a second meaning: they are used to - define budget goals, shown in budget reports. - - 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.): - - ~ monthly - expenses:rent $2000 - assets:bank:checking - - There is an additional constraint on the period expression: the start - date must fall on a natural boundary of the interval. Eg monthly from - 2018/1/1 is valid, but monthly from 2018/1/15 is not. - - 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. - - 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 acciden- - tally 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, - - o Do write two spaces between your period expression and your transac- - tion description, if any. - - o Don't accidentally write two spaces in the middle of your period - expression. - - Forecasting with periodic transactions - The --forecast flag activates any periodic transaction rules in the - journal. These will generate temporary additional transactions, usu- - ally 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-transac- - tion:, which you can use to reliably match transactions generated "just - now" (rather than printed 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: - - o the start date provided within --forecast's argument, if any - - o otherwise, the later of - - o the report start date, if specified (with -b/-p/date:) - - o the day after the latest ordinary transaction in the journal, if - any - - o otherwise today. - - It ends on: - - o the end date provided within --forecast's argument, if any - - o otherwise, the report end date, if specified (with -e/-p/date:) - - o 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: - - o 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. - - o 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: - - o You must use = between flag and argument; a space won't work. - - o The period expression can specify the forecast period's start date, - end date, or both. See also Report start & end date. - - o The period expression should not specify a report interval. (Each - periodic transaction rule specifies its own interval.) - - Some examples: --forecast=202001-202004, --forecast=jan-, --fore- - cast=2021. - - Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- - pared in budget reports. - - See also: Budgeting and Forecasting. - - - Auto postings - "Automated postings" or "auto postings" are extra postings which get - added automatically to transactions which match certain queries, - defined by "auto posting rules", when you use the --auto flag. - - 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 match- - ing), followed by a query (which matches existing postings), and each - "posting" line describes a posting to be generated, and the posting - amounts can be: - - o a normal amount with a commodity symbol, eg $2. This will be used - as-is. - - o a number, eg 2. The commodity symbol (if any) from the matched post- - ing will be added to this. - - o 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. - - o 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 - - 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). - - 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. - - Auto postings and transaction balancing / inferred amounts / balance asser- - tions - Currently, auto postings are added: - - o after missing amounts are inferred, and transactions are checked for - balancedness, - - o but before balance assertions are checked. - - Note this means that journal entries must be balanced both before and - after auto postings are added. This changed in hledger 1.12+; see #893 - for background. - - 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. - - Auto posting tags - Automated postings will have some extra tags: - - o generated-posting:= QUERY - shows this was generated by an auto post- - ing rule, and the query - - o _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: - - o modified: - this transaction was modified - - o _modified: - a hidden tag not appearing in the comment; this transac- - tion was modified "just now". - -CSV FORMAT - How hledger reads CSV data, and the CSV rules file format. - - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records as if they were journal - files, automatically converting each CSV record into a transaction. - - (To learn about writing CSV, see CSV output.) - - We describe each CSV file's format with a corresponding rules file. By - default this is named like the CSV file with a .rules extension added. - Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the - same directory as FILE.csv. You can specify a different rules file - with the --rules-file option. If a rules file is not found, hledger - will create a sample rules file, which you'll need to adjust. - - This file contains rules describing the CSV data (header line, fields - layout, date format etc.), and how to construct hledger journal entries - (transactions) from it. Often there will also be a list of conditional - rules for categorising transactions based on their descriptions. - Here's an overview of the CSV rules; these are described more fully - below, after the examples: - - - skip skip one or more header lines or matched CSV - records - fields list name CSV fields, assign them to hledger - fields - field assignment assign a value to one hledger field, with - interpolation - Field names hledger field names, used in the fields list - and field assignments - separator a custom field separator - if block apply some rules to CSV records matched by - patterns - if table apply some rules to CSV records matched by - patterns, alternate syntax - end skip the remaining CSV records - date-format how to parse dates in CSV records - decimal-mark the decimal mark used in CSV amounts, if - ambiguous - newest-first disambiguate record order when there's only - one date - include inline another CSV rules file - balance-type choose which type of balance assignments to - use - - Note, for best error messages when reading CSV files, use a .csv, .tsv - or .ssv file extension or file prefix - see File Extension below. - - There's an introductory Convert CSV files tutorial on hledger.org. - - Examples - Here are some sample hledger CSV rules files. See also the full col- - lection at: - https://github.com/simonmichael/hledger/tree/master/examples/csv - - Basic - 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 - - Default account names are chosen, since we didn't set them. - - 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 neces- - sary 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 read- - ing directly from CSV, but they will be checked if these entries are - imported into a journal file. - - Amazon - Here we convert amazon.com order history, and use an if block to gener- - ate 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 - - 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: - - CSV rules - The following kinds of rule can appear in the rules file, in any order. - Blank lines and lines beginning with # or ; are ignored. - - skip - skip N - - The word "skip" followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines preceding the CSV data. - (Empty/blank lines are skipped automatically.) You'll need this when- - ever your CSV data contains header lines. - - It also has a second purpose: it can be used inside if blocks to ignore - certain CSV records (described below). - - fields list - fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word "fields" followed by comma-separated field - names) is the quick way to assign CSV field values to hledger fields. - (The other way is field assignments, see below.) A fields list does - does two things: - - 1. It names the CSV fields. This is optional, but can be convenient - later for interpolating them. - - 2. Whenever you use a standard hledger field name (defined below), the - CSV value is assigned to that part of the hledger 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 - - Tips: - - o The fields list always use commas, even if your CSV data uses another - separator character. - - o Currently there must be least two items in the list (at least one - comma). - - o Field names may not contain spaces. Spaces before/after field names - are optional. - - o Field names may contain _ (underscore) or - (hyphen). - - o If the CSV contains column headings, it's a good idea to use these, - suitably modified, as the basis for your field names (eg lower-cased, - with underscores instead of spaces). - - o If some heading names match standard hledger fields, but you don't - want to set the hledger fields directly, alter those names, eg by - appending an underscore. - - o Fields you don't care about can be given a dummy name (eg: _ ), or no - name. - - field assignment - HLEDGERFIELDNAME 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 inter- - polate CSV fields, referenced by their 1-based position in the CSV - record (%N), or by the name they were given in the fields list (%CSV- - FIELDNAME). - - 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: - - o Interpolation strips outer whitespace (so a CSV value like " 1 " - becomes 1 when interpolated) (#1051). - - o Interpolations always refer to a CSV field - you can't interpolate a - hledger field. (See Referencing other fields below). - - Field names - Here are the standard hledger field (and pseudo-field) names, which you - can use in a fields list and in field assignments. For more about the - transaction parts they refer to, see Transactions. - - date field - Assigning to date sets the transaction date. - - date2 field - date2 sets the transaction's secondary date, if any. - - status field - status sets the transaction's status, if any. - - code field - code sets the transaction's code, if any. - - description field - description sets the transaction's description, if any. - - comment field - comment sets the transaction's comment, if any. - - commentN, where N is a number, sets the Nth posting's comment. - - Tips: - - o You can assign multi-line comments by writing literal \n in the code. - A comment starting with \n will begin on a new line. - - o Comments can contain tags, as usual. - - 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, and in conditional blocks. - - 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"). - - amount field - 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. - - amountN-in and amountN-out can be used instead, if the CSV uses sepa- - rate fields for debits and credits (inflows and outflows). hledger - assumes both of these CSV fields are unsigned, and will automatically - negate the "-out" value. If they are signed, see "Setting amounts" - below. - - amount, or amount-in and amount-out are a legacy mode, to keep pre- - hledger-1.17 CSV rules files working (and for occasional convenience). - They are suitable only for two-posting transactions; they set both - posting 1's and posting 2's amount. Posting 2's amount will be - negated, and also converted to cost if there's a transaction price. - - If you have an existing rules file using the unnumbered form, you might - want to use the numbered form in certain conditional blocks, without - having to update and retest all the old rules. To facilitate this, - posting 1 ignores amount/amount-in/amount-out if any of - amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them - if any of amount2/amount2-in/amount2-out are assigned, avoiding con- - flicts. - - 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. - - 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. - - separator - You can use the separator rule to read other kinds of character-sepa- - rated 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 automat- - ically, and you won't need this rule. - - if block - if MATCHER - RULE - - if - MATCHER - MATCHER - MATCHER - RULE - RULE - - Conditional blocks ("if blocks") are a block of rules that are applied - only to CSV records which match certain patterns. They are often used - for customising account names based on transaction descriptions. - - Matching the whole record - Each MATCHER can be a record matcher, which looks like this: - - REGEX - - REGEX is a case-insensitive regular expression that tries to match any- - where within the CSV record. It is a POSIX ERE (extended regular - expression) that also supports GNU word boundaries (\b, \B, \<, \>), - and nothing else. If you have trouble, be sure to check our doc: - https://hledger.org/hledger.html#regular-expressions - - Important note: the record that is matched is not the original record, - but a synthetic one, with any enclosing double quotes (but not enclos- - ing whitespace) removed, and always comma-separated (which means that a - field containing a comma will appear like two fields). Eg, if the - original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will - actually see 2020-01-01,Acme, Inc., 1,000). - - Matching individual fields - Or, MATCHER can be a field matcher, like this: - - %CSVFIELD REGEX - - which matches just the content of a particular CSV field. CSVFIELD is - a percent sign followed by the field's name or column number, like - %date or %1. - - Combining matchers - A single matcher can be written on the same line as the "if"; or multi- - ple matchers can be written on the following lines, non-indented. Mul- - tiple matchers are OR'd (any one of them can match), unless one begins - with an & symbol, in which case it is AND'ed with the previous matcher. - - if - MATCHER - & MATCHER - RULE - - Rules applied on successful match - After the patterns there should be one or more rules to apply, all - indented by at least one space. Three kinds of rule are allowed in - conditional blocks: - - o field assignments (to set a hledger field) - - o skip (to skip the matched CSV record) - - o end (to skip all remaining CSV records). - - Examples: - - # if the CSV record contains "groceries", set account2 to "expenses:groceries" - if groceries - account2 expenses:groceries - - # if the CSV record contains any of these patterns, set account2 and comment as shown - if - monthly service fee - atm transaction fee - banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - if table - if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn - MATCHER1,VALUE11,VALUE12,...,VALUE1n - MATCHER2,VALUE21,VALUE22,...,VALUE2n - MATCHER3,VALUE31,VALUE32,...,VALUE3n - - - Conditional tables ("if tables") are a different syntax to specify - field assignments that will be applied only to CSV records which match - certain patterns. - - MATCHER could be either field or record matcher, as described above. - When MATCHER matches, values from that row would be assigned to the CSV - fields named on the if line, in the same order. - - Therefore if table is exactly equivalent to a sequence of of if blocks: - - if MATCHER1 - CSVFIELDNAME1 VALUE11 - CSVFIELDNAME2 VALUE12 - ... - CSVFIELDNAMEn VALUE1n - - if MATCHER2 - CSVFIELDNAME1 VALUE21 - CSVFIELDNAME2 VALUE22 - ... - CSVFIELDNAMEn VALUE2n - - if MATCHER3 - CSVFIELDNAME1 VALUE31 - CSVFIELDNAME2 VALUE32 - ... - CSVFIELDNAMEn VALUE3n - - Each line starting with MATCHER should contain enough (possibly empty) - values for all the listed fields. - - Rules would be checked and applied in the order they are listed in the - table and, like with if blocks, later rules (in the same or another ta- - ble) or if blocks could override the effect of any rule. - - Instead of ',' you can use a variety of other non-alphanumeric charac- - ters as a separator. First character after if is taken to be the sepa- - rator for the rest of the table. It is the responsibility of the user - to ensure that separator does not occur inside MATCHERs and values - - there is no way to escape separator. - - 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 - - end - This rule can be used inside if blocks (only), to make hledger stop - reading this CSV file and move on to the next input file, or to command - execution. Eg: - - # ignore everything following the first empty record - if ,,,, - end - - 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 date - parsing pattern, which 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 - - For the supported strptime syntax, see: - https://hackage.haskell.org/package/time/docs/Data-Time-For- - mat.html#v:formatTime - - Note that although you can parse date-times which include a time zone, - that time zone is ignored; it will not change the date that is parsed. - This means when reading CSV data with times not in your local time - zone, dates can be "off by one". - - 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. - - newest-first - hledger always sorts the generated transactions by date. Transactions - on the same date should appear in the same order as their CSV records, - as hledger can usually auto-detect whether the CSV's normal order is - oldest first or newest first. But if all of the following are true: - - o the CSV might sometimes contain just one day of data (all records - having the same date) - - o the CSV records are normally in reverse chronological order (newest - at the top) - - o and you care about preserving the order of same-day transactions - - then, you should add the newest-first rule as a hint. Eg: - - # tell hledger explicitly that the CSV is normally newest first - newest-first - - 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 - - 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 - - Tips - 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. - - Valid CSV - hledger accepts CSV conforming to RFC 4180. When CSV values are - enclosed in quotes, note: - - o they must be double quotes (not single quotes) - - o spaces outside the quotes are not allowed - - File Extension - To help hledger identify the format and show the right error messages, - CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv - filename extension. Or, the file path should be prefixed with csv:, - ssv: or tsv:. Eg: - - $ hledger -f foo.ssv print - - or: - - $ cat foo | hledger -f ssv:- foo - - You can override the file extension with a separator rule if needed. - See also: Input files in the hledger manual. - - 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. - - Valid transactions - After reading a CSV file, hledger post-processes and validates the gen- - erated 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 - - 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: - - o https://hledger.org/cookbook.html#setups-and-workflows - - o https://plaintextaccounting.org -> data import/conversion - - Setting amounts - Some tips on using the amount-setting rules discussed above. - - Here are the ways to set a posting's amount: - - 1. If the CSV has a single amount field: - Assign (via a fields list or a field assignment) to amountN. This sets - the Nth posting's amount. N is usually 1 or 2 but can go up to 99. - - 2. If the CSV has separate amount fields for debit & credit (in & out): - - a. If both fields are unsigned: - Assign to amountN-in and amountN-out. This sets posting N's amount - to whichever of these has a non-zero value, and negates the "-out" - value. - - b. If either field is signed (can contain a minus sign): - Use a conditional rule to flip the sign (of non-empty values). - Since hledger always negates amountN-out, if it was already nega- - tive, we must undo that by negating once more (but only if the - field is non-empty): - - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. If both fields, or neither field, can contain a non-zero value: - hledger normally expects exactly one of the fields to have a non- - zero value. Eg, the amountN-in/amountN-out rules would reject - value pairs like these: - - "", "" - "0", "0" - "1", "none" - - So, use smarter conditional rules to set the amount from the appro- - priate field. Eg, these rules would make it use only the value - containing non-zero digits, handling the above: - - 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: - Assign to amount (or to amount-in and amount-out). (This is the legacy - numberless syntax, which sets amount1 and amount2 and converts amount2 - to cost.) - - 4. If the CSV has the balance instead of the transaction amount: - Assign to balanceN, which sets posting N's amount indirectly via a bal- - ance assignment. (Old syntax: balance, equivalent to balance1.) - - o If hledger guesses the wrong default account name: - When setting the amount via balance assertion, hledger may guess - the wrong default account name. So, set the account name explic- - itly, eg: - - fields date, description, balance1 - account1 assets:checking - - Amount signs - There is some special handling for amount signs, to simplify parsing - and sign-flipping: - - o If an amount value begins with a plus sign: - that will be removed: +AMT becomes AMT - - o If an amount value is parenthesised: - it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - - o 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 - - o If an amount value contains just a sign (or just a set of parenthe- - ses): - that is removed, making it an empty value. "+" or "-" or "()" becomes - "". - - 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. - - 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 deci- - mal 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). - - 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 lit- - eral "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 - - How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need - to). First, - - o 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: - - o skip (at top level) - - o date-format - - o newest-first - - o fields - names the CSV fields, optionally sets up initial assignments - to hledger fields - - Then for each CSV record in turn: - - o 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. - - o 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. - - o compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELDNAME references), or a - default - - o generate a synthetic hledger transaction 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. - -TIMECLOCK FORMAT - 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). - - i 2015/03/30 09:00:00 some:account name optional description after two spaces - o 2015/03/30 09:20:00 - i 2015/03/31 22:21:45 another account - o 2015/04/01 02:00:34 - - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For - the above time log, hledger print generates these journal entries: - - $ hledger -f t.timeclock print - 2015-03-30 * optional description after two spaces - (some:account name) 0.33h - - 2015-03-31 * 22:21-23:59 - (another account) 1.64h - - 2015-04-01 * 00:00-02:00 - (another account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - - $ hledger -f sample.timeclock balance # current time balances - $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 - $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - o use emacs and the built-in timeclock.el, or the extended timeclock- - x.el and perhaps the extras in ledgerutils.el - - o at the command line, use these bash aliases: shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" - - o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 - executable renamed. - -TIMEDOT FORMAT - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is - - o convenient for quick, approximate, and retroactive time logging - - o 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: - - o 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 - - o a common transaction description for this day - - o a common transaction comment for this day, after a semicolon (;). - - After the date line are zero or more optionally-indented time transac- - tion lines, consisting of: - - o an account name - any word or phrase, usually a hledger-style account - name. - - o two or more spaces - a field separator, required if there is an - amount (as in journal format). - - o a timedot amount - dots representing quarter hours, or a number rep- - resenting hours. - - o an optional comment beginning with semicolon. This is ignored. - - In more detail, timedot amounts can be: - - o dots: zero or more period characters, each representing one quarter- - hour. Spaces are ignored and can be used for grouping. Eg: .... .. - - o a number, representing hours. Eg: 1.5 - - o 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.: - - o Lines beginning with # or ;, and blank lines, are ignored. - - o Lines not ending with a double-space and amount are parsed as trans- - actions with zero amount. (Most hledger reports hide these by - default; add -E to see them.) - - o One or more stars (*) followed by a space, at the start of a line, is - ignored. So date lines or time transaction lines can also be Org- - mode headlines. - - o All Org-mode headlines before the first date line are ignored. - - 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. - -COMMON TASKS - Here are some quick examples of how to do some basic tasks with - hledger. For more details, see the reference section below, the - hledger_journal(5) manual, or the more extensive docs at - https://hledger.org. - - Getting help - $ hledger # show available commands - $ hledger --help # show common options - $ hledger CMD --help # show common and command options, and command help - $ hledger help # show available manuals/topics - $ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) - $ hledger help journal -m # show the journal topic, as a man page scrolled to that section - $ hledger help --help # show more detailed help for the help command - - Find more docs, chat, mail list, reddit, issue tracker: - https://hledger.org/support.html-feedback - - Constructing command lines - hledger has an extensive and powerful command line interface. We - strive to keep it simple and ergonomic, but you may run into one of the - confusing real world details described in OPTIONS, below. If that hap- - pens, here are some tips that may help: - - o command-specific options must go after the command (it's fine to put - all options there) (hledger CMD OPTS ARGS) - - o running add-on executables directly simplifies command line parsing - (hledger-ui OPTS ARGS) - - o enclose "problematic" args in single quotes - - o if needed, also add a backslash to hide regular expression metachar- - acters from the shell - - o to see how a misbehaving command is being parsed, add --debug=2. - - 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 () - - 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 bal- - ances on this date. Here are two ways to do it: - - o 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. - - o 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 - - 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 - - Reconciling - Periodically you should reconcile - compare your hledger-reported bal- - ances 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 dis- - crepancies. - - 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 check- - ing -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 trans- - action 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 --reg- - ister 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 com- - mit: - - $ git commit -m 'txns' 2020.journal - - 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 --flat -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 --flat -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 **** - - 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. - -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 file format - differences. - - On large data files, hledger is slower and uses more memory than - Ledger. - -TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug - tracker): - - Successfully installed, but "No command 'hledger' found" - stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, - that is ~/.local/bin and ~/.cabal/bin respectively. - - I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may - need to use export. Here's an explanation. - - Getting errors like "Illegal byte sequence" or "Invalid or incomplete - multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- - ment (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 sup- - ports 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 differ- - ence 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 - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2020 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), ledger(1) - - - -hledger-1.26 June 2022 HLEDGER(1) + manual is for hledger 1.26.1. + +SYNOPSIS + hledger + + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + +DESCRIPTION + hledger is a reliable, cross-platform set of programs for tracking + money, time, or any other commodity, using double-entry accounting and + a simple, editable file format. hledger is inspired by and largely + compatible with ledger(1). + + The basic function of the hledger CLI is to read a plain text file + describing financial transactions (in accounting terms, a general jour- + nal) and print useful reports on standard output, or export them as + CSV. hledger can also read some other file formats such as CSV files, + translating them to journal format. Additionally, hledger lists other + hledger-* executables found in the user's $PATH and can invoke them as + subcommands. + + hledger reads data from one or more files in hledger journal, time- + clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must + be a real environment variable, not a shell variable. You can specify + standard input with -f-. + + Transactions are dated movements of money between two (or more) named + accounts, and are recorded with journal entries like this: + + 2015/10/16 bought food + expenses:food $10 + assets:cash + + Most users use a text editor to edit the journal, usually with an edi- + tor mode such as ledger-mode for added convenience. hledger's interac- + tive add command is another way to record new transactions. hledger + never changes existing transactions. + + To get started, you can either save some entries like the above in + ~/.hledger.journal, or run hledger add and follow the prompts. Then + try some commands like hledger print or hledger balance. Run hledger + with no arguments for a list of commands. + +OPTIONS + General options + To see general usage help, including general options which are sup- + ported by most hledger commands, run hledger -h. + + General help options: + + -h --help + show general 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 fol- + lowing 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 com- + modities + + -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 charac- + ters. 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. + + 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. + + 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 noth- + ing). 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. + + Special characters + 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 dou- + ble 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. + + 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:\\$ + + 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 argu- + ments 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:\\$ + + 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: + + o an @argumentfile + + o hledger-ui's filter field + + o hledger-web's search form + + o GHCI's prompt (used by developers). + + Unicode characters + hledger is expected to handle non-ascii characters correctly: + + o 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.) + + o 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: + + o 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 Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- + grams). + + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode + + o the terminal must be using a font which includes the required unicode + glyphs + + o the terminal should be configured to display wide characters as dou- + ble width (for report alignment) + + o 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 stan- + dard 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). + + Regular expressions + hledger uses regular expressions in a number of places: + + o query terms, on the command line and in the hledger-web search form: + REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX + + o CSV rules conditional blocks: if REGEX ... + + o account alias directives and options: alias /REGEX/ = REPLACEMENT, + --alias /REGEX/=REPLACEMENT + + hledger's regular expressions come from the regex-tdfa library. 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: + + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + these are not required. + + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write cur:\$. + + o On the command line, some metacharacters like $ have a special mean- + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. + +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\MyUser- + Name\.hledger.journal. You can change this by running a command like + this in a powershell window: + + > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" + + (Let us know if you need to be an Administrator, and if this persists + across a reboot.) + + 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. + +DATA FILES + hledger reads transactions from one or more data files. The default + data file is $HOME/.hledger.journal (or on Windows, something like + C:/Users/USER/.hledger.journal). + + You can override this with the $LEDGER_FILE environment variable: + + $ setenv LEDGER_FILE ~/finance/2016.journal + $ hledger stats + + or with 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- + + 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 exten- + sions: + ----------------------------------------------------------------------------- + journal hledger journal files and some Ledger .journal .j .hledger + journals, for transactions .ledger + time- timeclock files, for precise time log- .timeclock + clock ging + 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 their own sections, 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:- + + Multiple files + You can specify multiple -f options, to read multiple files as one big + journal. There are some limitations with this: + + o most directives do not affect sibling files + + o balance assertions will not see any account balances from previous + files + + If you need either of those things, you can + + o use a single parent file which includes the others + + o or concatenate the files into one before reading, eg: cat a.journal + b.journal | hledger -f- CMD. + + Strict mode + hledger checks input files for valid data. By default, the most impor- + tant errors are detected, while still accepting easy journal files + without a lot of declarations: + + o Are the input files parseable, with valid syntax ? + + o Are all transactions balanced ? + + o Do all balance assertions pass ? + + With the -s/--strict flag, additional checks are performed: + + o Are all accounts posted to, declared with an account directive ? + (Account error checking) + + o Are all commodities declared with a commodity directive ? (Commodity + error checking) + + o Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks -- the ones + listed above and some more. + +TIME PERIODS + Smart dates + hledger's user interfaces accept a flexible "smart date" syntax. Smart + dates allow some english words, can be relative to today's date, and + can have less-significant date parts omitted (defaulting to 1). + + Examples: + + + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 + 2004 start of year + 2004/10 start of month + 10/1 month and day in current year + 21 day in current month + october, oct start of month in current year + yesterday, today, tomor- -1, 0, 1 days from today + row + last/this/next -1, 0, 1 periods from the current period + day/week/month/quar- + ter/year + in n n periods from the current period + days/weeks/months/quar- + ters/years + n n periods from the current period + days/weeks/months/quar- + ters/years ahead + n -n periods from the current period + days/weeks/months/quar- + ters/years ago + 20181201 8 digit YYYYMMDD with valid year month and day + 201812 6 digit YYYYMM with valid year and month + + Counterexamples - malformed digit sequences might give surprising + results: + + + 201813 6 digits with an invalid month is parsed as start of + 6-digit year + 20181301 8 digits with an invalid month is parsed as start of + 8-digit year + 20181232 8 digits with an invalid day gives an error + 201801012 9+ digits beginning with a valid YYYYMMDD gives an error + + Note "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; those are not affected by --today.) + + + Report start & end date + By default, most hledger reports will show the full span of time repre- + sented by the journal data. 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. + + Some notes: + + o End dates are exclusive, as in Ledger, so you should write the date + after the last day you want to see in the report. + + o As noted in reporting options: among start/end dates specified with + options, the last (i.e. right-most) option takes precedence. + + o 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. + + o A report interval (see below) will adjust start/end dates, when + needed, so that they fall on subperiod boundaries. + + Examples: + + + -b 2016/3/17 begin on St. Patrick's day 2016 + -e 12/1 end at the start of december 1st of the current year + (11/30 will be the last date included) + -b thismonth all transactions on or after the 1st of the current month + -p thismonth all transactions in the current month + date:2016/3/17.. the above written as queries instead (.. can also be + replaced with -) + date:..12/1 + date:thismonth.. + date:thismonth + + Report intervals + A report interval can be specified so that commands like register, bal- + ance and activity become multi-period, showing each subperiod as a sep- + arate row or column. + + The following "standard" report intervals can be enabled by using their + corresponding flag: + + o -D/--daily + + o -W/--weekly + + o -M/--monthly + + o -Q/--quarterly + + o -Y/--yearly + + These standard intervals always start on natural interval boundaries: + eg --weekly starts on mondays, --monthly starts on the first of the + month, --yearly always starts on January 1st, etc. + + Certain more complex intervals, and more flexible boundary dates, can + be specified by -p/--period. These are described in period expres- + sions, below. + + Report intervals can only be specified by the flags above, and not by + query arguments, currently. + + Report intervals have another effect: multi-period reports are always + expanded to fill a whole number of subperiods. So if you use a report + interval (other than --daily), and you have specified a start or end + date, you may notice those dates being overridden (ie, the report + starts earlier than your requested start date, or ends later than your + requested end date). This is done to ensure "full" first and last sub- + periods, so that all subperiods' numbers are comparable. + + To summarise: + + o In multiperiod reports, all subperiods are forced to be the same + length, to simplify reporting. + + o Reports with the standard --weekly/--monthly/--quarterly/--yearly + intervals are required to start on the first day of a + week/month/quarter/year. We'd like more flexibility here but it + isn't supported yet. + + o --period (below) can specify more complex intervals, starting on any + date. + + Period expressions + The -p/--period option accepts period expressions, a shorthand way of + expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as + exclusive: + + + -p "from 2009/1/1 to 2009/4/1" + + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as + ".." or "-". These are equivalent to the above: + + + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1..2009/4/1 + + Dates are smart dates, so if the current year is 2009, the above can + also be written as: + + + -p "1/1 4/1" + -p "january-apr" + -p "this year to 4/1" + + If you specify only one date, the missing start or end date will be the + earliest or latest transaction in your journal: + + + -p "from 2009/1/1" everything after january + 1, 2009 + -p "from 2009/1" the same + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 + + A single date with no "from" or "to" defines both the start and end + date like so: + + + -p "2009" the year 2009; equivalent + to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of jan; equiva- + lent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" just that day; equivalent + to "2009/1/1 to 2009/1/2" + + Or you can specify a single quarter like so: + + + -p "2009Q1" first quarter of 2009, + equivalent to "2009/1/1 to + 2009/4/1" + -p "q4" fourth quarter of the cur- + rent year + + Period expressions with a report interval + -p/--period's argument can also begin with, or entirely consist of, a + report interval. This should be separated from the start/end dates (if + any) by a space, or the word in. The basic intervals (which can also + be written as command line flags) are daily, weekly, monthly, quar- + terly, and yearly. Some examples: + + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "quarterly" + + As mentioned above, the weekly, monthly, quarterly and yearly intervals + require a report start date that is the first day of a week, month, + quarter or year. And, report start/end dates will be expanded if + needed to span a whole number of intervals. + + For example: + + + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + to 2009/4/1" day + -p "monthly in starts on 2018/11/01 + 2008/11/25" + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 + -p "yearly from starts on 2009/01/01, first day of 2009 + 2009-12-29" + + More complex report intervals + Some more complex kinds of interval are also supported in period + expressions: + + o biweekly + + o fortnightly + + o bimonthly + + o every day|week|month|quarter|year + + o every N days|weeks|months|quarters|years + + These too will cause report start/end dates to be expanded, if needed, + to span a whole number of intervals. Examples: + + + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + 2008/03/01, ... + -p "every 2 weeks" starts on closest preceding Monday + -p "every 5 months from periods will have boundaries on 2009/03/01, + 2009/03" 2009/08/01, ... + + Intervals with custom start date + All intervals mentioned above are required to start on their natural + calendar boundaries, but the following intervals can start on any date: + + Weekly on custom day: + + o every Nth day of week (th, nd, rd, or st are all accepted after the + number) + + o every WEEKDAYNAME (full or three-letter english weekday name, case + insensitive) + + Monthly on custom day: + + o every Nth day [of month] + + o every Nth WEEKDAYNAME [of month] + + Yearly on custom day: + + o every MM/DD [of year] (month number and day of month number) + + o every MONTHNAME DDth [of year] (full or three-letter english month + name, case insensitive, and day of month number) + + o every DDth MONTHNAME [of year] (equivalent to the above) + + Examples: + + + + + -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" + + Periods or dates ? + Report intervals like the above are most often used with -p|--period, + to divide reports into multiple subperiods - each generated date marks + a subperiod boundary. Here, the periods between the dates are what's + important. + + But report intervals can also be used with --forecast to generate + future transactions, or with balance --budget to generate budget goal- + setting transactions. For these, the dates themselves are what mat- + ters. + + Events on multiple weekdays + The every WEEKDAYNAME form has a special variant with multiple day + names, comma-separated. Eg: every mon,thu,sat. Also, weekday and + weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec- + tively. + + This form is mainly intended for use with --forecast, to generate peri- + odic transactions on arbitrary days of the week. It may be less useful + with -p, since it divides each week into subperiods of unequal length. + (Because gaps between periods are not allowed; if you'd like to change + this, see #1632.) + + Examples: + + + -p "every dates will be Mon, Wed, Fri; periods will be Mon- + mon,wed,fri" Tue, Wed-Thu, Fri-Sun + -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + be Mon, Tue, Wed, Thu, Fri-Sun + -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri + day" + +DEPTH + With the --depth NUM option (short form: -NUM), commands like account, + balance and register will show only the uppermost accounts in the + account tree, down to level NUM. 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. + +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 argu- + ments to restrict their scope. The syntax is as follows: + + o Zero or more space-separated query terms. These are most often + account name substrings: + + utilities food:groceries + + o Terms with spaces or other special characters should be enclosed in + quotes: + + "personal care" + + o Regular expressions are also supported: + + "^expenses\b" "accounts (payable|receivable)" + + o Add a query type prefix to match other parts of the data: + + date:202012- desc:amazon cur:USD amt:">100" status: + + o Add a not: prefix to negate a term: + + not:cur:USD + + 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 expres- + sion. This is the default query type when there is no prefix, and reg- + ular 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. Oth- + erwise, the absolute magnitudes are compared, ignoring sign. + + code:REGEX + Match by transaction code (eg check number). + + cur:REGEX + Match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a 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). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, + case insensitive. Note type:A and type:E will also match their respec- + tive 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: + + o Accounts also inherit the tags of their parent accounts + + o Postings also inherit the tags of their account and their transaction + + o 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.) + + Combining query terms + Most commands select things which match: + + o any of the description terms AND + + o any of the account terms AND + + o any of the status terms AND + + o all the other terms. + + while the print command shows transactions which: + + o match any of the description terms AND + + o have any postings matching any of the positive account terms AND + + o have no postings matching any of the negative account terms AND + + o match all the other terms. + + You can do more powerful queries (such as AND-ing two like terms) by + running a first query with print, and piping the result into a second + hledger command. Eg: how much of food expenses was paid with cash ? + + $ hledger print assets:cash | hledger -f- -I balance expenses:food + + If you are interested in full boolean expressions for queries, see + #203. + + 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. + + Queries and account aliases + When account names are rewritten with --alias or alias, acct: will + match either the old or the new account name. + + 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). + + 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. + + 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. + +CONVERSION & COST + This section is about converting between commodities. Some defini- + tions: + + o A "commodity conversion" is an exchange of one currency or commodity + for another. Eg a foreign currency exchange, or a purchase or sale + of stock or cryptocurrency. + + o A "conversion transaction" is a transaction involving one or more + such conversions. + + o "Conversion rate" is the exchange rate in a conversion - the cost per + unit of one commodity in the other. + + o "Cost" is how much of one commodity was paid to acquire the other + (when buying), or how much was received in exchange for the other + (when selling). We call both of these "cost" for convenience (after + all, it is cost for one party or the other). + + Recording conversions + As a concrete example, let's assume 100 EUR was converted to 120 USD. + There are several ways to record this in the journal, each with pros + and cons which will be explained in more detail below. (Also, these + examples use journal format which is properly explained much further + below; sorry about that, you may want to read some of that first.) + + Implicit conversion + 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: + + o Easy, concise + + o hledger can do cost reporting + + Con: + + o Less error checking - typos in amounts or commodity symbols may not + be detected + + o conversion rate is not clear + + o disturbs the accounting equation + + You can prevent accidental implicit conversions due to a mistyped com- + modity symbol, by using hledger check commodities. You can prevent + implicit conversions entirely, by using hledger check balancednoauto- + conversion, or -s/--strict. + + Priced conversion + 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: + + o Still concise + + o makes the conversion rate clear + + o provides some error checking + + o hledger can do cost reporting + + Con: + + o Disturbs the accounting equation + + Equity conversion + In strict double entry bookkeeping, the above transaction is not bal- + anced 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: + + o Preserves the accounting equation + + o keeps track of conversions and related gains/losses in one place + + o works in any double entry accounting system + + Con: + + o More verbose + + o conversion rate is not clear + + o hledger can not do cost reporting + + Priced equity conversion + Another possible notation would be to record both the conversion rate + and the equity postings: + + 2021-01-01 + assets:cash -100 EUR @ 1.20 USD + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + hledger currently does not allow this; instead, you can record the con- + version rate as a comment. + + Inferring missing conversion rates + hledger will do this automatically for implicit conversions. Currently + it can not do this for equity conversions. + + Inferring missing equity postings + With the --infer-equity flag, hledger will add equity postings to + priced and implicit conversions (and move the conversion rate into a + comment). + + Cost reporting + With the -B/--cost flag, hledger will convert the amounts in priced and + implicit conversions to their cost in the other commodity. This is + useful to see a report of what you paid for things (or how much you + sold things for). Currently -B/--cost does not work on equity conver- + sions, and it disables --infer-equity. + + These operations are transient, only affecting reports. If you want to + change the journal file permanently, you could pipe each entry through + hledger -f- -I print [-x] [--infer-equity] [-B] + + Conversion summary + o Recording the conversion rate is good because it makes that clear and + allows cost reporting. + + o Recording equity postings is good because it balances the accounting + equation and is correct bookkeeping. + + o Combining these is not yet supported, so you have to choose. For + now, priced conversions are a good compromise, so that: + + o When you want to see the cost (or sale proceeds) of things, use + -B/--cost. + + o When you want to see a balanced balance sheet or correct journal + entries, use --infer-equity. + + o Combining these is not yet supported; -B/--cost will take prece- + dence. + + o Conversion/cost operations are performed before valuation. + +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: + + -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. + + -X: Value in specified commodity + The -X/--exchange=COMM option is like -V, except you tell it which cur- + rency you want to convert to, and it tries to convert everything to + that. + + 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. + + Market prices + 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 direc- + tive, or (with the --infer-market-prices flag) inferred from trans- + action prices. + + 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 com- + bining 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 con- + verted. + + --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 transaction prices as additional market + prices (as Ledger does) ? We could produce value reports without need- + ing P directives at all. + + 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. (And if + both occur on the same day, the P directive takes precedence). + + There is a downside: value reports can sometimes be affected in confus- + ing/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: + + o multicommodity transactions with explicit prices (@/@@) + + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. + hledger print -x can be useful for troubleshooting.) + + o but not, currently, from "more correct" multicommodity transactions + (no @, multiple commodities, balanced). + + There is another 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 con- + version might not happen because no valuation commodity was detected + (--debug=2 will show this). To be safe, specify the valuation commmod- + ity, eg: + + o -X EUR --infer-market-prices, not -V --infer-market-prices + + o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- + ket-prices + + 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 suit- + able 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: + + o If you have P directives, they determine which commodities -V will + convert, and to what. + + o If you have no P directives, and use the --infer-market-prices flag, + transaction prices determine it. + + Amounts for which no valuation commodity can be found are not con- + verted. + + Simple valuation examples + Here are some quick examples of -V: + + ; one euro is worth this many dollars from nov 1 + P 2016/11/01 EUR $1.10 + + ; purchase some euros on nov 3 + 2016/11/3 + assets:euros EUR100 + assets:checking + + ; the euro is worth fewer dollars by dec 21 + P 2016/12/21 EUR $1.03 + + How many euros do I have ? + + $ hledger -f t.j bal -N euros + EUR100 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 + + --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 commod- + ity, using market prices on each posting's date. + + --value=end + Convert amounts to their value in the default valuation commod- + ity, 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 commod- + ity using current market prices (as of when report is gener- + ated). + + --value=YYYY-MM-DD + Convert amounts to their value in the default valuation commod- + ity 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. + + 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 specify- + ing a display style for A, 0.5A gets the default style, which shows no + decimal digits. Because the displayed amount looks like zero, the com- + modity symbol and minus sign are not displayed either. Adding a com- + modity 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 + + 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 + + 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, --cost -V, -X --value=then --value=end --value=DATE, + type --value=now + ----------------------------------------------------------------------------------------------- + print + posting cost value at value at posting value at value at + amounts report end date report or DATE/today + or today journal end + balance unchanged unchanged unchanged unchanged unchanged + asser- + tions/assign- + ments + + register + starting bal- cost value at valued at day value at value at + ance (-H) report or each historical report or DATE/today + journal end posting was made journal end + starting bal- cost value at day valued at day value at day value at + ance (-H) before each historical before DATE/today + with report report or posting was made report or + interval journal journal + start start + posting cost value at value at posting value at value at + amounts report or date report or DATE/today + journal end journal end + summary post- summarised value at sum of postings value at value at + ing amounts cost period ends in interval, val- period ends DATE/today + with report ued at interval + interval start + running sum/average sum/average sum/average of sum/average sum/average + total/average of displayed of displayed displayed values of displayed of displayed + values values values values + + balance (bs, + bse, cf, is) + balance sums of value at value at posting value at value at + changes costs report end date report or DATE/today of + or today of journal end sums of post- + sums of of sums of ings + postings postings + budget like balance like balance like balance like bal- like balance + amounts changes changes changes ances changes + (--budget) + grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + played val- played val- valued played val- played values + ues ues ues + + + + balance (bs, + bse, cf, is) + with report + interval + starting bal- sums of value at sums of values of value at sums of post- + ances (-H) costs of report start postings before report start ings before + postings of sums of report start at of sums of report start + before all postings respective post- all postings + report start before ing dates before + report start report start + balance sums of same as sums of values of balance value at + changes (bal, costs of --value=end postings in change in DATE/today of + is, bs postings in period at respec- each period, sums of post- + --change, cf period tive posting valued at ings + --change) dates period ends + end balances sums of same as sums of values of period end value at + (bal -H, is costs of --value=end postings from balances, DATE/today of + --H, bs, cf) postings before period valued at sums of post- + from before start to period period ends ings + report start end at respective + to period posting dates + end + budget like balance like balance like balance like bal- like balance + amounts changes/end changes/end changes/end bal- ances changes/end + (--budget) balances balances ances balances + row totals, sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- + row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- + (-T, -A) played val- played val- played val- played values + ues ues ues + column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + played val- played val- values played val- played values + ues ues ues + grand total, sum, average sum, average sum, average of sum, average sum, average + grand average of column of column column totals of column of column + totals totals totals 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 subperi- + ods). + +PIVOTING + Normally hledger sums amounts, and organizes them in a hierarchy, based + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD + can be: status, code, description, payee, note, or the full name (case + insensitive) of any tag. As with account names, values containing + colon:separated:parts will be displayed hierarchically in reports. + + --pivot is a general option affecting all reports; you can think of + hledger transforming the journal before any other processing, replacing + every posting's account name with the value of the specified field on + that posting, inheriting it from the transaction or using a blank value + if it's not present. + + An example: + + 2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query, + described below): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + +OUTPUT + 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 pro- + vide 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) + + hledger can optionally produce debug output (if enabled with + --debug=N); this goes to stderr, and is not affected by -o/--output- + file. If you need to capture it, use shell redirects, eg: hledger bal + --debug=3 >file 2>&1. + + Output styling + hledger commands can produce colour output when the terminal supports + it. This is controlled by the --color/--colour option: - 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. + + hledger commands can also use unicode box-drawing characters to produce + prettier tables and output. This is controlled by the --pretty option: + - 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. + + Output format + Some commands offer additional output formats, other than the usual + plain text terminal output. Here are those commands and the formats + currently supported: + + + - txt csv html json sql + --------------------------------------------- + aregister Y Y Y + balance Y 1 Y 1 Y 1,2 Y + bal- Y 1 Y 1 Y 1 Y + ancesheet + bal- Y 1 Y 1 Y 1 Y + ancesheete- + quity + cashflow Y 1 Y 1 Y 1 Y + incomes- Y 1 Y 1 Y 1 Y + tatement + print Y Y Y Y + register Y Y Y + + o 1 Also affected by the balance commands' --layout option. + + o 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 + + CSV output + o In CSV output, digit group marks (such as thousands separators) are + disabled automatically. + + HTML output + o HTML output can be styled by an optional hledger.css file in the same + directory. + + JSON output + o Not yet much used; real-world feedback is welcome. + + o Our JSON is rather large and verbose, as it is quite a faithful rep- + resentation 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. + + o 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) + + SQL output + o Not yet much used; real-world feedback is welcome. + + o SQL output is expected to work with sqlite, MySQL and PostgreSQL + + o SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables cre- + ated 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. + + Commodity styles + The display style of a commodity/currency is inferred according to the + rules described in Commodity display style. The inferred display style + can be overridden by an optional -c/--commodity-style option (Excep- + tions: as is the case for inferred styles, price amounts, and all + amounts displayed by the print command, will be displayed with all of + their decimal digits visible, regardless of the specified precision). + For example, the following will override the display style for dollars. + + $ hledger print -c '$1.000,0' + + The format specification of the style is identical to the commodity + display style specification for the commodity directive. The command + line option can be supplied repeatedly to override the display style + for multiple commodity/currency symbols. + +COMMANDS + hledger provides a number of commands for producing reports and manag- + ing your data. Run hledger with no arguments to list the commands + available, and hledger CMD to run a command. CMD can be the full com- + mand name, or its standard abbreviation shown in the commands list, or + any unambiguous prefix of the name. Eg: hledger bal. + + Here are the built-in commands, with the most often-used in bold: + + Data entry: + + These data entry commands are the only ones which can modify your jour- + nal file. + + o add - add transactions using guided prompts + + o import - add any new transactions from other files (eg csv) + + Data management: + + o check - check for various kinds of issue in the data + + o close (equity) - generate balance-resetting transactions + + o diff - compare account transactions in two journal files + + o rewrite - generate extra postings, similar to print --auto + + Financial statements: + + o aregister (areg) - show transactions in a particular account + + o balancesheet (bs) - show assets, liabilities and net worth + + o balancesheetequity (bse) - show assets, liabilities and equity + + o cashflow (cf) - show changes in liquid assets + + o incomestatement (is) - show revenues and expenses + + o roi - show return on investments + + Miscellaneous reports: + + o accounts - show account names + + o activity - show postings-per-interval bar charts + + o balance (bal) - show balance changes/end balances/budgets in any + accounts + + o codes - show transaction codes + + o commodities - show commodity/currency symbols + + o descriptions - show unique transaction descriptions + + o files - show input file paths + + o help - show hledger user manuals in several formats + + o notes - show unique note segments of transaction descriptions + + o payees - show unique payee segments of transaction descriptions + + o prices - show market price records + + o print - show transactions (journal entries) + + o print-unique - show only transactions with unique descriptions + + o register (reg) - show postings in one or more accounts & running + total + + o register-match - show a recent posting that best matches a descrip- + tion + + o stats - show journal statistics + + o tags - show tag names + + o test - run self tests + + Add-on commands: + + Programs or scripts named hledger-SOMETHING in your PATH are add-on + commands; these appear in the commands list with a + mark. Two of + these are maintained and released with hledger: + + o ui - an efficient terminal interface (TUI) for hledger + + o web - a simple web interface (WUI) for hledger + + And these add-ons are maintained separately: + + o iadd - a more interactive alternative for the add command + + o interest - generates interest transactions according to various + schemes + + o stockquotes - downloads market prices for your commodities from + AlphaVantage (experimental) + + Next, the detailed command docs, in alphabetical order. + + accounts + accounts + Show account names. + + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N + or -N. + + With --types, it also shows each account's type, if it's known. (See + Declaring accounts > Account types.) + + Examples: + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + activity + activity + Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the + default). With query arguments, it counts only matched transactions. + + Examples: + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + + add + add + Prompt for transactions and add them to the journal. 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 trans- + actions, 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: + + o add tries to provide useful defaults, using the most similar (by + description) recent transaction (filtered by the query, if any) as a + template. + + o You can also set the initial defaults with command line arguments. + + o Readline-style edit keys can be used during data entry. + + o The tab key will auto-complete whenever possible - accounts, descrip- + tions, dates (yesterday, today, tomorrow). If the input area is + empty, it will insert the default value. + + o If the journal defines a default commodity, it will be added to any + bare numbers entered. + + o A parenthesised transaction code may be entered following a date. + + o Comments and tags may be entered following a description or amount. + + o If you make a mistake, enter < at any prompt to go one step backward. + + o Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see the tutorial for a detailed explanation): + + $ hledger add + Adding transactions to journal file /src/hledger/examples/sample.journal + Any command line arguments will be used as defaults. + Use tab key to complete, readline keys to edit, enter to accept defaults. + An optional (CODE) may follow transaction dates. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to 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). + + aregister + 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 areg- + ister 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. + (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, + hledger areg checking would select assets:aaa:checking.) + + 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 transac- + tions shown. Note some queries will disturb the running balance, caus- + ing 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: + + o the transaction's date (or the relevant posting's date if different, + see below) + + o the names of all the other account(s) involved in this transaction + (probably abbreviated) + + o the total change to this account's balance from this transaction + + o 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. + + 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. + + balance + 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, bal- + ancesheetequity, cashflow and incomestatement. When you need more con- + trol, then use balance. + + 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.. + + o accounts as a list (-l) or a tree (-t) + + o optionally depth-limited (-[1-9]) + + o sorted by declaration order and name, or by amount + + ..and their.. + + o balance changes (the default) + + o or actual and planned balance changes (--budget) + + o or value of balance changes (-V) + + o or change of balance values (--valuechange) + + o or unrealised capital gain/loss (--gain) + + ..in.. + + o one time period (the whole journal period by default) + + o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) + + ..either.. + + o per period (the default) + + o or accumulated since report start date (--cumulative) + + o or accumulated since account creation (--historical/-H) + + ..possibly converted to.. + + o cost (--value=cost[,COMM]/--cost/-B) + + o or market value, as of transaction dates (--value=then[,COMM]) + + o or at period ends (--value=end[,COMM]) + + o or now (--value=now) + + o or at some other date (--value=YYYY-MM-DD) + + ..with.. + + o totals (-T), averages (-A), percentages (-%), inverted sign + (--invert) + + o rows and columns swapped (--transpose) + + o another field used as account name (--pivot) + + o custom-formatted line items (single-period reports only) (--format) + + o 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. + + 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. For real-world + accounts, this should also match their end balance at the end of the + journal period (more on this below). + + Accounts are sorted by declaration order if any, and then alphabeti- + cally 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. + + 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 + + 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: + + o "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). + + o 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-plaintextac- + counting-users. A tree mode report's final total is the sum of the + top-level balances shown, not of all the balances shown. + + o Each group of sibling accounts (ie, under a common parent) is sorted + separately. + + 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 + + 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 + + + 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), bal- + ance 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: + + o The report's start/end dates will be expanded, if necessary, to fully + encompass the displayed subperiods (so that the first and last subpe- + riods have the same duration as the others). + + o Leading and trailing periods (columns) containing all zeroes are not + shown, unless -E/--empty is used. + + o Accounts (rows) containing all zeroes are not shown, unless + -E/--empty is used. + + o Amounts with many commodities are shown in abbreviated form, unless + --no-elide is used. (experimental) + + o Average and/or total columns can be added with the -A/--average and + -T/--row-total flags. + + o The --transpose flag can be used to exchange rows and columns. + + o 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: + + o Hide the totals row with -N/--no-total + + o Convert to a single currency with -V + + o Maximize the terminal window + + o Reduce the terminal's font size + + o View with a pager like less, eg: hledger bal -D --color=yes | less + -RS + + o 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) + + o Output as HTML and view with a browser: hledger bal -D -o a.html && + open a.html + + 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. + + Data layout + The --layout option affects how multi-commodity amounts are displayed, + and some other things, influencing the overall layout of the report + data: + + o --layout=wide[,WIDTH]: commodities are shown on a single line, possi- + bly elided to the specified width + + o --layout=tall: each commodity is shown on a separate line + + o --layout=bare: amounts are shown as bare numbers, with commodity sym- + bols in a separate column + + o --layout=tidy: data is normalised to tidy form, with one row per data + value. We currently support this with CSV output only. In tidy + mode, totals and row averages are disabled (-N/--no-total is implied + and -T/--row-total and -A/--average will be ignored). + + These --layout modes are supported with some but not all of the output + formats: + + + - txt csv html json sql + ------------------------------------- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y + + Examples: + + o 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 + + o Limited wide layout. A width limit reduces the width, but some com- + modities 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.. + + o 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 + + o Bare layout. Commodity symbols are kept in one column, each commod- + ity 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 + + o Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg when 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" + + o Tidy layout produces normalised "tidy data", where every variable is + a column and each row represents a single data point (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- + data.html). This kind of data is the easiest to process with other + software: + + $ 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" + + Sorting by amount + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. Eg: hledger bal expenses -MAS shows your big- + gest 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). + + + Percentages + With -%/--percent, balance reports show each account's value expressed + as a percentage of the (column) total: + + $ hledger -f examples/sample.journal bal expenses -Q -% + Balance changes in 2008: + + || 2008Q1 2008Q2 2008Q3 2008Q4 + ===================++================================= + expenses:food || 0 50.0 % 0 0 + expenses:supplies || 0 50.0 % 0 0 + -------------------++--------------------------------- + || 0 100.0 % 0 0 + + Note it is not useful to calculate percentages if the amounts in a col- + umn 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:EUR + + Balance change, end balance + It's important to be clear on the meaning of the numbers shown in bal- + ance 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 post- + ings.) + + Balance report types + For more flexible reporting, there are three important option groups: + + hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] + ... + + The first two are the most important: calculation type selects the + basic calculation to perform for each table cell, while accumulation + type says which postings should be included in each cell's calculation. + Typically one or both of these are selected by default, so you don't + need to write them explicitly. A valuation type can be added if you + want to convert the basic report to value or cost. + + Calculation type: + The basic calculation to perform for each table cell. It is one of: + + o --sum : sum the posting amounts (default) + + o --budget : like --sum but also show a goal amount + + o --valuechange : show the change in period-end historical balance val- + ues (caused by deposits, withdrawals, and/or market price fluctua- + tions) + + o --gain : show the unrealised capital gain/loss, (the current valued + balance minus each amount's original cost) + + Accumulation type: + Which postings should be included in each cell's calculation. It is + one of: + + o --change : postings from column start to column end, ie within the + cell's period. Typically used to see revenues/expenses. (default + for balance, incomestatement) + + o --cumulative : postings from report start to column end, eg to show + changes accumulated since the report's start date. Rarely used. + + o --historical/-H : postings from journal start to column end, ie all + postings from account creation to the end of the cell's period. Typ- + ically used to see historical end balances of assets/liabili- + ties/equity. (default for balancesheet, balancesheetequity, cash- + flow) + + Valuation type: + Which kind of valuation, valuation date(s) and optionally a target val- + uation commodity to use. It is one of: + + o no valuation, show amounts in their original commodities (default) + + o --value=cost[,COMM] : no valuation, show amounts converted to cost + + o --value=then[,COMM] : show value at transaction dates + + o --value=end[,COMM] : show value at period end date(s) (default with + --valuechange, --gain) + + o --value=now[,COMM] : show value at today's date + + o --value=YYYY-MM-DD[,COMM] : show value at another date + + or one of their aliases: --cost/-B, --market/-V or --exchange/-X. + + 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: + + o --valuechange implies --value=end + + o --valuechange makes --change the default when used with the bal- + ancesheet/balancesheetequity commands + + o --cumulative or --historical disables --row-total/-T + + For reference, here is what the combinations of accumulation and valua- + tion show: + + + + Valua- no valuation --value= then --value= end --value= YYYY- + tion: MM-DD /now + >Accumu- + lation: + v + ------------------------------------------------------------------------------------ + --change change in period sum of posting- period-end DATE-value of + date market val- value of change change in + ues in period in period period + --cumu- change from sum of posting- period-end DATE-value of + lative report start to date market val- value of change change from + period end ues from report from report report start + start to period start to period to period end + end end + --his- change from sum of posting- period-end DATE-value of + torical journal start to date market val- value of change change from + /-H period end (his- ues from journal from journal journal start + torical end bal- start to period start to period to period end + ance) end end + + Useful balance reports + Some frequently used balance options/reports are: + + o bal -M revenues expenses + Show revenues/expenses in each month. Also available as the incomes- + tatement command. + + o bal -M -H assets liabilities + Show historical asset/liability balances at each month end. Also + available as the balancesheet command. + + o bal -M -H assets liabilities equity + Show historical asset/liability/equity balances at each month end. + Also available as the balancesheetequity command. + + o bal -M assets not:receivable + Show changes to liquid assets in each month. Also available as the + cashflow command. + + Also: + + o bal -M expenses -2 -SA + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + o bal -M --budget expenses + Show monthly expenses and budget goals. + + o bal -M --valuechange investments + Show monthly change in market value of investment assets. + + o bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert] + Show top gainers [or losers] last week + + 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 very 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: + + o Only accounts with budget goals during the report period are shown, + by default. + + o In each column, in square brackets after the actual amount, budget + goal amounts are shown, and the actual/goal percentage. (Note: bud- + get goals should be in the same commodity as the actual amount.) + + o All parent accounts are always shown, even in list mode. Eg assets, + assets:bank, and expenses above. + + o 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 transac- + tions, 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] + + For more examples and notes, see Budgeting. + + 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] + + 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 bud- + get(s) of the child account(s) would be added to the budget of their + parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any + account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which 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 transac- + tions in any other subaccount of expenses:personal would be counted + towards only towards the budget of expenses:personal. + + For example, let's consider these transactions: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + 2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + + 2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + + 2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + + 2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- + tions would be counted towards budgets of expenses:personal:electronics + and expenses:personal accordingly: + + $ hledger balance --budget -M + Budget performance in 2019/01: + + || Jan + ===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] + -------------------------------++------------------------------- + || 0 [ 0] + + And with --empty, we can get a better picture of budget allocation and + consumption: + + $ hledger balance --budget -M --empty + Budget performance in 2019/01: + + || Jan + ========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] + ----------------------------------------++------------------------------- + || 0 [ 0] + + Selecting budget goals + The budget report evaluates periodic transaction rules to generate spe- + cial "goal transactions", which generate the goal amounts for each + account in each report subperiod. When troubleshooting, you can use + the print command 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. + + Customising single-period balance reports + 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 (plus a newline) specifies the formatting applied + to each account/balance pair. It may contain any suitable text, with + data fields interpolated like so: + + %[MIN][.MAX](FIELDNAME) + + o MIN pads with spaces to at least this width (optional) + + o MAX truncates at this width (optional) + + o FIELDNAME must be enclosed in parentheses, and can be one of: + + o depth_spacer - a number of spaces equal to the account's depth, or + if MIN is specified, MIN * depth spaces. + + o account - the account's name + + o total - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how multi-com- + modity amounts are rendered: + + o %_ - render on multiple lines, bottom-aligned (the default) + + o %^ - render on multiple lines, top-aligned + + o %, - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, %(depth_spacer) has no + effect, instead %(account) has indentation built in. Experimentation + may be needed to get pleasing results. + + Some example formats: + + o %(total) - the account's total + + o %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters + + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line + + o %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + + balancesheet + balancesheet, bs + This command displays a balance sheet, showing historical ending bal- + ances 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 sup- + ports 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 (experi- + mental) json. + + balancesheetequity + balancesheetequity, bse + This command displays a balance sheet, showing historical ending bal- + ances 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 sup- + ports 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 (experi- + mental) json. + + cashflow + 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 finan- + cial statements. + + This report shows accounts declared with the Cash type (see account + types). Or if no such accounts are declared, it shows accounts + + o under a top-level account named asset (case insensitive, plural + allowed) + + o 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 sup- + ports 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 (experi- + mental) json. + + check + 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 + + Here are the checks currently available: + + Basic checks + These checks are always run automatically, by (almost) all hledger com- + mands, including check: + + o parseable - data files are well-formed and can be successfully parsed + + o balancedwithautoconversion - all transactions are balanced, inferring + missing amounts where necessary, and possibly converting commodities + using transaction prices or automatically-inferred transaction prices + + o assertions - all balance assertions in the journal are passing. + (This check can be disabled with -I/--ignore-assertions.) + + 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: + + o accounts - all account names used by transactions have been declared + + o commodities - all commodity symbols used have been declared + + o balancednoautoconversion - transactions are balanced, possibly using + explicit transaction prices but not inferred ones + + 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: + + o ordereddates - transactions are ordered by date within each file + + o payees - all payees used by transactions have been declared + + o uniqueleafnames - all account leaf names are unique + + Custom checks + A few more checks are are available as separate add-on commands, in + https://github.com/simonmichael/hledger/tree/master/bin: + + o hledger-check-tagfiles - all tag values containing / (a forward + slash) exist as file paths + + o hledger-check-fancyassertions - more complex balance assertions are + passing + + You could make similar scripts to perform your own custom checks. See: + Cookbook -> Scripting. + + close + close, equity + Prints a sample "closing" transaction bringing specified account bal- + ances to zero, and an inverse "opening" transaction restoring the same + account balances. + + If like most people you split your journal files by time, eg by year: + at the end of the year you can use this command to "close out" your + asset and liability (and perhaps equity) balances in the old file, and + reinitialise them in the new file. This helps ensure that report bal- + ances remain correct whether you are including old files or not. + (Because all closing/opening transactions except the very first will + cancel out - see example below.) + + Some people also use this command to close out revenue and expense bal- + ances at the end of an accounting period. This properly records the + period's profit/loss as "retained earnings" (part of equity), and + allows the accounting equation (A-L=E) to balance, which you could then + check by the bse report's zero total. + + You can print just the closing transaction by using the --close flag, + or just the opening transaction with the --open flag. + + Their descriptions are closing balances and opening balances by + default; you can customise these with the --close-desc and --open-desc + options. + + Just one balancing equity posting is used by default, with the amount + left implicit. The default account name is equity:opening/closing bal- + ances. You can customise the account name(s) with --close-acct and + --open-acct. (If you specify only one of these, it will be used for + both.) + + With --x/--explicit, the equity posting's amount will be shown explic- + itly, and if it involves multiple commodities, there will be a separate + equity posting for each commodity (as in the print command). + + With --interleaved, each equity posting is shown next to the posting it + balances (good for troubleshooting). + + close and prices + Transaction prices are ignored (and discarded) by closing/opening + transactions, by default. With --show-costs, they are preserved; there + will be a separate equity posting for each cost in each commodity. + This means balance -B reports will look the same after the transition. + Note if you have many foreign currency or investment transactions, this + will generate very large journal entries. + + close date + The default closing date is yesterday, or the journal's end date, + whichever is later. + + Unless you are running close on exactly the first day of the new + period, you'll want to override the closing date. This is done by + specifying a report end date, where "last day of the report period" + will be the closing date. The opening date is always the following + day. So to close on (end of) 2020-12-31 and open on (start of) + 2021-01-01, any of these will work: + + + end date argument explanation + ----------------------------------------------- + -e 2021-01-01 end dates are exclusive + -e 2021 equivalent, per smart + dates + -p 2020 equivalent, the period's + begin date is ignored + date:2020 equivalent query + + Example: close asset/liability accounts for file transition + Carrying asset/liability balances from 2020.journal into a new file for + 2021: + + $ hledger close -f 2020.journal -p 2020 assets liabilities + # copy/paste the closing transaction to the end of 2020.journal + # copy/paste the opening transaction to the start of 2021.journal + + Or: + + $ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction + $ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction + + Now, + + $ hledger bs -f 2021.journal # just new file - balances correct + $ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct + $ hledger bs -f 2020.journal # just old files - balances are zero ? + # (exclude final closing txn, see below) + + Hiding opening/closing transactions + Although the closing/opening transactions cancel out, they will be vis- + ible in reports like print and register, creating some visual clutter. + You can exclude them all with a query, like: + + $ hledger print not:desc:'opening|closing' # less typing + $ hledger print not:'equity:opening/closing balances' # more precise + + But when reporting on multiple files, this can get a bit tricky; you + may need to keep the earliest opening balances, for a historical regis- + ter report; or you may need to suppress a closing transaction, to see + year-end balances. If you find yourself needing more precise queries, + here's one solution: add more easily-matched tags to opening/closing + transactions, like this: + + ; 2019.journal + 2019-01-01 opening balances ; earliest opening txn, no tag here + ... + 2019-12-31 closing balances ; clopen:2020 + ... + + ; 2020.journal + 2020-01-01 opening balances ; clopen:2020 + ... + 2020-12-31 closing balances ; clopen:2021 + ... + + ; 2021.journal + 2021-01-01 opening balances ; clopen:2021 + ... + + Now with + + ; all.journal + include 2019.journal + include 2020.journal + include 2021.journal + + you could do eg: + + $ hledger -f all.journal reg -H checking not:tag:clopen + # all years checking register, hiding non-essential opening/closing txns + + $ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 + # 2020 year end balances, suppressing 2020 closing txn + + close and balance assertions + The closing and opening transactions will include balance assertions, + verifying that the accounts have first been reset to zero and then + restored to their previous balance. These provide valuable error + checking, alerting you when things get out of line, but you can ignore + them temporarily with -I or just remove them if you prefer. + + You probably shouldn't use status or realness filters (like -C or -R or + status:) with close, or the generated balance assertions will depend on + these flags. Likewise, if you run this command with --auto, the bal- + ance assertions would probably always require --auto. + + Multi-day transactions (where some postings have a different date) + break the balance assertions, because the money is temporarily "invisi- + ble" while in transit: + + 2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + assets:bank:checking -5 ; date: 2021/1/2 + + To fix the assertions, you can add a temporary account to track such + in-transit money (splitting the multi-day transaction into two single- + day transactions): + + ; in 2020.journal: + 2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + liabilities:pending + + ; in 2021.journal: + 2021/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:bank:checking + + Example: close revenue/expense accounts to retained earnings + For this, use --close to suppress the opening transaction, as it's not + needed. Also you'll want to change the equity account name to your + equivalent of "equity:retained earnings". + + Closing 2021's first quarter revenues/expenses: + + $ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ + --close-acct='equity:retained earnings' >> 2021.journal + + The same, using the default journal and current year: + + $ hledger close --close revenues expenses -p Q1 \ + --close-acct='equity:retained earnings' >> $LEDGER_FILE + + Now, the first quarter's balance sheet should show a zero (unless you + are using @/@@ notation without equity postings): + + $ hledger bse -p Q1 + + And we must suppress the closing transaction to see the first quarter's + income statement (using the description; not:'retained earnings' won't + work here): + + $ hledger is -p Q1 not:desc:'closing balances' + + codes + 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: + + 1/1 (123) + (a) 1 + + 1/1 () + (a) 1 + + 1/1 + (a) 1 + + 1/1 (126) + (a) 1 + + $ hledger codes + 123 + 124 + 126 + + $ hledger codes -E + 123 + 124 + + + 126 + + commodities + commodities + List all commodity/currency symbols used or declared in the journal. + + descriptions + 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 trans- + actions. + + Example: + + $ hledger descriptions + Store Name + Gas Station | Petrol + Person A + + diff + 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 mul- + tiple 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: + + files + files + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + help + help + Show the hledger user manual in one of several formats, optionally + positioned at a given TOPIC (if possible). + + TOPIC is any heading in the manual, or the start of any heading (but + not the middle). It is case insensitive. + + Some examples: commands, print, forecast, "auto postings", "commodity + column". + + This command shows the user manual built in to this hledger version. + It can be useful if the correct version of the hledger manual, or the + usual viewing tools, are not installed on your system. + + By default it uses the best viewer it can find in $PATH, in this order: + info, man, $PAGER (unless a topic is specified), less, or stdout. When + run non-interactively, it always uses stdout. Or you can select a par- + ticular viewer with the -i (info), -m (man), or -p (pager) flags. + + import + 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' trans- + actions 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 out- + put 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. + + 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 idem- + potent.) + + 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 sav- + ing a hidden ".latest" state file in the same directory. Eg when read- + ing finance/bank.csv, it will look for and update the finance/.lat- + est.bank.csv state file. The format is simple: one or more lines con- + taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- + cessed 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 cer- + tain date. + + Note deduplication (and updating of state files) can also be done by + print --new, but this is less often used. + + 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' + + 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.) + + Commodity display styles + Imported amounts will be formatted according to the canonical commodity + styles (declared or inferred) in the main journal file. + + incomestatement + 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 insensi- + tive, 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 sup- + ports 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 (experi- + mental) json. + + notes + 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 transac- + tions. 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 + + payees + 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 + + prices + prices + Print market price directives from the journal. With --infer-market- + prices, generate additional market prices from transaction prices. + With --infer-reverse-prices, also generate market prices by inverting + transaction prices. Prices (and postings providing transaction prices) + can be filtered by a query. Price amounts are displayed with their + full precision. + + print + 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 deci- + mal places are shown, as in the original journal entry (with one alter- + ation: 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: + + o Valuation affects posting amounts but not balance assertion or bal- + ance assignment amounts, potentially causing those to fail. + + o Auto postings can generate postings with too many missing amounts. + + o Account aliases can generate bad account names. + + Normally, the journal entry's explicit or implicit amount style is pre- + served. For example, when an amount is omitted in the journal, it will + not appear in the output. Similarly, when a transaction price is + implied but not written, it will not appear in the output. You can use + the -x/--explicit flag to make all amounts and transaction prices + 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 transaction prices are converted to cost + using that price. This can be used for troubleshooting. + + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is + no similar-enough match, no transaction will be shown. + + With --new, hledger prints only transactions it has not seen on a pre- + vious run. This uses the same deduplication system as the import com- + mand. (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","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o The "txnidx" (transaction index) field shows which postings belong to + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different + order, etc.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + print-unique + print-unique + Print transactions which do not reuse an already-seen description. + + Example: + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + + register + register, reg + 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 num- + bers. 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. + + 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. + + register-match + register-match + Print the one posting whose transaction description is closest to DESC, + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger- + autosync detect already-seen transactions when importing. + + rewrite + rewrite + Print all transactions, rewriting the postings of matched transactions. + For now the only rewrite available is adding new postings, like print + --auto. + + This is a start at a generic rewriter of transaction entries. It reads + the default journal and prints the transactions, like print, but adds + one or more specified postings to any transactions matching QUERY. The + posting amounts can be fixed, or a multiplier of the existing transac- + tion's first posting amount. + + Examples: + + $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' + $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' + $ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + + = ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the + two spaces between account and amount. + + More: + + $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... + $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' + $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' + $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can + use '*' (star symbol) before the amount to indicate that that this is a + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- + modity. + + Re-write rules in a file + During the run this tool will execute so called "Automated Transac- + tions" found in any journal it process. I.e instead of specifying this + operations in command line you can put them in a journal file. + + $ rewrite-rules.journal + + Make contents look like this: + + = ^income + (liabilities:tax) *.33 + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that '=' (equality symbol) that is used instead of date in trans- + actions you usually write. It indicates the query by which you want to + match the posting to add new ones. + + $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + + $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- + ings. + + Diff output format + To use this tool for batch modification of your journal files you may + find useful output in form of unified diff. + + $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + + --- /tmp/examples/sample.journal + +++ /tmp/examples/sample.journal + @@ -18,3 +18,4 @@ + 2008/01/01 income + - assets:bank:checking $1 + + assets:bank:checking $1 + income:salary + + (liabilities:tax) 0 + @@ -22,3 +23,4 @@ + 2008/06/01 gift + - assets:bank:checking $1 + + assets:bank:checking $1 + income:gifts + + (liabilities:tax) 0 + + If you'll pass this through patch tool you'll get transactions contain- + ing the posting that matches your query be updated. Note that multiple + files might be update according to list of input files specified via + --file options and include directives inside of these files. + + Be careful. Whole transaction being re-formatted in a style of output + from hledger print. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + rewrite vs. print --auto + This command predates print --auto, and currently does much the same + thing, but with these differences: + + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + + o rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + + o rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. + + roi + roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + on your investments. + + 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: + + o 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. + + o Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or con- + verges too slowly. + + Examples: + + o Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/invest- + ing/roi-unrealised.ledger + + o Cookbook > Return on Investment: https://hledger.org/roi.html + + 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'" + + 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. + + o "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 + + o "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 + + IRR and TWR explained + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- + tial value, expressed in percentage of the initial value. + + However, this approach is only practical in simple cases, where invest- + ments receives no in-flows or out-flows of money, and where rate of + growth is fixed over time. For more complex scenarios you need differ- + ent 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 percent- + age of your initial investment, and if you are adding to your invest- + ment, 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 "unreal- + ized 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: + + o Explanation of rate of return + + o Explanation of IRR + + o Explanation of TWR + + o Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + stats + 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 also supports output destination and output format selec- + tion. + + tags + tags + List the tags used in the journal, or their values. + + This command lists the tag names used in the journal, whether on trans- + actions, postings, or account declarations. + + With a TAGREGEX argument, only tag names matching this regular expres- + sion (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. + + test + 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). + + About add-on commands + Add-on commands are programs or scripts in your PATH + + o whose name starts with hledger- + + o whose name ends with a recognised file extension: .bat,.com,.exe, + .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none + + o and (on unix, mac) which are executable by the current user. + + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger library + functions that built-in commands use for command-line options, parsing + and reporting. Some experimental/example add-on scripts can be found + in the hledger repo's bin/ directory. + + 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 + +JOURNAL FORMAT + hledger's default file format, representing a General Journal. + + hledger's usual data source is a plain text file containing journal + entries in hledger journal format. This file represents a standard + accounting general journal. I use file names ending in .journal, but + that's not required. The journal file contains a number of transaction + entries, each describing a transfer of money (or any commodity) between + two or more named accounts, in a simple format readable by both hledger + and humans. + + hledger's journal format is a compatible subset, mostly, of ledger's + journal format, so hledger can work with compatible ledger journal + files as well. It's safe, and encouraged, to run both hledger and + ledger on the same journal file, eg to validate the results you're get- + ting. + + You can use hledger without learning any more about this file; just use + the add or web 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 configura- + tion at hledger.org for the full list. + + Here's a description of each part of the file format (and hledger's + data model). These are mostly in the order you'll use them, but in + some cases related concepts have been grouped together for easy refer- + ence, or linked before they are introduced, so feel free to skip over + anything that looks unnecessary right now. + + 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 sim- + ple date in column 0. This can be followed by any of the following + optional fields, separated by spaces: + + o a status character (empty, !, or *) + + o a code (any short number or text, enclosed in parentheses) + + o a description (any remaining text until end of line or a semicolon) + + o a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + + o 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 + + Dates + 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 cur- + rent transaction, the default year set with a default year 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.) + + Secondary dates + Real-life transactions sometimes involve more than one date - eg the + date you write a cheque, and the date it clears in your bank. When you + want to model this, for more accurate daily balances, you can specify + individual posting dates. + + Or, you can use the older secondary date feature (Ledger calls it aux- + iliary date or effective date). Note: we support this for compatibil- + ity, but I usually recommend avoiding this feature; posting dates are + almost always clearer and simpler. + + 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", as shown here: + + 2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + + $ hledger register checking + 2010-02-23 movie ticket assets:checking $-10 $-10 + + $ hledger register checking --date2 + 2010-02-19 movie ticket assets:checking $-10 $-10 + + Posting dates + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) + like date:DATE. This is probably the best way to control posting dates + precisely. Eg in this example the expense should appear in May + reports, and the deduction from checking should be reported on 6/1 for + easy bank reconciliation: + + 2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + + $ hledger -f t.j register food + 2015-05-30 expenses:food $10 $10 + + $ hledger -f t.j register checking + 2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. You can set the secondary date + similarly, with date2:DATE2. The date: or date2: tags must have a + valid simple date value if they are present, eg a date: tag with no + value is not allowed. + + Ledger's earlier, more compact bracketed date syntax is also supported: + [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any + square-bracketed sequence of the 0123456789/-.= characters in this way. + With this syntax, DATE infers its year from the transaction and DATE2 + infers its year from DATE. + + Status + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction + description or posting account name, separated from it by a space, + indicating one of three statuses: + + + + + mark status + ------------------ + unmarked + ! pending + * cleared + + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags; or the status:, status:!, and + status:* queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" state + is called "uncleared". As of hledger 1.3 we have renamed it to + unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching pend- + ing, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with + real-world accounts. Some editor modes provide highlighting and short- + cuts for working with status. Eg in Emacs ledger-mode, you can toggle + transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to you. + Here's one suggestion: + + + status meaning + -------------------------------------------------------------------------- + uncleared recorded but not yet reconciled; needs review + pending tentatively reconciled (if needed, eg during a big reconcil- + iation) + cleared complete, reconciled as far as possible, and considered cor- + rect + + With this scheme, you would use -PC to see the current balance at your + bank, -U to see things which will probably hit your bank soon (like + uncashed checks), and no flags to see the most up-to-date state of your + finances. + + 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. + + Description + A transaction's description is the rest of the line following the date + and status mark (or until a comment begins). Sometimes called the + "narration" in traditional bookkeeping, it can be used for whatever you + wish, or left blank. Transaction descriptions can be queried, unlike + comments. + + Payee and note + You can optionally include a | (pipe) character in descriptions to sub- + divide 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. + + Comments + Lines in the journal beginning with a semicolon (;) or hash (#) or star + (*) are comments, and will be ignored. (Star comments cause org-mode + nodes to be ignored, allowing emacs users to fold and navigate their + journals with org-mode or orgstruct-mode.) + + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. + Transaction and posting comments must begin with a semicolon (;). + + Some examples: + + # a file comment + ; another file comment + * also a file comment, useful in org/orgstruct mode + + comment + A multiline file comment, which continues + until a line containing just "end comment" + (or end of file). + end comment + + 2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 + ; a file comment (because not indented) + + You can also comment larger regions of a file using comment and end + comment directives. + + Tags + Tags are a way to add extra labels or labelled data to postings and + transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full + colon, written inside a transaction or posting comment line: + + 2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the + next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or new- + lines. Ending at commas means you can write multiple short tags on one + line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + o "a comment containing" is just comment text, not a tag + + o "tag1" is a tag with no value + + o "tag2" is another tag, whose value is "some value ..." + + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, third- + tag) and the posting has four (those plus posting-tag): + + 1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values + are simple strings. + + Postings + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or + tab (2 or 4 spaces is common), followed by: + + o (optional) a status character (empty, !, or *), followed by a space + + o (required) an account name (any text, optionally containing single + spaces, until end of line or a double space) + + o (optional) two or more spaces or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are + being removed. + + The amounts within a transaction must always sum up to zero. As a con- + venience, one amount may be left blank; it will be inferred so as to + balance the transaction. + + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the + amount, the amount will be considered part of the account name. + + Virtual postings + A posting with a parenthesised 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 accounting, 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: + + 1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with a bracketed 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: + + 1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance + + Ordinary non-parenthesised, non-bracketed postings are called real + postings. You can exclude virtual postings from reports with the + -R/--real flag or real:1 query. + + Account names + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five top- + level accounts: assets, liabilities, revenue, expenses, and equity. + + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more + spaces (or newline). + + Account names can be aliased. + + Amounts + After the account name, there is usually an amount. (Important: + between account name and amount, there must be two or more spaces.) + + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- + tity"): + + 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 com- + modity 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 + + 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 jour- + nal 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 detail below. + + 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 punctu- + ation), 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.) + + 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, in JOURNAL FORMAT -> Declaring commodities. + 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 + + + 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: + + o The commodity directive for that commodity (including the no-symbol + commodity), if any. + + o The amounts in that commodity seen in the journal's transactions. + (Posting amounts only; prices and periodic or auto rules are ignored, + currently.) + + o The built-in fallback style, which looks like this: $1000.00. (Sym- + bol on the left, period decimal mark, two decimal places.) + + A style is inferred from journal amounts as follows: + + o Use the general style (decimal mark, symbol placement) of the first + amount + + o Use the first-seen digit group style (digit group mark, digit group + sizes), if any + + o Use the maximum number of decimal places of all. + + Transaction price amounts don't affect the commodity display style + directly, but occasionally they can do so indirectly (eg when a post- + ing's amount is inferred using a transaction price). 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. + + 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"). (Guaranteed since hledger 1.17.1; in older versions + this could vary if hledger was built with Decimal < 0.5.1.) + + Transaction prices + Within a transaction, you can note an amount's price in another commod- + ity. This can be used to document the cost (in a purchase) or selling + price (in a sale). For example, transaction prices are useful to + record purchases of a foreign currency. Note transaction prices are + fixed at the time of the transaction, and do not change over time. See + also market prices, which represent prevailing exchange rates on a cer- + tain date. + + There are several ways to record a transaction price: + + 1. Write the price per unit, as @ UNITPRICE after the amount: + + 2009/1/1 + assets:euros EUR100 @ $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 EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros EUR100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati- + bility with Ledger journals (Virtual posting costs), and is equiva- + lent to 1 in hledger. + + 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger, + this is equivalent to 2. + + Use the -B/--cost flag to convert amounts to their transaction price's + commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). + Eg here is how -B affects the balance report for the example above: + + $ hledger bal -N --flat + $-135 assets:dollars + EUR100 assets:euros + $ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last + amount. So if example 3's postings are reversed, while the transaction + is equivalent, -B shows something different: + + 2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros EUR100 ; for 100 euros + + $ hledger bal -N --flat -B + EUR-100 assets:dollars # <- the dollars' selling price + EUR100 assets:euros + + Lot prices, lot dates + Ledger allows another kind of price, lot price (four variants: {UNIT- + PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), + and/or a lot date ([DATE]) to be specified. These are normally used to + select a lot when selling investments. hledger will parse these, for + compatibility with Ledger journals, but currently ignores them. A + transaction price, lot price and/or lot date may appear in any order, + after the posting amount and before the balance assertion if any. + + 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 pro- + tect 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, below). + + Assertions and ordering + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- + ferent from Ledger, which sorts assertions only by parse order. (Also, + Ledger assertions do not see the accumulated effect of repeated post- + ings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder 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. + + 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. + + 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 bal- + ance from earlier files. This can be useful when you do not want prob- + lems 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. + + 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 1EUR + b $-1 + c -1EUR + + 2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1EUR + b 0 == $-1 + c 0 == -1EUR + + 2013/1/3 ; This assertion fails as 'a' also contains 1EUR + 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 1EUR + b + + 2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1EUR + + Assertions and prices + Balance assertions ignore transaction prices, and should normally be + written without one: + + 2019/1/1 + (a) $1 @ EUR1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- + ments do use them (see below). + + Assertions and subaccounts + 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 + + 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. + + 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: + + o assert the balance calculated with --auto, and always use --auto with + that file + + o or assert the balance calculated without --auto, and never use --auto + with that file + + o or avoid balance assertions on accounts affected by auto postings (or + avoid auto postings entirely). + + Assertions and precision + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- + tions. Balance assertion failure messages show exact amounts. + + Balance assignments + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when + setting opening balances: + + ; starting a new journal, set asset account balances + 2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + + ; no cash left; update balance, record any untracked spending as a generic expense + 2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the commodity + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- + ment). Note that using balance assignments makes your journal a little + less explicit; to know the exact amount posted, you have to run hledger + or do the calculations yourself, instead of just reading it. + + Balance assignments and prices + A transaction price in a balance assignment will cause the calculated + amount to have that price attached: + + 2019/1/1 + (a) = $1 @ EUR2 + + $ hledger print --explicit + 2019-01-01 + (a) $1 @ EUR2 = $1 @ EUR2 + + 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: + + o subdirective - Some directives support subdirectives, written + indented below the parent directive. + + o decimal mark - The character to interpret as a decimal mark (period + or comma) when parsing amounts of a commodity. + + o display style - How to display amounts of a commodity in output: sym- + bol side and spacing, digit groups, decimal mark, and number of deci- + mal places. + + Directives are not required when starting out with hledger, but you + will probably add some as your needs grow. Here is an overview of + directives by purpose: + + + purpose directives command line + options with sim- + ilar effect + ----------------------------------------------------------------------------- + READING/GENERATING DATA: + Declare a commodity's or file's commodity, D, decimal- + decimal mark to help parse mark + amounts accurately + Apply changes to the data while alias, apply account, --alias + parsing comment, D, Y + Inline extra data files include multiple + -f/--file's + Generate extra transactions or ~ + budget goals + Generate extra postings = + CHECKING FOR ERRORS: + Define valid entities to allow account, commodity, + stricter error checking payee + DISPLAYING REPORTS: + Declare accounts' display order account + and accounting type + Declare commodity display commodity, D -c/--commodity- + styles style + + And here are all the directives and their precise effects: + + + direc- effects ends + tive at + file + end? + ---------------------------------------------------------------------------------- + account Declares an account, for checking all entries in all files; + and its display order and type, for reports. Subdirectives: + any text, ignored. + alias Rewrites account names, in following entries until end of Y + current file or end aliases. + apply Prepends a common parent account to all account names, in Y + account following entries until end of current file or end apply + account. + comment Ignores part of the journal file, until end of current file Y + or end comment. + commod- Declares a commodity, for checking all entries in all files; N, Y + ity the decimal mark for parsing amounts of this commodity, for + following entries until end of current file; and its display + style, for reports. Takes precedence over D. Subdirectives: + format (alternate syntax). + D Sets a default commodity to use for no-symbol amounts, and Y + its decimal mark for parsing amounts of this commodity in + following entries until end of current file; and its display + style, for reports. + deci- Declares the decimal mark, for parsing amounts of all com- Y + mal- modities in following entries until next decimal-mark or end + mark of current file. Included files can override. Takes prece- + dence over commodity and D. + include Includes entries and directives from another file, as if they + were written inline. + payee Declares a payee name, for checking all entries in all files. + P Declares a market price for a commodity on some date, for + valuation reports. + Y Declares a year for yearless dates, for following entries Y + until end of current file. + ~ Declares a periodic transaction rule that generates future + (tilde) transactions with --forecast and budget goals with balance + --budget. + = Declares an auto posting rule that generates extra postings partly + (equals) on matched transactions with --auto, in current, parent, and + child files (but not sibling files, see #1212). + + 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 sta- + ble 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 direc- + tives do not affect parent or sibling files (see below). + + Comment blocks + A line containing just comment starts a commented region of the file, + and a line containing just end comment (or the end of the current file) + ends it. See also comments. + + Including other files + You can pull in the content of additional files by writing an include + 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, overrid- + ing the file extension (as described in hledger.1 -> Input files): + include timedot:~/notes/2020*.md. + + Default year + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. + Eg: + + Y2009 ; set default year to 2009 + + 12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + + Y2010 ; change default year to 2010 + + 2009/1/30 ; specifies the year, not affected + expenses 1 + assets + + 1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Declaring payees + The payee 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 + + Declaring the decimal mark + 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). + + Declaring commodities + 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 Com- + modity 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 dec- + imal 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 subdirec- + tive, 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 + + 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. + + 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 cur- + rently 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. + + Default commodity + The D directive sets a default commodity, to be used for any subsequent + commodityless amounts (ie, plain numbers) seen while parsing the jour- + nal. 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). + + The syntax is D AMOUNT. As with commodity, 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 + + If both commodity and D directives are found for a commodity, commodity + takes precedence for setting decimal mark and display style. + + If you are using D and also checking commodities, you will need to add + a commodity directive similar to the D. (The hledger check commodities + command expects commodity directives, and ignores D). + + Declaring market prices + The P directive declares a market price, which is an exchange rate + between two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, + cryptocurrency exchange, or the 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 EUR $1.35 + + # and $1.40 from 2010-01-01 onward: + P 2010-01-01 EUR $1.40 + + The -V, -X and --value flags use these market prices to show amount + values in another commodity. See Valuation. + + Declaring accounts + account directives can be used to declare accounts (ie, the places that + amounts are transferred from and to). Though not required, these dec- + larations can provide several benefits: + + o They can document your intended chart of accounts, providing a refer- + ence. + + o They control account display order in reports, allowing non-alpha- + betic sorting (eg Revenues to appear above Expenses). + + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and + incomestatement. + + o They can store other account information, as comments or as tags + which can be used to filter reports. + + o They help with account name completion (in hledger add, hledger-web, + hledger-iadd, ledger-mode, etc.) + + o In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + + The simplest form is just the word account followed by a hledger-style + account name, eg this account directive declares the assets:bank:check- + ing account: + + account assets:bank:checking + + Account error checking + By default, accounts come into existence when a transaction references + them by name. 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 + the error later, as an extra account in balance reports, or an incor- + rect 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: + + o The declaration is case-sensitive; transactions must use the correct + account name capitalisation. + + o The account directive's scope is "whole file and below" (see direc- + tives). 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. + + o Accounts can only be declared in journal files (but will affect + included files in other formats). + + o It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + Account comments + Comments, beginning with a semicolon, can be added: + + o on the same line, after two or more spaces (because ; is allowed in + account names) + + o on the next lines, indented + + An example of both: + + account assets:bank:checking ; same-line comment, note 2+ spaces required before ; + ; next-line comment + ; some tags, type:A, acctnum:12345 + + Compatibility note: same-line comments are not supported by Ledger or + hledger <1.13. + + Account subdirectives + We also allow (and ignore) Ledger-style indented subdirectives, just + for compatibility.: + + account assets:bank:checking + format blah blah ; <- subdirective, ignored + + Here is the full syntax of account directives: + + account ACCTNAME [;type:ACCTTYPE] [COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] + + 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: + + o A or Asset (things you own) + + o L or Liability (things you owe) + + o E or Equity (investment/ownership; balanced counterpart of assets & + liabilities) + + o R or Revenue (what you received money from, AKA income; technically + part of Equity) + + o X or Expense (what you spend money on; technically part of Equity) + + or, it can be (these are used less often): + + o C or Cash (a subtype of Asset, indicating liquid assets for the cash- + flow report) + + o V or Conversion (a subtype of Equity, for conversions (see CONVERSION + & COST).) + + 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. + + o 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. Note the Cash regexp changed + in hledger 1.24.99.2. + + 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 + + o If you declare any account types, it's a good idea to declare an + account for each of them, because a mixture of declared and name- + inferred types can disrupt certain reports. + + o Certain uses of account aliases can disrupt account types. See + Rewriting accounts > Aliases and account types. + + o 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. + + o For troubleshooting, you can list accounts and their types with: + + $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] + + Account display order + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web + sidebar. By default accounts are listed in alphabetical order. But if + you have these account directives in the journal: + + account assets + account liabilities + account equity + account revenues + account expenses + + you'll see those accounts displayed in declaration order, not alphabet- + ically: + + $ hledger accounts -1 + assets + liabilities + equity + revenues + expenses + + Undeclared accounts, if any, are displayed last, in alphabetical order. + + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, + 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: + + o you will sometimes declare parent accounts (eg account other above) + that you don't intend to post to, just to customize their display + order + + o sibling accounts stay together (you couldn't display x:y in between + a:b and a:c). + + Rewriting accounts + You can define account alias rules which rewrite your account names, or + parts of them, before generating reports. This can be useful for: + + o expanding shorthand account names to their full form, allowing easier + data entry and a less verbose journal + + o adapting old journals to your current chart of accounts + + o experimenting with new account organisations, like a new hierarchy + + o combining two accounts into one, eg to see their sum or difference on + one line + + o 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 cor- + rectly, but you can also generate invalid account names with them; more + on this below. + + See also Rewrite account names. + + Basic aliases + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its + included files (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. Sub- + accounts are also affected. Eg: + + alias checking = assets:bank:wells fargo:checking + ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + Regex aliases + There is also a more powerful variant that uses a regular expression, + 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. + + 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: + + o the nearest alias declaration before/above the entry is applied first + + o the next alias before/above that will be be applied next, and so on + + o aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- + pendent 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. + + 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 + + end aliases + You can clear (forget) all currently defined aliases (seen in the jour- + nal so far, or defined on the command line) with this directive: + + end aliases + + 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 exam- + ple, 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 + + 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, renam- + ing 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 + + Default parent account + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and + end apply account directives like so: + + apply account home + + 2010/1/1 + food $10 + cash + + end apply account + + which is equivalent to: + + 2010/01/01 + home:food $10 + home:cash $-10 + + If end apply account is omitted, the effect lasts to the end of the + file. Included files are also affected, eg: + + apply account business + include biz.journal + end apply account + apply account personal + include personal.journal + + Prior to hledger 1.0, legacy account and end spellings were also sup- + ported. + + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent + account. + + Periodic transactions + Periodic transaction rules describe transactions that recur. They + allow hledger to generate temporary future transactions to help with + forecasting, so you don't have to write out each one in the journal, + and it's easy to try out different forecasts. + + 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-fore- + casted 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. + + Periodic transaction rules also have a second meaning: they are used to + define budget goals, shown in budget reports. + + 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.): + + ~ monthly + expenses:rent $2000 + assets:bank:checking + + There is an additional constraint on the period expression: the start + date must fall on a natural boundary of the interval. Eg monthly from + 2018/1/1 is valid, but monthly from 2018/1/15 is not. + + 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. + + 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 acciden- + tally 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, + + o Do write two spaces between your period expression and your transac- + tion description, if any. + + o Don't accidentally write two spaces in the middle of your period + expression. + + Forecasting with periodic transactions + The --forecast flag activates any periodic transaction rules in the + journal. These will generate temporary additional transactions, usu- + ally 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-transac- + tion:, which you can use to reliably match transactions generated "just + now" (rather than printed 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: + + o the start date provided within --forecast's argument, if any + + o otherwise, the later of + + o the report start date, if specified (with -b/-p/date:) + + o the day after the latest ordinary transaction in the journal, if + any + + o otherwise today. + + It ends on: + + o the end date provided within --forecast's argument, if any + + o otherwise, the report end date, if specified (with -e/-p/date:) + + o 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: + + o 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. + + o 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: + + o You must use = between flag and argument; a space won't work. + + o The period expression can specify the forecast period's start date, + end date, or both. See also Report start & end date. + + o The period expression should not specify a report interval. (Each + periodic transaction rule specifies its own interval.) + + Some examples: --forecast=202001-202004, --forecast=jan-, --fore- + cast=2021. + + Budgeting with periodic transactions + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- + pared in budget reports. + + See also: Budgeting and Forecasting. + + + Auto postings + "Automated postings" or "auto postings" are extra postings which get + added automatically to transactions which match certain queries, + defined by "auto posting rules", when you use the --auto flag. + + 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 match- + ing), followed by a query (which matches existing postings), and each + "posting" line describes a posting to be generated, and the posting + amounts can be: + + o a normal amount with a commodity symbol, eg $2. This will be used + as-is. + + o a number, eg 2. The commodity symbol (if any) from the matched post- + ing will be added to this. + + o 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. + + o 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 + + 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). + + 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. + + Auto postings and transaction balancing / inferred amounts / balance asser- + tions + Currently, auto postings are added: + + o after missing amounts are inferred, and transactions are checked for + balancedness, + + o but before balance assertions are checked. + + Note this means that journal entries must be balanced both before and + after auto postings are added. This changed in hledger 1.12+; see #893 + for background. + + 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. + + Auto posting tags + Automated postings will have some extra tags: + + o generated-posting:= QUERY - shows this was generated by an auto post- + ing rule, and the query + + o _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: + + o modified: - this transaction was modified + + o _modified: - a hidden tag not appearing in the comment; this transac- + tion was modified "just now". + +CSV FORMAT + How hledger reads CSV data, and the CSV rules file format. + + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records as if they were journal + files, automatically converting each CSV record into a transaction. + + (To learn about writing CSV, see CSV output.) + + We describe each CSV file's format with a corresponding rules file. By + default this is named like the CSV file with a .rules extension added. + Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the + same directory as FILE.csv. You can specify a different rules file + with the --rules-file option. If a rules file is not found, hledger + will create a sample rules file, which you'll need to adjust. + + This file contains rules describing the CSV data (header line, fields + layout, date format etc.), and how to construct hledger journal entries + (transactions) from it. Often there will also be a list of conditional + rules for categorising transactions based on their descriptions. + Here's an overview of the CSV rules; these are described more fully + below, after the examples: + + + skip skip one or more header lines or matched CSV + records + fields list name CSV fields, assign them to hledger + fields + field assignment assign a value to one hledger field, with + interpolation + Field names hledger field names, used in the fields list + and field assignments + separator a custom field separator + if block apply some rules to CSV records matched by + patterns + if table apply some rules to CSV records matched by + patterns, alternate syntax + end skip the remaining CSV records + date-format how to parse dates in CSV records + decimal-mark the decimal mark used in CSV amounts, if + ambiguous + newest-first disambiguate record order when there's only + one date + include inline another CSV rules file + balance-type choose which type of balance assignments to + use + + Note, for best error messages when reading CSV files, use a .csv, .tsv + or .ssv file extension or file prefix - see File Extension below. + + There's an introductory Convert CSV files tutorial on hledger.org. + + Examples + Here are some sample hledger CSV rules files. See also the full col- + lection at: + https://github.com/simonmichael/hledger/tree/master/examples/csv + + Basic + 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 + + Default account names are chosen, since we didn't set them. + + 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 neces- + sary 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 read- + ing directly from CSV, but they will be checked if these entries are + imported into a journal file. + + Amazon + Here we convert amazon.com order history, and use an if block to gener- + ate 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 + + 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: + + CSV rules + The following kinds of rule can appear in the rules file, in any order. + Blank lines and lines beginning with # or ; are ignored. + + skip + skip N + + The word "skip" followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines preceding the CSV data. + (Empty/blank lines are skipped automatically.) You'll need this when- + ever your CSV data contains header lines. + + It also has a second purpose: it can be used inside if blocks to ignore + certain CSV records (described below). + + fields list + fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word "fields" followed by comma-separated field + names) is the quick way to assign CSV field values to hledger fields. + (The other way is field assignments, see below.) A fields list does + does two things: + + 1. It names the CSV fields. This is optional, but can be convenient + later for interpolating them. + + 2. Whenever you use a standard hledger field name (defined below), the + CSV value is assigned to that part of the hledger 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 + + Tips: + + o The fields list always use commas, even if your CSV data uses another + separator character. + + o Currently there must be least two items in the list (at least one + comma). + + o Field names may not contain spaces. Spaces before/after field names + are optional. + + o Field names may contain _ (underscore) or - (hyphen). + + o If the CSV contains column headings, it's a good idea to use these, + suitably modified, as the basis for your field names (eg lower-cased, + with underscores instead of spaces). + + o If some heading names match standard hledger fields, but you don't + want to set the hledger fields directly, alter those names, eg by + appending an underscore. + + o Fields you don't care about can be given a dummy name (eg: _ ), or no + name. + + field assignment + HLEDGERFIELDNAME 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 inter- + polate CSV fields, referenced by their 1-based position in the CSV + record (%N), or by the name they were given in the fields list (%CSV- + FIELDNAME). + + 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: + + o Interpolation strips outer whitespace (so a CSV value like " 1 " + becomes 1 when interpolated) (#1051). + + o Interpolations always refer to a CSV field - you can't interpolate a + hledger field. (See Referencing other fields below). + + Field names + Here are the standard hledger field (and pseudo-field) names, which you + can use in a fields list and in field assignments. For more about the + transaction parts they refer to, see Transactions. + + date field + Assigning to date sets the transaction date. + + date2 field + date2 sets the transaction's secondary date, if any. + + status field + status sets the transaction's status, if any. + + code field + code sets the transaction's code, if any. + + description field + description sets the transaction's description, if any. + + comment field + comment sets the transaction's comment, if any. + + commentN, where N is a number, sets the Nth posting's comment. + + Tips: + + o You can assign multi-line comments by writing literal \n in the code. + A comment starting with \n will begin on a new line. + + o Comments can contain tags, as usual. + + 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, and in conditional blocks. + + 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"). + + amount field + 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. + + amountN-in and amountN-out can be used instead, if the CSV uses sepa- + rate fields for debits and credits (inflows and outflows). hledger + assumes both of these CSV fields are unsigned, and will automatically + negate the "-out" value. If they are signed, see "Setting amounts" + below. + + amount, or amount-in and amount-out are a legacy mode, to keep pre- + hledger-1.17 CSV rules files working (and for occasional convenience). + They are suitable only for two-posting transactions; they set both + posting 1's and posting 2's amount. Posting 2's amount will be + negated, and also converted to cost if there's a transaction price. + + If you have an existing rules file using the unnumbered form, you might + want to use the numbered form in certain conditional blocks, without + having to update and retest all the old rules. To facilitate this, + posting 1 ignores amount/amount-in/amount-out if any of + amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them + if any of amount2/amount2-in/amount2-out are assigned, avoiding con- + flicts. + + 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. + + 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. + + separator + You can use the separator rule to read other kinds of character-sepa- + rated 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 automat- + ically, and you won't need this rule. + + if block + if MATCHER + RULE + + if + MATCHER + MATCHER + MATCHER + RULE + RULE + + Conditional blocks ("if blocks") are a block of rules that are applied + only to CSV records which match certain patterns. They are often used + for customising account names based on transaction descriptions. + + Matching the whole record + Each MATCHER can be a record matcher, which looks like this: + + REGEX + + REGEX is a case-insensitive regular expression that tries to match any- + where within the CSV record. It is a POSIX ERE (extended regular + expression) that also supports GNU word boundaries (\b, \B, \<, \>), + and nothing else. If you have trouble, be sure to check our doc: + https://hledger.org/hledger.html#regular-expressions + + Important note: the record that is matched is not the original record, + but a synthetic one, with any enclosing double quotes (but not enclos- + ing whitespace) removed, and always comma-separated (which means that a + field containing a comma will appear like two fields). Eg, if the + original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will + actually see 2020-01-01,Acme, Inc., 1,000). + + Matching individual fields + Or, MATCHER can be a field matcher, like this: + + %CSVFIELD REGEX + + which matches just the content of a particular CSV field. CSVFIELD is + a percent sign followed by the field's name or column number, like + %date or %1. + + Combining matchers + A single matcher can be written on the same line as the "if"; or multi- + ple matchers can be written on the following lines, non-indented. Mul- + tiple matchers are OR'd (any one of them can match), unless one begins + with an & symbol, in which case it is AND'ed with the previous matcher. + + if + MATCHER + & MATCHER + RULE + + Rules applied on successful match + After the patterns there should be one or more rules to apply, all + indented by at least one space. Three kinds of rule are allowed in + conditional blocks: + + o field assignments (to set a hledger field) + + o skip (to skip the matched CSV record) + + o end (to skip all remaining CSV records). + + Examples: + + # if the CSV record contains "groceries", set account2 to "expenses:groceries" + if groceries + account2 expenses:groceries + + # if the CSV record contains any of these patterns, set account2 and comment as shown + if + monthly service fee + atm transaction fee + banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + if table + if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn + MATCHER1,VALUE11,VALUE12,...,VALUE1n + MATCHER2,VALUE21,VALUE22,...,VALUE2n + MATCHER3,VALUE31,VALUE32,...,VALUE3n + + + Conditional tables ("if tables") are a different syntax to specify + field assignments that will be applied only to CSV records which match + certain patterns. + + MATCHER could be either field or record matcher, as described above. + When MATCHER matches, values from that row would be assigned to the CSV + fields named on the if line, in the same order. + + Therefore if table is exactly equivalent to a sequence of of if blocks: + + if MATCHER1 + CSVFIELDNAME1 VALUE11 + CSVFIELDNAME2 VALUE12 + ... + CSVFIELDNAMEn VALUE1n + + if MATCHER2 + CSVFIELDNAME1 VALUE21 + CSVFIELDNAME2 VALUE22 + ... + CSVFIELDNAMEn VALUE2n + + if MATCHER3 + CSVFIELDNAME1 VALUE31 + CSVFIELDNAME2 VALUE32 + ... + CSVFIELDNAMEn VALUE3n + + Each line starting with MATCHER should contain enough (possibly empty) + values for all the listed fields. + + Rules would be checked and applied in the order they are listed in the + table and, like with if blocks, later rules (in the same or another ta- + ble) or if blocks could override the effect of any rule. + + Instead of ',' you can use a variety of other non-alphanumeric charac- + ters as a separator. First character after if is taken to be the sepa- + rator for the rest of the table. It is the responsibility of the user + to ensure that separator does not occur inside MATCHERs and values - + there is no way to escape separator. + + 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 + + end + This rule can be used inside if blocks (only), to make hledger stop + reading this CSV file and move on to the next input file, or to command + execution. Eg: + + # ignore everything following the first empty record + if ,,,, + end + + 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 date + parsing pattern, which 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 + + For the supported strptime syntax, see: + https://hackage.haskell.org/package/time/docs/Data-Time-For- + mat.html#v:formatTime + + Note that although you can parse date-times which include a time zone, + that time zone is ignored; it will not change the date that is parsed. + This means when reading CSV data with times not in your local time + zone, dates can be "off by one". + + 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. + + newest-first + hledger always sorts the generated transactions by date. Transactions + on the same date should appear in the same order as their CSV records, + as hledger can usually auto-detect whether the CSV's normal order is + oldest first or newest first. But if all of the following are true: + + o the CSV might sometimes contain just one day of data (all records + having the same date) + + o the CSV records are normally in reverse chronological order (newest + at the top) + + o and you care about preserving the order of same-day transactions + + then, you should add the newest-first rule as a hint. Eg: + + # tell hledger explicitly that the CSV is normally newest first + newest-first + + 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 + + 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 + + Tips + 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. + + Valid CSV + hledger accepts CSV conforming to RFC 4180. When CSV values are + enclosed in quotes, note: + + o they must be double quotes (not single quotes) + + o spaces outside the quotes are not allowed + + File Extension + To help hledger identify the format and show the right error messages, + CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv + filename extension. Or, the file path should be prefixed with csv:, + ssv: or tsv:. Eg: + + $ hledger -f foo.ssv print + + or: + + $ cat foo | hledger -f ssv:- foo + + You can override the file extension with a separator rule if needed. + See also: Input files in the hledger manual. + + 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. + + Valid transactions + After reading a CSV file, hledger post-processes and validates the gen- + erated 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 + + 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: + + o https://hledger.org/cookbook.html#setups-and-workflows + + o https://plaintextaccounting.org -> data import/conversion + + Setting amounts + Some tips on using the amount-setting rules discussed above. + + Here are the ways to set a posting's amount: + + 1. If the CSV has a single amount field: + Assign (via a fields list or a field assignment) to amountN. This sets + the Nth posting's amount. N is usually 1 or 2 but can go up to 99. + + 2. If the CSV has separate amount fields for debit & credit (in & out): + + a. If both fields are unsigned: + Assign to amountN-in and amountN-out. This sets posting N's amount + to whichever of these has a non-zero value, and negates the "-out" + value. + + b. If either field is signed (can contain a minus sign): + Use a conditional rule to flip the sign (of non-empty values). + Since hledger always negates amountN-out, if it was already nega- + tive, we must undo that by negating once more (but only if the + field is non-empty): + + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. If both fields, or neither field, can contain a non-zero value: + hledger normally expects exactly one of the fields to have a non- + zero value. Eg, the amountN-in/amountN-out rules would reject + value pairs like these: + + "", "" + "0", "0" + "1", "none" + + So, use smarter conditional rules to set the amount from the appro- + priate field. Eg, these rules would make it use only the value + containing non-zero digits, handling the above: + + 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: + Assign to amount (or to amount-in and amount-out). (This is the legacy + numberless syntax, which sets amount1 and amount2 and converts amount2 + to cost.) + + 4. If the CSV has the balance instead of the transaction amount: + Assign to balanceN, which sets posting N's amount indirectly via a bal- + ance assignment. (Old syntax: balance, equivalent to balance1.) + + o If hledger guesses the wrong default account name: + When setting the amount via balance assertion, hledger may guess + the wrong default account name. So, set the account name explic- + itly, eg: + + fields date, description, balance1 + account1 assets:checking + + Amount signs + There is some special handling for amount signs, to simplify parsing + and sign-flipping: + + o If an amount value begins with a plus sign: + that will be removed: +AMT becomes AMT + + o If an amount value is parenthesised: + it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT + + o 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 + + o If an amount value contains just a sign (or just a set of parenthe- + ses): + that is removed, making it an empty value. "+" or "-" or "()" becomes + "". + + 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. + + 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 deci- + mal 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). + + 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 lit- + eral "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 + + How CSV rules are evaluated + Here's how to think of CSV rules being evaluated (if you really need + to). First, + + o 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: + + o skip (at top level) + + o date-format + + o newest-first + + o fields - names the CSV fields, optionally sets up initial assignments + to hledger fields + + Then for each CSV record in turn: + + o 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. + + o 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. + + o compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELDNAME references), or a + default + + o generate a synthetic hledger transaction 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. + +TIMECLOCK FORMAT + 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). + + i 2015/03/30 09:00:00 some:account name optional description after two spaces + o 2015/03/30 09:20:00 + i 2015/03/31 22:21:45 another account + o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For + the above time log, hledger print generates these journal entries: + + $ hledger -f t.timeclock print + 2015-03-30 * optional description after two spaces + (some:account name) 0.33h + + 2015-03-31 * 22:21-23:59 + (another account) 1.64h + + 2015-04-01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + + $ hledger -f sample.timeclock balance # current time balances + $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 + $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + o use emacs and the built-in timeclock.el, or the extended timeclock- + x.el and perhaps the extras in ledgerutils.el + + o at the command line, use these bash aliases: shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" + + o or use the old ti and to scripts in the ledger 2.x repository. These + rely on a "timeclock" executable which I think is just the ledger 2 + executable renamed. + +TIMEDOT FORMAT + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is + + o convenient for quick, approximate, and retroactive time logging + + o 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: + + o 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 + + o a common transaction description for this day + + o a common transaction comment for this day, after a semicolon (;). + + After the date line are zero or more optionally-indented time transac- + tion lines, consisting of: + + o an account name - any word or phrase, usually a hledger-style account + name. + + o two or more spaces - a field separator, required if there is an + amount (as in journal format). + + o a timedot amount - dots representing quarter hours, or a number rep- + resenting hours. + + o an optional comment beginning with semicolon. This is ignored. + + In more detail, timedot amounts can be: + + o dots: zero or more period characters, each representing one quarter- + hour. Spaces are ignored and can be used for grouping. Eg: .... .. + + o a number, representing hours. Eg: 1.5 + + o 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.: + + o Lines beginning with # or ;, and blank lines, are ignored. + + o Lines not ending with a double-space and amount are parsed as trans- + actions with zero amount. (Most hledger reports hide these by + default; add -E to see them.) + + o One or more stars (*) followed by a space, at the start of a line, is + ignored. So date lines or time transaction lines can also be Org- + mode headlines. + + o All Org-mode headlines before the first date line are ignored. + + 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. + +COMMON TASKS + Here are some quick examples of how to do some basic tasks with + hledger. For more details, see the reference section below, the + hledger_journal(5) manual, or the more extensive docs at + https://hledger.org. + + Getting help + $ hledger # show available commands + $ hledger --help # show common options + $ hledger CMD --help # show common and command options, and command help + $ hledger help # show available manuals/topics + $ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) + $ hledger help journal -m # show the journal topic, as a man page scrolled to that section + $ hledger help --help # show more detailed help for the help command + + Find more docs, chat, mail list, reddit, issue tracker: + https://hledger.org/support.html-feedback + + Constructing command lines + hledger has an extensive and powerful command line interface. We + strive to keep it simple and ergonomic, but you may run into one of the + confusing real world details described in OPTIONS, below. If that hap- + pens, here are some tips that may help: + + o command-specific options must go after the command (it's fine to put + all options there) (hledger CMD OPTS ARGS) + + o running add-on executables directly simplifies command line parsing + (hledger-ui OPTS ARGS) + + o enclose "problematic" args in single quotes + + o if needed, also add a backslash to hide regular expression metachar- + acters from the shell + + o to see how a misbehaving command is being parsed, add --debug=2. + + 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 () + + 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 bal- + ances on this date. Here are two ways to do it: + + o 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. + + o 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 + + 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 + + Reconciling + Periodically you should reconcile - compare your hledger-reported bal- + ances 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 dis- + crepancies. + + 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 check- + ing -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 trans- + action 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 --reg- + ister 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 com- + mit: + + $ git commit -m 'txns' 2020.journal + + 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 --flat -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 --flat -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 **** + + 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. + +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 file format + differences. + + On large data files, hledger is slower and uses more memory than + Ledger. + +TROUBLESHOOTING + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug + tracker): + + Successfully installed, but "No command 'hledger' found" + stack and cabal install binaries into a special directory, which should + be added to your PATH environment variable. Eg on unix-like systems, + that is ~/.local/bin and ~/.cabal/bin respectively. + + I set a custom LEDGER_FILE, but hledger is still using the default file + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may + need to use export. Here's an explanation. + + Getting errors like "Illegal byte sequence" or "Invalid or incomplete + multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- + ment (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 sup- + ports 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 differ- + ence 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 + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2020 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + + +hledger-1.26.1 July 2022 HLEDGER(1) diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "June 2022" "hledger-1.26 " "hledger User Manuals" +.TH "HLEDGER" "1" "July 2022" "hledger-1.26.1 " "hledger User Manuals" @@ -9,7 +9,7 @@ This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger\[aq]s concepts and file formats. -This manual is for hledger 1.26. +This manual is for hledger 1.26.1. .SH SYNOPSIS .PP \f[C]hledger\f[R] @@ -4436,10 +4436,11 @@ shown with normal positive sign, as in conventional financial statements. .PP -The asset and liability accounts shown are those accounts declared with -the \f[C]Asset\f[R] or \f[C]Cash\f[R] or \f[C]Liability\f[R] type, or -otherwise all accounts under a top-level \f[C]asset\f[R] or -\f[C]liability\f[R] account (case insensitive, plurals allowed). +This report shows accounts declared with the \f[C]Asset\f[R], +\f[C]Cash\f[R] or \f[C]Liability\f[R] type (see account types). +Or if no such accounts are declared, it shows top-level accounts named +\f[C]asset\f[R] or \f[C]liability\f[R] (case insensitive, plurals +allowed) and their subaccounts. .PP Example: .IP @@ -4487,11 +4488,12 @@ Amounts are shown with normal positive sign, as in conventional financial statements. .PP -The asset, liability and equity accounts shown are those accounts -declared with the \f[C]Asset\f[R], \f[C]Cash\f[R], \f[C]Liability\f[R] -or \f[C]Equity\f[R] type, or otherwise all accounts under a top-level -\f[C]asset\f[R], \f[C]liability\f[R] or \f[C]equity\f[R] account (case -insensitive, plurals allowed). +This report shows accounts declared with the \f[C]Asset\f[R], +\f[C]Cash\f[R], \f[C]Liability\f[R] or \f[C]Equity\f[R] type (see +account types). +Or if no such accounts are declared, it shows top-level accounts named +\f[C]asset\f[R], \f[C]liability\f[R] or \f[C]equity\f[R] (case +insensitive, plurals allowed) and their subaccounts. .PP Example: .IP @@ -4545,22 +4547,15 @@ Amounts are shown with normal positive sign, as in conventional financial statements. .PP -\[dq]Cash\[dq] assets are those accounts which are (or whose parents -are) declared as \f[C]Cash\f[R] by an account directive, like this: -.IP -.nf -\f[C] -account some:liquid:asset ; type:C -\f[R] -.fi -.PP -Or if there are no such declarations, all accounts +This report shows accounts declared with the \f[C]Cash\f[R] type (see +account types). +Or if no such accounts are declared, it shows accounts .IP \[bu] 2 -under a top-level \f[C]asset\f[R] account (case insensitive, plural -allowed) +under a top-level account named \f[C]asset\f[R] (case insensitive, +plural allowed) .IP \[bu] 2 -with some variation of \f[C]cash\f[R], \f[C]bank\f[R], -\f[C]checking\f[R] or \f[C]saving\f[R] in their name. +whose name contains some variation of \f[C]cash\f[R], \f[C]bank\f[R], +\f[C]checking\f[R] or \f[C]saving\f[R]. .PP More precisely: all accounts matching this case insensitive regular expression: @@ -5255,16 +5250,16 @@ .PD 0 .P .PD -.PP 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. .PP -The revenue and expense accounts shown are those accounts declared with -the \f[C]Revenue\f[R] or \f[C]Expense\f[R] type, or otherwise all -accounts under a top-level \f[C]revenue\f[R] or \f[C]income\f[R] or -\f[C]expense\f[R] account (case insensitive, plurals allowed). +This report shows accounts declared with the \f[C]Revenue\f[R] or +\f[C]Expense\f[R] type (see account types). +Or if no such accounts are declared, it shows top-level accounts named +\f[C]revenue\f[R] or \f[C]income\f[R] or \f[C]expense\f[R] (case +insensitive, plurals allowed) and their subaccounts. .PP Example: .IP 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.26 +version: 1.26.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 @@ -134,7 +134,7 @@ other-modules: Paths_hledger ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-name-shadowing -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.26" + cpp-options: -DVERSION="1.26.1" build-depends: Decimal >=0.5.1 , Diff @@ -151,7 +151,7 @@ , githash >=0.1.4 , hashable >=1.2.4 , haskeline >=0.6 - , hledger-lib ==1.26.* + , hledger-lib >=1.26.1 && <1.27 , lucid , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.3 @@ -159,7 +159,7 @@ , mtl >=2.2.1 , process , regex-tdfa - , safe >=0.2 + , safe >=0.3.19 , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2 @@ -185,7 +185,7 @@ hs-source-dirs: app ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-name-shadowing -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.26" + cpp-options: -DVERSION="1.26.1" build-depends: Decimal >=0.5.1 , aeson >=1 @@ -201,14 +201,14 @@ , githash >=0.1.4 , haskeline >=0.6 , hledger - , hledger-lib ==1.26.* + , hledger-lib >=1.26.1 && <1.27 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.3 , microlens >=0.4 , mtl >=2.2.1 , process , regex-tdfa - , safe >=0.2 + , safe >=0.3.19 , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2 @@ -235,7 +235,7 @@ hs-source-dirs: test ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-name-shadowing -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.26" + cpp-options: -DVERSION="1.26.1" build-depends: Decimal >=0.5.1 , aeson >=1 @@ -251,14 +251,14 @@ , githash >=0.1.4 , haskeline >=0.6 , hledger - , hledger-lib ==1.26.* + , hledger-lib >=1.26.1 && <1.27 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.3 , microlens >=0.4 , mtl >=2.2.1 , process , regex-tdfa - , safe >=0.2 + , safe >=0.3.19 , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2 @@ -299,7 +299,7 @@ , githash >=0.1.4 , haskeline >=0.6 , hledger - , hledger-lib ==1.26.* + , hledger-lib >=1.26.1 && <1.27 , html , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.3 @@ -307,7 +307,7 @@ , mtl >=2.2.1 , process , regex-tdfa - , safe >=0.2 + , safe >=0.3.19 , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2 diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -13,10072 +13,10068 @@ This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger's concepts and file formats. This -manual is for hledger 1.26. - - 'hledger' - - 'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]' - - 'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]' - - hledger is a reliable, cross-platform set of programs for tracking -money, time, or any other commodity, using double-entry accounting and a -simple, editable file format. hledger is inspired by and largely -compatible with ledger(1). - - The basic function of the hledger CLI is to read a plain text file -describing financial transactions (in accounting terms, a general -journal) and print useful reports on standard output, or export them as -CSV. hledger can also read some other file formats such as CSV files, -translating them to journal format. Additionally, hledger lists other -hledger-* executables found in the user's $PATH and can invoke them as -subcommands. - - hledger reads data from one or more files in hledger journal, -timeclock, timedot, or CSV format specified with '-f', or -'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). If using '$LEDGER_FILE', note this -must be a real environment variable, not a shell variable. You can -specify standard input with '-f-'. - - Transactions are dated movements of money between two (or more) named -accounts, and are recorded with journal entries like this: - -2015/10/16 bought food - expenses:food $10 - assets:cash - - Most users use a text editor to edit the journal, usually with an -editor mode such as ledger-mode for added convenience. hledger's -interactive add command is another way to record new transactions. -hledger never changes existing transactions. - - To get started, you can either save some entries like the above in -'~/.hledger.journal', or run 'hledger add' and follow the prompts. Then -try some commands like 'hledger print' or 'hledger balance'. Run -'hledger' with no arguments for a list of commands. - -* Menu: - -* OPTIONS:: -* ENVIRONMENT:: -* DATA FILES:: -* TIME PERIODS:: -* DEPTH:: -* QUERIES:: -* CONVERSION & COST:: -* VALUATION:: -* PIVOTING:: -* OUTPUT:: -* COMMANDS:: -* JOURNAL FORMAT:: -* CSV FORMAT:: -* TIMECLOCK FORMAT:: -* TIMEDOT FORMAT:: -* COMMON TASKS:: -* LIMITATIONS:: -* TROUBLESHOOTING:: - - -File: hledger.info, Node: OPTIONS, Next: ENVIRONMENT, Prev: Top, Up: Top - -1 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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 - -1.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 directives and options: '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: DATA FILES, Prev: OPTIONS, Up: Top - -2 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\MyUserName\.hledger.journal'. You can change this by running -a command like this in a powershell window: - -> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - - (Let us know if you need to be an Administrator, and if this persists -across a reboot.) - - *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: DATA FILES, Next: TIME PERIODS, Prev: ENVIRONMENT, Up: Top - -3 DATA FILES -************ - -hledger reads transactions from one or more data files. The default -data file is '$HOME/.hledger.journal' (or on Windows, something like -'C:/Users/USER/.hledger.journal'). - - You can override this with the '$LEDGER_FILE' environment variable: - -$ setenv LEDGER_FILE ~/finance/2016.journal -$ hledger stats - - or with 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: DATA FILES - -3.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 their own sections, 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: DATA FILES - -3.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: DATA FILES - -3.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: TIME PERIODS, Next: DEPTH, Prev: DATA FILES, Up: Top - -4 TIME PERIODS -************** - -* Menu: - -* Smart dates:: -* Report start & end date:: -* Report intervals:: -* Period expressions:: - - -File: hledger.info, Node: Smart dates, Next: Report start & end date, Up: TIME PERIODS - -4.1 Smart dates -=============== - -hledger's user interfaces accept a flexible "smart date" syntax. Smart -dates allow some english words, can be relative to today's date, and can -have less-significant date parts omitted (defaulting to 1). - - Examples: - -'2004/10/1', 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 - - 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 - - Note "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; those are not affected by '--today'.) - - -File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: TIME PERIODS - -4.2 Report start & end date -=========================== - -By default, most hledger reports will show the full span of time -represented by the journal data. 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. - - 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. - * A report interval (see below) will adjust start/end dates, when - needed, so that they fall on subperiod boundaries. - - 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: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: TIME PERIODS - -4.3 Report intervals -==================== - -A report interval can be specified so that commands like register, -balance and activity become multi-period, showing each subperiod as a -separate row or column. - - The following "standard" report intervals can be enabled by using -their corresponding flag: - - * '-D/--daily' - * '-W/--weekly' - * '-M/--monthly' - * '-Q/--quarterly' - * '-Y/--yearly' - - These standard intervals always start on natural interval boundaries: -eg '--weekly' starts on mondays, '--monthly' starts on the first of the -month, '--yearly' always starts on January 1st, etc. - - Certain more complex intervals, and more flexible boundary dates, can -be specified by '-p/--period'. These are described in period -expressions, below. - - Report intervals can only be specified by the flags above, and not by -query arguments, currently. - - Report intervals have another effect: multi-period reports are always -expanded to fill a whole number of subperiods. So if you use a report -interval (other than '--daily'), and you have specified a start or end -date, you may notice those dates being overridden (ie, the report starts -earlier than your requested start date, or ends later than your -requested end date). This is done to ensure "full" first and last -subperiods, so that all subperiods' numbers are comparable. - - To summarise: - - * In multiperiod reports, all subperiods are forced to be the same - length, to simplify reporting. - * Reports with the standard - '--weekly'/'--monthly'/'--quarterly'/'--yearly' intervals are - required to start on the first day of a week/month/quarter/year. - We'd like more flexibility here but it isn't supported yet. - * '--period' (below) can specify more complex intervals, starting on - any date. - - -File: hledger.info, Node: Period expressions, Prev: Report intervals, Up: TIME PERIODS - -4.4 Period expressions -====================== - -The '-p/--period' option accepts period expressions, a shorthand way of -expressing a start date, end date, and/or report interval all at once. - - Here's a basic period expression specifying the first quarter of -2009. Note, hledger always treats start dates as inclusive and end -dates as exclusive: - -'-p "from 2009/1/1 to 2009/4/1"' - - Keywords like "from" and "to" are optional, and so are the spaces, as -long as you don't run two dates together. "to" can also be written as -".." or "-". These are equivalent to the above: - -'-p "2009/1/1 2009/4/1"' -'-p2009/1/1to2009/4/1' -'-p2009/1/1..2009/4/1' - - Dates are smart dates, so if the current year is 2009, the above can -also be written as: - -'-p "1/1 4/1"' -'-p "january-apr"' -'-p "this year to 4/1"' - - If you specify only one date, the missing start or end date will be -the earliest or latest transaction in your journal: - -'-p "from 2009/1/1"' everything after january 1, 2009 -'-p "from 2009/1"' the same -'-p "from 2009"' the same -'-p "to 2009"' everything before january 1, 2009 - - A single date with no "from" or "to" defines both the start and end -date like so: - -'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” -'-p "2009/1"' the month of jan; equivalent to “2009/1/1 to 2009/2/1” -'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2” - - Or you can specify a single quarter like so: - -'-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:: -* Intervals with custom start date:: -* Periods or dates ?:: -* Events on multiple weekdays:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -4.4.1 Period expressions with a report interval ------------------------------------------------ - -'-p/--period''s argument can also begin with, or entirely consist of, a -report interval. This should be separated from the start/end dates (if -any) by a space, or the word 'in'. The basic intervals (which can also -be written as command line flags) are 'daily', 'weekly', 'monthly', -'quarterly', and 'yearly'. Some examples: - -'-p "weekly from 2009/1/1 to 2009/4/1"' -'-p "monthly in 2008"' -'-p "quarterly"' - - As mentioned above, the 'weekly', 'monthly', 'quarterly' and 'yearly' -intervals require a report start date that is the first day of a week, -month, quarter or year. And, report start/end dates will be expanded if -needed to span a whole number of intervals. - - For example: - -'-p "weekly from starts on 2008/12/29, closest preceding -2009/1/1 to 2009/4/1"' Monday -'-p "monthly in starts on 2018/11/01 -2008/11/25"' -'-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, -2009-05-05 to which are first and last days of Q2 2009 -2009-06-01"' -'-p "yearly from starts on 2009/01/01, first day of 2009 -2009-12-29"' - - -File: hledger.info, Node: More complex report intervals, Next: Intervals with custom start date, Prev: Period expressions with a report interval, Up: Period expressions - -4.4.2 More complex report intervals ------------------------------------ - -Some more complex kinds of interval are also supported in period -expressions: - - * 'biweekly' - * 'fortnightly' - * 'bimonthly' - * 'every day|week|month|quarter|year' - * 'every N days|weeks|months|quarters|years' - - These too will cause report start/end dates to be expanded, if -needed, to span a whole number of intervals. Examples: - -'-p "bimonthly from periods will have boundaries on 2008/01/01, -2008"' 2008/03/01, ... -'-p "every 2 weeks"' starts on closest preceding Monday -'-p "every 5 months from periods will have boundaries on 2009/03/01, -2009/03"' 2009/08/01, ... - - -File: hledger.info, Node: Intervals with custom start date, Next: Periods or dates ?, Prev: More complex report intervals, Up: Period expressions - -4.4.3 Intervals with custom start date --------------------------------------- - -All intervals mentioned above are required to start on their natural -calendar boundaries, but the following intervals can start on any date: - - Weekly on 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 custom day: - - * 'every Nth day [of month]' - * 'every Nth WEEKDAYNAME [of month]' - - Yearly on 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 "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 period boundaries will be on second Monday of -Monday"' each month -'-p "every 11/05"' yearly periods with boundaries on 5th of - November -'-p "every 5th same -November"' -'-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: Periods or dates ?, Next: Events on multiple weekdays, Prev: Intervals with custom start date, Up: Period expressions - -4.4.4 Periods or dates ? ------------------------- - -Report intervals like the above are most often used with '-p|--period', -to divide reports into multiple subperiods - each generated date marks a -subperiod boundary. Here, the periods between the dates are what's -important. - - But report intervals can also be used with '--forecast' to generate -future transactions, or with 'balance --budget' to generate budget -goal-setting transactions. For these, the dates themselves are what -matters. - - -File: hledger.info, Node: Events on multiple weekdays, Prev: Periods or dates ?, Up: Period expressions - -4.4.5 Events on multiple weekdays ---------------------------------- - -The 'every WEEKDAYNAME' form has a special variant with multiple day -names, comma-separated. Eg: 'every mon,thu,sat'. Also, 'weekday' and -'weekendday' are shorthand for 'mon,tue,wed,thu,fri' and 'sat,sun' -respectively. - - This form 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. (Because gaps between periods are not allowed; if you'd like to -change this, see #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 - -5 DEPTH -******* - -With the '--depth NUM' option (short form: '-NUM'), commands like -account, balance and register will show only the uppermost accounts in -the account tree, down to level NUM. 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: CONVERSION & COST, Prev: DEPTH, Up: Top - -6 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 account aliases:: -* Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value:: - - -File: hledger.info, Node: Query types, Next: Combining query terms, Up: QUERIES - -6.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 - -6.2 Combining 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. - - while the print command shows transactions which: - - * match any of the description terms AND - * have any postings matching any of the positive account terms AND - * have no postings matching any of the negative account terms AND - * match all the other terms. - - You can do more powerful queries (such as AND-ing two like terms) by -running a first query with 'print', and piping the result into a second -hledger command. Eg: how much of food expenses was paid with cash ? - -$ hledger print assets:cash | hledger -f- -I balance expenses:food - - If you are interested in full boolean expressions for queries, see -#203. - - -File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Combining query terms, Up: QUERIES - -6.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 account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: QUERIES - -6.4 Queries and account aliases -=============================== - -When account names are rewritten with '--alias' or 'alias', 'acct:' will -match either the old or the new account name. - - -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and account aliases, Up: QUERIES - -6.5 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 - -6.6 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 - -6.7 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: CONVERSION & COST, Next: VALUATION, Prev: QUERIES, Up: Top - -7 CONVERSION & COST -******************* - -This section is about converting between commodities. Some definitions: - - * A "commodity conversion" is an exchange of one currency or - commodity for another. Eg a foreign currency exchange, or a - purchase or sale of stock or cryptocurrency. - - * A "conversion transaction" is a transaction involving one or more - such conversions. - - * "Conversion rate" is the exchange rate in a conversion - the cost - per unit of one commodity in the other. - - * "Cost" is how much of one commodity was paid to acquire the other - (when buying), or how much was received in exchange for the other - (when selling). We call both of these "cost" for convenience - (after all, it is cost for one party or the other). - -* Menu: - -* Recording conversions:: -* Inferring missing conversion rates:: -* Inferring missing equity postings:: -* Cost reporting:: -* Conversion summary:: - - -File: hledger.info, Node: Recording conversions, Next: Inferring missing conversion rates, Up: CONVERSION & COST - -7.1 Recording conversions -========================= - -As a concrete example, let's assume 100 EUR was converted to 120 USD. -There are several ways to record this in the journal, each with pros and -cons which will be explained in more detail below. (Also, these -examples use journal format which is properly explained much further -below; sorry about that, you may want to read some of that first.) - -* Menu: - -* Implicit conversion:: -* Priced conversion:: -* Equity conversion:: -* Priced equity conversion:: - - -File: hledger.info, Node: Implicit conversion, Next: Priced conversion, Up: Recording conversions - -7.1.1 Implicit conversion -------------------------- - -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: - - * Easy, concise - * hledger can do cost reporting - - Con: - - * Less error checking - typos in amounts or commodity symbols may not - be detected - * conversion rate is not clear - * disturbs the accounting equation - - 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: Priced conversion, Next: Equity conversion, Prev: Implicit conversion, Up: Recording conversions - -7.1.2 Priced conversion ------------------------ - -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 some error checking - * hledger can do cost reporting - - Con: - - * Disturbs the accounting equation - - -File: hledger.info, Node: Equity conversion, Next: Priced equity conversion, Prev: Priced conversion, Up: Recording conversions - -7.1.3 Equity conversion ------------------------ - -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 - * works in any double entry accounting system - - Con: - - * More verbose - * conversion rate is not clear - * hledger can not do cost reporting - - -File: hledger.info, Node: Priced equity conversion, Prev: Equity conversion, Up: Recording conversions - -7.1.4 Priced equity conversion ------------------------------- - -Another possible notation would be to record both the conversion rate -and the equity postings: - -2021-01-01 - assets:cash -100 EUR @ 1.20 USD - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - hledger currently does not allow this; instead, you can record the -conversion rate as a comment. - - -File: hledger.info, Node: Inferring missing conversion rates, Next: Inferring missing equity postings, Prev: Recording conversions, Up: CONVERSION & COST - -7.2 Inferring missing conversion rates -====================================== - -hledger will do this automatically for implicit conversions. Currently -it can not do this for equity conversions. - - -File: hledger.info, Node: Inferring missing equity postings, Next: Cost reporting, Prev: Inferring missing conversion rates, Up: CONVERSION & COST - -7.3 Inferring missing equity postings -===================================== - -With the '--infer-equity' flag, hledger will add equity postings to -priced and implicit conversions (and move the conversion rate into a -comment). - - -File: hledger.info, Node: Cost reporting, Next: Conversion summary, Prev: Inferring missing equity postings, Up: CONVERSION & COST - -7.4 Cost reporting -================== - -With the '-B/--cost' flag, hledger will convert the amounts in priced -and implicit conversions to their cost in the other commodity. This is -useful to see a report of what you paid for things (or how much you sold -things for). Currently '-B/--cost' does not work on equity conversions, -and it disables '--infer-equity'. - - These operations are transient, only affecting reports. If you want -to change the journal file permanently, you could pipe each entry -through 'hledger -f- -I print [-x] [--infer-equity] [-B]' - - -File: hledger.info, Node: Conversion summary, Prev: Cost reporting, Up: CONVERSION & COST - -7.5 Conversion summary -====================== - - * Recording the conversion rate is good because it makes that clear - and allows cost reporting. - * Recording equity postings is good because it balances the - accounting equation and is correct bookkeeping. - * Combining these is not yet supported, so you have to choose. For - now, priced conversions are a good compromise, so that: - * When you want to see the cost (or sale proceeds) of things, - use '-B/--cost'. - * When you want to see a balanced balance sheet or correct - journal entries, use '--infer-equity'. - * Combining these is not yet supported; '-B/--cost' will take - precedence. - - * Conversion/cost operations are performed before valuation. - - -File: hledger.info, Node: VALUATION, Next: PIVOTING, Prev: CONVERSION & COST, Up: Top - -8 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:: -* Market prices:: -* --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 - -8.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 - -8.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: Market prices, Prev: -X Value in specified commodity, Up: VALUATION - -8.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: Market prices, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: VALUATION - -8.4 Market prices -================= - -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 transaction prices. - - 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: Market prices, Up: VALUATION - -8.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 transaction prices as additional market -prices (as Ledger does) ? We could produce value reports without -needing P directives at all. - - 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. -(And 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.) - - * but not, currently, from "more correct" multicommodity transactions - (no '@', multiple commodities, balanced). - - There is another 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' - - -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: VALUATION - -8.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, transaction prices 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 - -8.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 - -8.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 - -8.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 - -8.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 - -8.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: PIVOTING, Next: OUTPUT, Prev: VALUATION, Up: Top - -9 PIVOTING -********** - -Normally hledger sums amounts, and organizes them in a hierarchy, based -on account name. The '--pivot FIELD' option causes it to sum and -organize hierarchy based on the value of some other field instead. -FIELD can be: 'status', 'code', 'description', 'payee', 'note', or the -full name (case insensitive) of any tag. As with account names, values -containing 'colon:separated:parts' will be displayed hierarchically in -reports. - - '--pivot' is a general option affecting all reports; you can think of -hledger transforming the journal before any other processing, replacing -every posting's account name with the value of the specified field on -that posting, inheriting it from the transaction or using a blank value -if it's not present. - - An example: - -2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees --------------------- - 0 - - Pivoted balance report, using member: tag values instead: - -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 - - One way to show only amounts with a member: value (using a query, -described below): - -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account -name"): - -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR - - -File: hledger.info, Node: OUTPUT, Next: COMMANDS, Prev: PIVOTING, Up: Top - -10 OUTPUT -********* - -* Menu: - -* Output destination:: -* Output styling:: -* Output format:: -* Commodity styles:: - - -File: hledger.info, Node: Output destination, Next: Output styling, Up: OUTPUT - -10.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) - - hledger can optionally produce debug output (if enabled with -'--debug=N'); this goes to stderr, and is not affected by -'-o/--output-file'. If you need to capture it, use shell redirects, eg: -'hledger bal --debug=3 >file 2>&1'. - - -File: hledger.info, Node: Output styling, Next: Output format, Prev: Output destination, Up: OUTPUT - -10.2 Output styling -=================== - -hledger commands can produce colour output when the terminal supports -it. This is controlled by the '--color/--colour' option: - 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. - - hledger commands can also use unicode box-drawing characters to -produce prettier tables and output. This is controlled by the -'--pretty' option: - 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: Output format, Next: Commodity styles, Prev: Output styling, Up: OUTPUT - -10.3 Output format -================== - -Some commands offer additional output formats, other than the usual -plain text terminal output. Here are those commands and the formats -currently supported: - -- txt csv html json sql ------------------------------------------------------------- -aregister 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 - -* Menu: - -* CSV output:: -* HTML output:: -* JSON output:: -* SQL output:: - - -File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format - -10.3.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 - -10.3.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 - -10.3.3 JSON output ------------------- - - * Not yet much used; real-world feedback is welcome. - - * Our JSON is rather large and verbose, as it is quite 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 - -10.3.4 SQL output ------------------ - - * 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, Prev: Output format, Up: OUTPUT - -10.4 Commodity styles -===================== - -The display style of a commodity/currency is inferred according to the -rules described in Commodity display style. The inferred display style -can be overridden by an optional '-c/--commodity-style' option -(Exceptions: as is the case for inferred styles, price amounts, and all -amounts displayed by the 'print' command, will be displayed with all of -their decimal digits visible, regardless of the specified precision). -For example, the following will override the display style for dollars. - -$ hledger print -c '$1.000,0' - - The format specification of the style is identical to the commodity -display style specification for the commodity directive. The command -line option can be supplied repeatedly to override the display style for -multiple commodity/currency symbols. - - -File: hledger.info, Node: COMMANDS, Next: JOURNAL FORMAT, Prev: OUTPUT, Up: Top - -11 COMMANDS -*********** - -hledger provides a number of commands for producing reports and managing -your data. 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'. - - Here are the built-in commands, with the most often-used in bold: - - *Data entry:* - - These data entry commands are the only ones which can modify your -journal file. - - * *add* - add transactions using guided prompts - * *import* - add any new transactions from other files (eg csv) - - *Data management:* - - * check - check for various kinds of issue in the data - * close (equity) - generate balance-resetting transactions - * diff - compare account transactions in two journal files - * rewrite - generate extra postings, similar to print -auto - - *Financial statements:* - - * *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 - * roi - show return on investments - - *Miscellaneous reports:* - - * accounts - show account names - * activity - show postings-per-interval bar charts - * *balance (bal)* - show balance changes/end balances/budgets in any - accounts - * codes - show transaction codes - * commodities - show commodity/currency symbols - * descriptions - show unique transaction descriptions - * files - show input file paths - * help - show hledger user manuals in several formats - * notes - show unique note segments of transaction descriptions - * payees - show unique payee segments of transaction descriptions - * prices - show market price records - * *print* - show transactions (journal entries) - * print-unique - show only transactions with unique descriptions - * *register (reg)* - show postings in one or more accounts & running - total - * register-match - show a recent posting that best matches a - description - * stats - show journal statistics - * tags - show tag names - * test - run self tests - - *Add-on commands:* - - Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on -commands; these appear in the commands list with a '+' mark. Two of -these are maintained and released with hledger: - - * *ui* - an efficient terminal interface (TUI) for hledger - * *web* - a simple web interface (WUI) for hledger - - And these add-ons are maintained separately: - - * iadd - a more interactive alternative for the add command - * interest - generates interest transactions according to various - schemes - * stockquotes - downloads market prices for your commodities from - AlphaVantage _(experimental)_ - - Next, the detailed command docs, in alphabetical order. - -* Menu: - -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* print-unique:: -* register:: -* register-match:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: -* About add-on commands:: - - -File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS - -11.1 accounts -============= - -accounts -Show account names. - - This command lists account names, either declared with account -directives (-declared), posted to (-used), or both (the default). With -query arguments, only matched account names and account names referenced -by matched postings are shown. It shows a flat list by default. With -'--tree', it uses indentation to show the account hierarchy. In flat -mode you can add '--drop N' to omit the first few account name -components. Account names can be depth-clipped with 'depth:N' or -'--depth N' or '-N'. - - With '--types', it also shows each account's type, if it's known. -(See Declaring accounts > Account types.) - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS - -11.2 activity -============= - -activity -Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - - Examples: - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS - -11.3 add -======== - -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, - 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 the tutorial for a detailed explanation): - -$ hledger add -Adding transactions to journal file /src/hledger/examples/sample.journal -Any command line arguments will be used as defaults. -Use tab key to complete, readline keys to edit, enter to accept defaults. -An optional (CODE) may follow transaction dates. -An optional ; COMMENT may follow descriptions or amounts. -If you make a mistake, enter < at any prompt to 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: COMMANDS - -11.4 aregister -============== - -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. -(Eg if you have 'assets:aaa:checking' and 'assets:bbb:checking' -accounts, 'hledger areg checking' would select 'assets:aaa:checking'.) - - 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 - -11.4.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: COMMANDS - -11.5 balance -============ - -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:: -* Filtered balance report:: -* List or tree mode:: -* Depth limiting:: -* Dropping top-level accounts:: -* Multi-period balance report:: -* Showing declared accounts:: -* Data layout:: -* Sorting by amount:: -* Percentages:: -* Balance change end balance:: -* Balance report types:: -* Useful balance reports:: -* Budget report:: -* Customising single-period balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -11.5.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: Filtered balance report, Prev: balance features, Up: balance - -11.5.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. For real-world -accounts, this should also match 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: Filtered balance report, Next: List or tree mode, Prev: Simple balance report, Up: balance - -11.5.3 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 - -11.5.4 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 - -11.5.5 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: Multi-period balance report, Prev: Depth limiting, Up: balance - -11.5.6 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: Multi-period balance report, Next: Showing declared accounts, Prev: Dropping top-level accounts, Up: balance - -11.5.7 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: Showing declared accounts, Next: Data layout, Prev: Multi-period balance report, Up: balance - -11.5.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: Data layout, Next: Sorting by amount, Prev: Showing declared accounts, Up: balance - -11.5.9 Data layout ------------------- - -The '--layout' option affects how multi-commodity amounts are displayed, -and some other things, influencing the overall layout of the report -data: - - * '--layout=wide[,WIDTH]': commodities are shown on a single line, - possibly elided to the specified width - * '--layout=tall': each commodity is shown on a separate line - * '--layout=bare': amounts are shown as bare numbers, with commodity - symbols in a separate column - * '--layout=tidy': data is normalised to tidy form, with one row per - data value. We currently support this with CSV output only. In - tidy mode, totals and row averages are disabled ('-N/--no-total' is - implied and '-T/--row-total' and '-A/--average' will be ignored). - - These '--layout' modes are supported with some but not all of the -output formats: - -- 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 when 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 - is a column and each row represents a single data point (see - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). - This kind of data is the easiest to process with other software: - - $ 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: Sorting by amount, Next: Percentages, Prev: Data layout, Up: balance - -11.5.10 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: Balance change end balance, Prev: Sorting by amount, Up: balance - -11.5.11 Percentages -------------------- - -With '-%/--percent', balance reports show each account's value expressed -as a percentage of the (column) total: - -$ hledger -f examples/sample.journal bal expenses -Q -% -Balance changes in 2008: - - || 2008Q1 2008Q2 2008Q3 2008Q4 -===================++================================= - expenses:food || 0 50.0 % 0 0 - expenses:supplies || 0 50.0 % 0 0 --------------------++--------------------------------- - || 0 100.0 % 0 0 - - 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: Balance change end balance, Next: Balance report types, Prev: Percentages, Up: balance - -11.5.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: Useful balance reports, Prev: Balance change end balance, Up: balance - -11.5.13 Balance report types ----------------------------- - -For more flexible reporting, there are three important option groups: - - 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] -...' - - The first two are the most important: calculation type selects the -basic calculation to perform for each table cell, while accumulation -type says which postings should be included in each cell's calculation. -Typically one or both of these are selected by default, so you don't -need to write them explicitly. A valuation type can be added if you -want to convert the basic report to value or cost. - - *Calculation type:* -The basic calculation to perform for each table cell. It is one of: - - * '--sum' : sum the posting amounts (*default*) - * '--budget' : like -sum but also show a goal amount - * '--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) - - *Accumulation type:* -Which postings should be included in each cell's calculation. It is one -of: - - * '--change' : postings from column start to column end, ie within - the cell's period. Typically used to see revenues/expenses. - (*default for balance, incomestatement*) - - * '--cumulative' : postings from report start to column end, eg to - show changes accumulated since the report's start date. Rarely - used. - - * '--historical/-H' : postings from journal start to column end, ie - all postings from account creation to the end of the cell's period. - Typically used to see historical end balances of - assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) - - *Valuation type:* -Which kind of valuation, valuation date(s) and optionally a target -valuation commodity to use. It is one of: - - * no valuation, show amounts in their original commodities - (*default*) - * '--value=cost[,COMM]' : no valuation, show amounts converted to - cost - * '--value=then[,COMM]' : show value at transaction dates - * '--value=end[,COMM]' : show value at period end date(s) (*default - with '--valuechange', '--gain'*) - * '--value=now[,COMM]' : show value at today's date - * '--value=YYYY-MM-DD[,COMM]' : show value at another date - - or one of their aliases: '--cost/-B', '--market/-V' or -'--exchange/-X'. - - 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: YYYY-MM-DD -v /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: Useful balance reports, Next: Budget report, Prev: Balance report types, Up: balance - -11.5.14 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: Budget report, Next: Customising single-period balance reports, Prev: Useful balance reports, Up: balance - -11.5.15 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 very 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] - - For more examples and notes, see Budgeting. - -* Menu: - -* Budget report start date:: -* Budgets and subaccounts:: -* Selecting budget goals:: - - -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report - -11.5.15.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 - -11.5.15.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, Prev: Budgets and subaccounts, Up: Budget report - -11.5.15.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 the -print command 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: Customising single-period balance reports, Prev: Budget report, Up: balance - -11.5.16 Customising single-period balance reports -------------------------------------------------- - -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 (plus a newline) specifies the formatting -applied to each account/balance pair. It may contain any suitable text, -with data fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - - * MAX truncates at this width (optional) - - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS - -11.6 balancesheet -================= - -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. - - The asset and liability accounts shown are those accounts declared -with the 'Asset' or 'Cash' or 'Liability' type, or otherwise all -accounts under a top-level 'asset' or 'liability' account (case -insensitive, plurals allowed). - - 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: COMMANDS - -11.7 balancesheetequity -======================= - -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. - - The asset, liability and equity accounts shown are those accounts -declared with the 'Asset', 'Cash', 'Liability' or 'Equity' type, or -otherwise all accounts under a top-level 'asset', 'liability' or -'equity' account (case insensitive, plurals allowed). - - 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: COMMANDS - -11.8 cashflow -============= - -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. - - "Cash" assets are those accounts which are (or whose parents are) -declared as 'Cash' by an account directive, like this: - -account some:liquid:asset ; type:C - - Or if there are no such declarations, all accounts - - * under a top-level 'asset' account (case insensitive, plural - allowed) - * with some variation of 'cash', 'bank', 'checking' or 'saving' in - their name. - - 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: COMMANDS - -11.9 check -========== - -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 - - Here are the checks currently available: - -* Menu: - -* Basic checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: - - -File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check - -11.9.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 transaction prices or automatically-inferred - transaction prices - - * *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 - -11.9.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 transaction prices but not inferred ones - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -11.9.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 - - * *uniqueleafnames* - all account leaf names are unique - - -File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check - -11.9.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: close, Next: codes, Prev: check, Up: COMMANDS - -11.10 close -=========== - -close, equity -Prints a sample "closing" transaction bringing specified account -balances to zero, and an inverse "opening" transaction restoring the -same account balances. - - If like most people you split your journal files by time, eg by year: -at the end of the year you can use this command to "close out" your -asset and liability (and perhaps equity) balances in the old file, and -reinitialise them in the new file. This helps ensure that report -balances remain correct whether you are including old files or not. -(Because all closing/opening transactions except the very first will -cancel out - see example below.) - - Some people also use this command to close out revenue and expense -balances at the end of an accounting period. This properly records the -period's profit/loss as "retained earnings" (part of equity), and allows -the accounting equation (A-L=E) to balance, which you could then check -by the bse report's zero total. - - You can print just the closing transaction by using the '--close' -flag, or just the opening transaction with the '--open' flag. - - Their descriptions are 'closing balances' and 'opening balances' by -default; you can customise these with the '--close-desc' and -'--open-desc' options. - - Just one balancing equity posting is used by default, with the amount -left implicit. The default account name is 'equity:opening/closing -balances'. You can customise the account name(s) with '--close-acct' -and '--open-acct'. (If you specify only one of these, it will be used -for both.) - - With '--x/--explicit', the equity posting's amount will be shown -explicitly, and if it involves multiple commodities, there will be a -separate equity posting for each commodity (as in the print command). - - With '--interleaved', each equity posting is shown next to the -posting it balances (good for troubleshooting). - -* Menu: - -* close and prices:: -* close date:: -* Example close asset/liability accounts for file transition:: -* Hiding opening/closing transactions:: -* close and balance assertions:: -* Example close revenue/expense accounts to retained earnings:: - - -File: hledger.info, Node: close and prices, Next: close date, Up: close - -11.10.1 close and prices ------------------------- - -Transaction prices are ignored (and discarded) by closing/opening -transactions, by default. With '--show-costs', they are preserved; -there will be a separate equity posting for each cost in each commodity. -This means 'balance -B' reports will look the same after the transition. -Note if you have many foreign currency or investment transactions, this -will generate very large journal entries. - - -File: hledger.info, Node: close date, Next: Example close asset/liability accounts for file transition, Prev: close and prices, Up: close - -11.10.2 close date ------------------- - -The default closing date is yesterday, or the journal's end date, -whichever is later. - - Unless you are running 'close' on exactly the first day of the new -period, you'll want to override the closing date. This is done by -specifying a report end date, where "last day of the report period" will -be the closing date. The opening date is always the following day. So -to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any -of these will work: - -end date explanation -argument -------------------------------------------------------------------- -'-e 2021-01-01' end dates are exclusive -'-e 2021' equivalent, per smart dates -'-p 2020' equivalent, the period's begin date is ignored -'date:2020' equivalent query - - -File: hledger.info, Node: Example close asset/liability accounts for file transition, Next: Hiding opening/closing transactions, Prev: close date, Up: close - -11.10.3 Example: close asset/liability accounts for file transition -------------------------------------------------------------------- - -Carrying asset/liability balances from 2020.journal into a new file for -2021: - -$ hledger close -f 2020.journal -p 2020 assets liabilities -# copy/paste the closing transaction to the end of 2020.journal -# copy/paste the opening transaction to the start of 2021.journal - - Or: - -$ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction -$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction - - Now, - -$ hledger bs -f 2021.journal # just new file - balances correct -$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct -$ hledger bs -f 2020.journal # just old files - balances are zero ? - # (exclude final closing txn, see below) - - -File: hledger.info, Node: Hiding opening/closing transactions, Next: close and balance assertions, Prev: Example close asset/liability accounts for file transition, Up: close - -11.10.4 Hiding opening/closing transactions -------------------------------------------- - -Although the closing/opening transactions cancel out, they will be -visible in reports like 'print' and 'register', creating some visual -clutter. You can exclude them all with a query, like: - -$ hledger print not:desc:'opening|closing' # less typing -$ hledger print not:'equity:opening/closing balances' # more precise - - But when reporting on multiple files, this can get a bit tricky; you -may need to keep the earliest opening balances, for a historical -register report; or you may need to suppress a closing transaction, to -see year-end balances. If you find yourself needing more precise -queries, here's one solution: add more easily-matched tags to -opening/closing transactions, like this: - -; 2019.journal -2019-01-01 opening balances ; earliest opening txn, no tag here -... -2019-12-31 closing balances ; clopen:2020 -... - -; 2020.journal -2020-01-01 opening balances ; clopen:2020 -... -2020-12-31 closing balances ; clopen:2021 -... - -; 2021.journal -2021-01-01 opening balances ; clopen:2021 -... - - Now with - -; all.journal -include 2019.journal -include 2020.journal -include 2021.journal - - you could do eg: - -$ hledger -f all.journal reg -H checking not:tag:clopen - # all years checking register, hiding non-essential opening/closing txns - -$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 - # 2020 year end balances, suppressing 2020 closing txn - - -File: hledger.info, Node: close and balance assertions, Next: Example close revenue/expense accounts to retained earnings, Prev: Hiding opening/closing transactions, Up: close - -11.10.5 close and balance assertions ------------------------------------- - -The closing and opening transactions will include balance assertions, -verifying that the accounts have first been reset to zero and then -restored to their previous balance. These provide valuable error -checking, alerting you when things get out of line, but you can ignore -them temporarily with '-I' or just remove them if you prefer. - - You probably shouldn't use status or realness filters (like -C or -R -or 'status:') with 'close', or the generated balance assertions will -depend on these flags. Likewise, if you run this command with '--auto', -the balance assertions would probably always require '--auto'. - - Multi-day transactions (where some postings have a different date) -break the balance assertions, because the money is temporarily -"invisible" while in transit: - -2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - assets:bank:checking -5 ; date: 2021/1/2 - - To fix the assertions, you can add a temporary account to track such -in-transit money (splitting the multi-day transaction into two -single-day transactions): - -; in 2020.journal: -2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - liabilities:pending - -; in 2021.journal: -2021/1/2 clearance of last year's pending transactions - liabilities:pending 5 = 0 - assets:bank:checking - - -File: hledger.info, Node: Example close revenue/expense accounts to retained earnings, Prev: close and balance assertions, Up: close - -11.10.6 Example: close revenue/expense accounts to retained earnings --------------------------------------------------------------------- - -For this, use '--close' to suppress the opening transaction, as it's not -needed. Also you'll want to change the equity account name to your -equivalent of "equity:retained earnings". - - Closing 2021's first quarter revenues/expenses: - -$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ - --close-acct='equity:retained earnings' >> 2021.journal - - The same, using the default journal and current year: - -$ hledger close --close revenues expenses -p Q1 \ - --close-acct='equity:retained earnings' >> $LEDGER_FILE - - Now, the first quarter's balance sheet should show a zero (unless you -are using @/@@ notation without equity postings): - -$ hledger bse -p Q1 - - And we must suppress the closing transaction to see the first -quarter's income statement (using the description; 'not:'retained -earnings'' won't work here): - -$ hledger is -p Q1 not:desc:'closing balances' - - -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS - -11.11 codes -=========== - -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: - -1/1 (123) - (a) 1 - -1/1 () - (a) 1 - -1/1 - (a) 1 - -1/1 (126) - (a) 1 - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - - -126 - - -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS - -11.12 commodities -================= - -commodities -List all commodity/currency symbols used or declared in the journal. - - -File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS - -11.13 descriptions -================== - -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: COMMANDS - -11.14 diff -========== - -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: COMMANDS - -11.15 files -=========== - -files -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - - -File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS - -11.16 help -========== - -help -Show the hledger user manual in one of several formats, optionally -positioned at a given TOPIC (if possible). - - TOPIC is any heading in the manual, or the start of any heading (but -not the middle). It is case insensitive. - - Some examples: 'commands', 'print', 'forecast', '"auto postings"', -'"commodity column"'. - - This command shows the user manual built in to this hledger version. -It can be useful if the correct version of the hledger manual, or the -usual viewing tools, are not installed on your system. - - By default it uses the best viewer it can find in $PATH, in this -order: 'info', 'man', $PAGER (unless a topic is specified), 'less', or -stdout. When run non-interactively, it always uses stdout. Or you can -select a particular viewer with the '-i' (info), '-m' (man), or '-p' -(pager) flags. - - -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS - -11.17 import -============ - -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 - -11.17.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 - -11.17.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' - - -File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import - -11.17.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 - -11.17.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: COMMANDS - -11.18 incomestatement -===================== - -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. - - The revenue and expense accounts shown are those accounts declared -with the 'Revenue' or 'Expense' type, or otherwise all accounts under a -top-level 'revenue' or 'income' or 'expense' account (case insensitive, -plurals allowed). - - 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: COMMANDS - -11.19 notes -=========== - -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: COMMANDS - -11.20 payees -============ - -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: COMMANDS - -11.21 prices -============ - -prices -Print market price directives from the journal. With --infer-market-prices, generate additional market prices from transaction -prices. With -infer-reverse-prices, also generate market prices by -inverting transaction prices. Prices (and postings providing -transaction prices) can be filtered by a query. Price amounts are -displayed with their full precision. - - -File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS - -11.22 print -=========== - -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 transaction price is -implied but not written, it will not appear in the output. You can use -the '-x'/'--explicit' flag to make all amounts and transaction prices -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 transaction prices are converted to -cost using that price. This can be used for troubleshooting. - - With '-m'/'--match' and a STR argument, print will show at most one -transaction: the one one whose description is most similar to STR, and -is most recent. STR should contain at least two characters. If there -is no similar-enough match, no transaction will be shown. - - With '--new', 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: print-unique, Next: register, Prev: print, Up: COMMANDS - -11.23 print-unique -================== - -print-unique -Print transactions which do not reuse an already-seen description. - - Example: - -$ cat unique.journal -1/1 test - (acct:one) 1 -2/2 test - (acct:two) 2 -$ LEDGER_FILE=unique.journal hledger print-unique -(-f option not supported) -2015/01/01 test - (acct:one) 1 - - -File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS - -11.24 register -============== - -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. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -11.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: register-match, Next: rewrite, Prev: register, Up: COMMANDS - -11.25 register-match -==================== - -register-match -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. If there are multiple equally -good matches, it shows the most recent. Query options (options, not -arguments) can be used to restrict the search space. Helps -ledger-autosync detect already-seen transactions when importing. - - -File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS - -11.26 rewrite -============= - -rewrite -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - - This is a start at a generic rewriter of transaction entries. It -reads the default journal and prints the transactions, like print, but -adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing -transaction's first posting amount. - - Examples: - -$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -$ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the -two spaces between account and amount. - - More: - -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for '--add-posting' option is a usual posting of transaction -with an exception for amount specification. More precisely, you can use -''*'' (star symbol) before the amount to indicate that that this is a -factor for an amount of original matched posting. If the amount -includes a commodity name, the new posting amount will be in the new -commodity; otherwise, it will be in the matched posting amount's -commodity. - -* Menu: - -* Re-write rules in a file:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -11.26.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 - -11.26.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 - -11.26.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: COMMANDS - -11.27 roi -========= - -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 - -11.27.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 - -11.27.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 - -11.27.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: COMMANDS - -11.28 stats -=========== - -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 also supports output destination and output format -selection. - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS - -11.29 tags -========== - -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, Next: About add-on commands, Prev: tags, Up: COMMANDS - -11.30 test -========== - -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: About add-on commands, Prev: test, Up: COMMANDS - -11.31 About add-on commands -=========================== - -Add-on commands are 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. - - Add-ons are a relatively easy way to add local features or experiment -with new ideas. They can be written in any language, but haskell -scripts have a big advantage: they can use the same hledger library -functions that built-in commands use for command-line options, parsing -and reporting. Some experimental/example add-on scripts can be found in -the hledger repo's bin/ directory. - - 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: JOURNAL FORMAT, Next: CSV FORMAT, Prev: COMMANDS, Up: Top - -12 JOURNAL FORMAT -***************** - -hledger's default file format, representing a General Journal. - - 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). These are mostly in the order you'll use them, but in some -cases related concepts have been grouped together for easy reference, or -linked before they are introduced, so feel free to skip over anything -that looks unnecessary right now. - -* Menu: - -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Comments:: -* Tags:: -* Postings:: -* Account names:: -* Amounts:: -* Transaction prices:: -* Lot prices lot dates:: -* Balance assertions:: -* Balance assignments:: -* Directives:: -* Directives and multiple files:: -* Comment blocks:: -* Including other files:: -* Default year:: -* Declaring payees:: -* Declaring the decimal mark:: -* Declaring commodities:: -* Default commodity:: -* Declaring market prices:: -* Declaring accounts:: -* Rewriting accounts:: -* Default parent account:: -* Periodic transactions:: -* Auto postings:: - - -File: hledger.info, Node: Transactions, Next: Dates, Up: JOURNAL FORMAT - -12.1 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 FORMAT - -12.2 Dates -========== - -* Menu: - -* Simple dates:: -* Secondary dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Secondary dates, Up: Dates - -12.2.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 default year 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: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates - -12.2.2 Secondary dates ----------------------- - -Real-life transactions sometimes involve more than one date - eg the -date you write a cheque, and the date it clears in your bank. When you -want to model this, for more accurate daily balances, you can specify -individual posting dates. - - Or, you can use the older _secondary date_ feature (Ledger calls it -auxiliary date or effective date). Note: we support this for -compatibility, but I usually recommend avoiding this feature; posting -dates are almost always clearer and simpler. - - 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", as shown here: - -2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking - -$ hledger register checking -2010-02-23 movie ticket assets:checking $-10 $-10 - -$ hledger register checking --date2 -2010-02-19 movie ticket assets:checking $-10 $-10 - - -File: hledger.info, Node: Posting dates, Prev: Secondary dates, Up: Dates - -12.2.3 Posting dates --------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like 'date:DATE'. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction's date. You can set the secondary date -similarly, with 'date2:DATE2'. The 'date:' or 'date2:' tags must have a -valid simple date value if they are present, eg a 'date:' tag with no -value is not allowed. - - Ledger's earlier, more compact bracketed date syntax is also -supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'. hledger will attempt -to parse any square-bracketed sequence of the '0123456789/-.=' -characters in this way. With this syntax, DATE infers its year from the -transaction and DATE2 infers its year from DATE. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: JOURNAL FORMAT - -12.3 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 FORMAT - -12.4 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: Comments, Prev: Code, Up: JOURNAL FORMAT - -12.5 Description -================ - -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -12.5.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: Comments, Next: Tags, Prev: Description, Up: JOURNAL FORMAT - -12.6 Comments -============= - -Lines in the journal beginning with a semicolon (';') or hash ('#') or -star ('*') are comments, and will be ignored. (Star comments cause -org-mode nodes to be ignored, allowing emacs users to fold and navigate -their journals with org-mode or orgstruct-mode.) - - You can attach comments to a transaction by writing them after the -description and/or indented on the following lines (before the -postings). Similarly, you can attach comments to an individual posting -by writing them after the amount and/or indented on the following lines. -Transaction and posting comments must begin with a semicolon (';'). - - Some examples: - -# a file comment -; another file comment -* also a file comment, useful in org/orgstruct mode - -comment -A multiline file comment, which continues -until a line containing just "end comment" -(or end of file). -end comment - -2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 -; a file comment (because not indented) - - You can also comment larger regions of a file using 'comment' and -'end comment' directives. - - -File: hledger.info, Node: Tags, Next: Postings, Prev: Comments, Up: JOURNAL FORMAT - -12.7 Tags -========= - -Tags are a way to add extra labels or labelled data to postings and -transactions, which you can then search or pivot on. - - A simple tag is a word (which may contain hyphens) followed by a full -colon, written inside a transaction or posting comment line: - -2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the -next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or -newlines. Ending at commas means you can write multiple short tags on -one line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - * "'a comment containing'" is just comment text, not a tag - * "'tag1'" is a tag with no value - * "'tag2'" is another tag, whose value is "'some value ...'" - - Tags in a transaction comment affect the transaction and all of its -postings, while tags in a posting comment affect only that posting. For -example, the following transaction has three tags ('A', 'TAG2', -'third-tag') and the posting has four (those plus 'posting-tag'): - -1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values -are simple strings. - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Tags, Up: JOURNAL FORMAT - -12.8 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. - -* Menu: - -* Virtual postings:: - - -File: hledger.info, Node: Virtual postings, Up: Postings - -12.8.1 Virtual postings ------------------------ - -A posting with a parenthesised 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 accounting, 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: - -1/1 opening balances - (assets:checking) $1000 - (assets:savings) $2000 - - A posting with a bracketed 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: - -1/1 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- not required to balance - - Ordinary non-parenthesised, non-bracketed postings are called _real -postings_. You can exclude virtual postings from reports with the -'-R/--real' flag or 'real:1' query. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: JOURNAL FORMAT - -12.9 Account names -================== - -Account names typically have several parts separated by a full colon, -from which hledger derives a hierarchical chart of accounts. They can -be anything you like, but in finance there are traditionally five -top-level accounts: 'assets', 'liabilities', 'revenue', 'expenses', and -'equity'. - - Account names may contain single spaces, eg: 'assets:accounts -receivable'. Because of this, they must always be followed by *two or -more spaces* (or newline). - - Account names can be aliased. - - -File: hledger.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: JOURNAL FORMAT - -12.10 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 - -12.10.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 detail below. - - -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts - -12.10.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 - -12.10.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, in JOURNAL FORMAT -> Declaring commodities. 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 - -12.10.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. - - Transaction price 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 transaction price). 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 - -12.10.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"). (Guaranteed since hledger 1.17.1; in older versions -this could vary if hledger was built with Decimal < 0.5.1.) - - -File: hledger.info, Node: Transaction prices, Next: Lot prices lot dates, Prev: Amounts, Up: JOURNAL FORMAT - -12.11 Transaction prices -======================== - -Within a transaction, you can note an amount's price in another -commodity. This can be used to document the cost (in a purchase) or -selling price (in a sale). For example, transaction prices are useful -to record purchases of a foreign currency. Note transaction prices are -fixed at the time of the transaction, and do not change over time. See -also market prices, which represent prevailing exchange rates on a -certain date. - - There are several ways to record a transaction price: - - 1. Write the price per unit, as '@ UNITPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as '@@ TOTALPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - 4. Like 1, but the '@' is parenthesised, i.e. '(@)'; this is for - compatibility with Ledger journals (Virtual posting costs), and is - equivalent to 1 in hledger. - - 5. Like 2, but as in 4 the '@@' is parenthesised, i.e. '(@@)'; in - hledger, this is equivalent to 2. - - Use the '-B/--cost' flag to convert amounts to their transaction -price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in -Ledger). Eg here is how -B affects the balance report for the example -above: - -$ hledger bal -N --flat - $-135 assets:dollars - €100 assets:euros -$ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction -price is inferred: the inferred price will be in the commodity of the -last amount. So if example 3's postings are reversed, while the -transaction is equivalent, -B shows something different: - -2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros €100 ; for 100 euros - -$ hledger bal -N --flat -B - €-100 assets:dollars # <- the dollars' selling price - €100 assets:euros - - -File: hledger.info, Node: Lot prices lot dates, Next: Balance assertions, Prev: Transaction prices, Up: JOURNAL FORMAT - -12.12 Lot prices, lot dates -=========================== - -Ledger allows another kind of price, lot price (four variants: -'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}', -'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified. -These are normally used to select a lot when selling investments. -hledger will parse these, for compatibility with Ledger journals, but -currently ignores them. A transaction price, lot price and/or lot date -may appear in any order, after the posting amount and before the balance -assertion if any. - - -File: hledger.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices lot dates, Up: JOURNAL FORMAT - -12.13 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, 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 - -12.13.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 - -12.13.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 - -12.13.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 - -12.13.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 - -12.13.5 Assertions and prices ------------------------------ - -Balance assertions ignore transaction prices, and should normally be -written without one: - -2019/1/1 - (a) $1 @ €1 = $1 - - We do allow prices to be written there, however, and print shows -them, even though they don't affect whether the assertion passes or -fails. This is for backward compatibility (hledger's close command used -to generate balance assertions with prices), and because balance -_assignments_ do use them (see below). - - -File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions - -12.13.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 - -12.13.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 - -12.13.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 - -12.13.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: Balance assignments, Next: Directives, Prev: Balance assertions, Up: JOURNAL FORMAT - -12.14 Balance assignments -========================= - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). Note that using balance assignments makes your journal a -little less explicit; to know the exact amount posted, you have to run -hledger or do the calculations yourself, instead of just reading it. - -* Menu: - -* Balance assignments and prices:: - - -File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments - -12.14.1 Balance assignments and prices --------------------------------------- - -A transaction price in a balance assignment will cause the calculated -amount to have that price attached: - -2019/1/1 - (a) = $1 @ €2 - -$ hledger print --explicit -2019-01-01 - (a) $1 @ €2 = $1 @ €2 - - -File: hledger.info, Node: Directives, Next: Directives and multiple files, Prev: Balance assignments, Up: JOURNAL FORMAT - -12.15 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 add some as your needs grow. Here is an overview of -directives by purpose: - -purpose directives command line - options with - similar effect ---------------------------------------------------------------------------- -*READING/GENERATING DATA:* -Declare a commodity's or 'commodity', 'D', -file's decimal mark to help 'decimal-mark' -parse amounts accurately -Apply changes to the data 'alias', 'apply '--alias' -while parsing account', 'comment', - 'D', 'Y' -Inline extra data files 'include' multiple - '-f/--file''s -Generate extra transactions or '~' -budget goals -Generate extra postings '=' -*CHECKING FOR ERRORS:* -Define valid entities to allow 'account', -stricter error checking 'commodity', 'payee' -*DISPLAYING REPORTS:* -Declare accounts' display 'account' -order and accounting type -Declare commodity display 'commodity', 'D' '-c/--commodity-style' -styles - - And here are all the directives and their precise effects: - -directiveeffects ends - at - file - end? ---------------------------------------------------------------------------- -*'account'*Declares an account, for checking all entries in all files; - and its display order and type, for reports. Subdirectives: - any text, ignored. -*'alias'*Rewrites account names, in following entries until end of Y - current file or 'end aliases'. -*'applyPrepends a common parent account to all account names, in Y -account'*following entries until end of current file or 'end apply - account'. -*'comment'*Ignores part of the journal file, until end of current fileY - or 'end comment'. -*'commodity'*Declares a commodity, for checking all entries in all files;N, - the decimal mark for parsing amounts of this commodity, for Y - following entries until end of current file; and its display - style, for reports. Takes precedence over 'D'. - Subdirectives: 'format' (alternate syntax). -*'D'* Sets a default commodity to use for no-symbol amounts, and Y - its decimal mark for parsing amounts of this commodity in - following entries until end of current file; and its display - style, for reports. -*'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 they - were written inline. -*'payee'*Declares a payee name, for checking all entries in all files. -*'P'* Declares a market price for a commodity on some date, for - valuation reports. -*'Y'* Declares a year for yearless dates, for following entries Y - until end of current file. -*'~'* Declares a periodic transaction rule that generates future -(tilde)transactions with '--forecast' and budget goals with 'balance - --budget'. -*'='* Declares an auto posting rule that generates extra postings partly -(equals)on matched transactions with '--auto', in current, parent, - and child files (but not sibling files, see #1212). - - -File: hledger.info, Node: Directives and multiple files, Next: Comment blocks, Prev: Directives, Up: JOURNAL FORMAT - -12.16 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: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: JOURNAL FORMAT - -12.17 Comment blocks -==================== - -A line containing just 'comment' starts a commented region of the file, -and a line containing just 'end comment' (or the end of the current -file) ends it. See also comments. - - -File: hledger.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: JOURNAL FORMAT - -12.18 Including other files -=========================== - -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: Default year, Next: Declaring payees, Prev: Including other files, Up: JOURNAL FORMAT - -12.19 Default year -================== - -You can set a default year to be used for subsequent dates which don't -specify a year. This is a line beginning with 'Y' followed by the year. -Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -Y2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - -File: hledger.info, Node: Declaring payees, Next: Declaring the decimal mark, Prev: Default year, Up: JOURNAL FORMAT - -12.20 Declaring payees -====================== - -The 'payee' 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 - - -File: hledger.info, Node: Declaring the decimal mark, Next: Declaring commodities, Prev: Declaring payees, Up: JOURNAL FORMAT - -12.21 Declaring the decimal mark -================================ - -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: Declaring commodities, Next: Default commodity, Prev: Declaring the decimal mark, Up: JOURNAL FORMAT - -12.22 Declaring commodities -=========================== - -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 - - 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: Declaring commodities - -12.22.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: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: JOURNAL FORMAT - -12.23 Default commodity -======================= - -The 'D' 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). - - The syntax is 'D AMOUNT'. As with 'commodity', 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 - - If both 'commodity' and 'D' directives are found for a commodity, -'commodity' takes precedence for setting decimal mark and display style. - - If you are using 'D' and also checking commodities, you will need to -add a 'commodity' directive similar to the 'D'. (The 'hledger check -commodities' command expects 'commodity' directives, and ignores 'D'). - - -File: hledger.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: JOURNAL FORMAT - -12.24 Declaring market prices -============================= - -The 'P' directive declares a market price, which is an exchange rate -between two commodities on a certain date. (In Ledger, they are called -"historical prices".) These are often obtained from a stock exchange, -cryptocurrency exchange, or the 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: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: JOURNAL FORMAT - -12.25 Declaring accounts -======================== - -'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. - * They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - * They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and - incomestatement. - * They can store other account information, as comments or as tags - which can be used to filter reports. - * They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - * In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - - The simplest form is just the word 'account' followed by a -hledger-style account name, eg this account directive declares the -'assets:bank:checking' account: - -account assets:bank:checking - -* Menu: - -* Account error checking:: -* Account comments:: -* Account subdirectives:: -* Account types:: -* Account display order:: - - -File: hledger.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts - -12.25.1 Account error checking ------------------------------- - -By default, accounts come into existence when a transaction references -them by name. 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 -the 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 in other formats). - * 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 comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts - -12.25.2 Account comments ------------------------- - -Comments, beginning with a semicolon, can be added: - - * on the same line, *after two or more spaces* (because ; is allowed - in account names) - * on the next lines, indented - - An example of both: - -account assets:bank:checking ; same-line comment, note 2+ spaces required before ; - ; next-line comment - ; some tags, type:A, acctnum:12345 - - Compatibility note: same-line comments are not supported by Ledger or -hledger <1.13. - - -File: hledger.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts - -12.25.3 Account subdirectives ------------------------------ - -We also allow (and ignore) Ledger-style indented subdirectives, just for -compatibility.: - -account assets:bank:checking - format blah blah ; <- subdirective, ignored - - Here is the full syntax of account directives: - -account ACCTNAME [;type:ACCTTYPE] [COMMENT] - [;COMMENTS] - [LEDGER-STYLE SUBDIRECTIVES, IGNORED] - - -File: hledger.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts - -12.25.4 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 - CONVERSION & COST).) - - 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. Note the Cash - regexp changed in hledger 1.24.99.2. - - 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 each of them, 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: Account display order, Prev: Account types, Up: Declaring accounts - -12.25.5 Account display order ------------------------------ - -Account directives also set the order in which accounts are displayed, -eg in reports, the hledger-ui accounts screen, and the hledger-web -sidebar. By default accounts are listed in alphabetical order. But if -you have these account directives in the journal: - -account assets -account liabilities -account equity -account revenues -account expenses - - you'll see those accounts displayed in declaration order, not -alphabetically: - -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses - - Undeclared accounts, if any, are displayed last, in alphabetical -order. - - Note that sorting is done at each level of the account tree (within -each group of sibling accounts under the same parent). And currently, -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: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: JOURNAL FORMAT - -12.26 Rewriting accounts -======================== - -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:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts - -12.26.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: Rewriting accounts - -12.26.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: Rewriting accounts - -12.26.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, Prev: Combining aliases, Up: Rewriting accounts - -12.26.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, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: Rewriting accounts - -12.26.5 'end aliases' ---------------------- - -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, Up: Rewriting accounts - -12.26.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: Rewriting accounts - -12.26.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: Default parent account, Next: Periodic transactions, Prev: Rewriting accounts, Up: JOURNAL FORMAT - -12.27 Default parent account -============================ - -You can specify a parent account which will be prepended to all accounts -within a section of the journal. Use the 'apply account' and 'end apply -account' directives like so: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - which is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - If 'end apply account' is omitted, the effect lasts to the end of the -file. Included files are also affected, eg: - -apply account business -include biz.journal -end apply account -apply account personal -include personal.journal - - Prior to hledger 1.0, legacy 'account' and 'end' spellings were also -supported. - - A default parent account also affects account directives. It does -not affect account names being entered via hledger add or hledger-web. -If account aliases are present, they are applied after the default -parent account. - - -File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: Default parent account, Up: JOURNAL FORMAT - -12.28 Periodic transactions -=========================== - -Periodic transaction rules describe transactions that recur. They allow -hledger to generate temporary future transactions to help with -forecasting, so you don't have to write out each one in the journal, and -it's easy to try out different forecasts. - - 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. - - Periodic transaction rules also have a second meaning: they are used -to define budget goals, shown in budget reports. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: -* Forecasting with periodic transactions:: -* Budgeting with periodic transactions:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -12.28.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.): - -~ monthly - expenses:rent $2000 - assets:bank:checking - - There is an additional constraint on the period expression: the start -date must fall on a natural boundary of the interval. Eg 'monthly from -2018/1/1' is valid, but 'monthly from 2018/1/15' is not. - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -12.28.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!, Next: Forecasting with periodic transactions, Prev: Periodic rules and relative dates, Up: Periodic transactions - -12.28.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: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions - -12.28.4 Forecasting with periodic transactions ----------------------------------------------- - -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 with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions - -12.28.5 Budgeting with periodic transactions --------------------------------------------- - -With the '--budget' flag, currently supported by the balance command, -each periodic transaction rule declares recurring budget goals for the -specified accounts. Eg the first example above declares a goal of -spending $2000 on rent (and also, a goal of depositing $2000 into -checking) every month. Goals and actual performance can then be -compared in budget reports. - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Auto postings, Prev: Periodic transactions, Up: JOURNAL FORMAT - -12.29 Auto postings -=================== - -"Automated postings" or "auto postings" are extra postings which get -added automatically to transactions which match certain queries, defined -by "auto posting rules", when you use the '--auto' flag. - - 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 - -12.29.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 - -12.29.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 - -12.29.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 - -12.29.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: CSV FORMAT, Next: TIMECLOCK FORMAT, Prev: JOURNAL FORMAT, Up: Top - -13 CSV FORMAT -************* - -How hledger reads CSV data, and the CSV rules file format. - - hledger can read CSV files (Character Separated Value - usually -comma, semicolon, or tab) containing dated records as if they were -journal files, automatically converting each CSV record into a -transaction. - - (To learn about _writing_ CSV, see CSV output.) - - We describe each CSV file's format with a corresponding _rules file_. -By default this is named like the CSV file with a '.rules' extension -added. Eg when reading 'FILE.csv', hledger also looks for -'FILE.csv.rules' in the same directory as 'FILE.csv'. You can specify a -different rules file with the '--rules-file' option. If a rules file is -not found, hledger will create a sample rules file, which you'll need to -adjust. - - This file contains rules describing the CSV data (header line, fields -layout, date format etc.), and how to construct hledger journal entries -(transactions) from it. Often there will also be a list of conditional -rules for categorising transactions based on their descriptions. Here's -an overview of the CSV rules; these are described more fully below, -after the examples: - -*'skip'* skip one or more header lines or matched - CSV records -*'fields' list* name CSV fields, assign them to hledger - fields -*field assignment* assign a value to one hledger field, with - interpolation -*Field names* hledger field names, used in the fields - list and field assignments -*'separator'* a custom field separator -*'if' block* apply some rules to CSV records matched by - patterns -*'if' table* apply some rules to CSV records matched by - patterns, alternate syntax -*'end'* skip the remaining CSV records -*'date-format'* how to parse dates in CSV records -*'decimal-mark'* the decimal mark used in CSV amounts, if - ambiguous -*'newest-first'* disambiguate record order when there's only - one date -*'include'* inline another CSV rules file -*'balance-type'* choose which type of balance assignments to - use - - Note, for best error messages when reading CSV files, use a '.csv', -'.tsv' or '.ssv' file extension or file prefix - see File Extension -below. - - There's an introductory Convert CSV files tutorial on hledger.org. - -* Menu: - -* Examples:: -* CSV rules:: -* Tips:: - - -File: hledger.info, Node: Examples, Next: CSV rules, Up: CSV FORMAT - -13.1 Examples -============= - -Here are some sample hledger CSV rules files. See also the full -collection at: -https://github.com/simonmichael/hledger/tree/master/examples/csv - -* Menu: - -* Basic:: -* Bank of Ireland:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Basic, Next: Bank of Ireland, Up: Examples - -13.1.1 Basic ------------- - -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 - - Default account names are chosen, since we didn't set them. - - -File: hledger.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: Examples - -13.1.2 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: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: Examples - -13.1.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: Examples - -13.1.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: CSV rules, Next: Tips, Prev: Examples, Up: CSV FORMAT - -13.2 CSV rules -============== - -The following kinds of rule can appear in the rules file, in any order. -Blank lines and lines beginning with '#' or ';' are ignored. - -* Menu: - -* skip:: -* fields list:: -* field assignment:: -* Field names:: -* separator:: -* if block:: -* if table:: -* end:: -* date-format:: -* decimal-mark:: -* newest-first:: -* include:: -* balance-type:: - - -File: hledger.info, Node: skip, Next: fields list, Up: CSV rules - -13.2.1 'skip' -------------- - -skip N - - The word "skip" followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines preceding the CSV data. -(Empty/blank lines are skipped automatically.) You'll need this -whenever your CSV data contains header lines. - - It also has a second purpose: it can be used inside if blocks to -ignore certain CSV records (described below). - - -File: hledger.info, Node: fields list, Next: field assignment, Prev: skip, Up: CSV rules - -13.2.2 'fields' list --------------------- - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word "fields" followed by comma-separated field -names) is the quick way to assign CSV field values to hledger fields. -(The other way is field assignments, see below.) A fields list does -does two things: - - 1. It names the CSV fields. This is optional, but can be convenient - later for interpolating them. - - 2. Whenever you use a standard hledger field name (defined below), the - CSV value is assigned to that part of the hledger 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 - - Tips: - - * The fields list always use commas, even if your CSV data uses - another separator character. - * Currently 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). - * If the CSV contains column headings, it's a good idea to use these, - suitably modified, as the basis for your field names (eg - lower-cased, with underscores instead of spaces). - * If some heading names match standard hledger fields, but you don't - want to set the hledger fields directly, alter those names, eg by - appending an underscore. - * Fields you don't care about can be given a dummy name (eg: '_' ), - or no name. - - -File: hledger.info, Node: field assignment, Next: Field names, Prev: fields list, Up: CSV rules - -13.2.3 field assignment ------------------------ - -HLEDGERFIELDNAME 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 -('%CSVFIELDNAME'). - - 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: separator, Prev: field assignment, Up: CSV rules - -13.2.4 Field names ------------------- - -Here are the standard hledger field (and pseudo-field) names, which you -can use in a fields list and in field assignments. For more about the -transaction parts they refer to, see Transactions. - -* 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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.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 - -13.2.4.6 comment field -...................... - -'comment' sets the transaction's comment, if any. - - 'commentN', where N is a number, sets the Nth posting's comment. - - Tips: - - * 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 - -13.2.4.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, and in conditional blocks. - - 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 - -13.2.4.8 amount field -..................... - -'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. - - 'amountN-in' and 'amountN-out' can be used instead, if the CSV uses -separate fields for debits and credits (inflows and outflows). hledger -assumes both of these CSV fields are unsigned, and will automatically -negate the "-out" value. If they are signed, see "Setting amounts" -below. - - 'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep -pre-hledger-1.17 CSV rules files working (and for occasional -convenience). They are suitable only for two-posting transactions; they -set both posting 1's and posting 2's amount. Posting 2's amount will be -negated, and also converted to cost if there's a transaction price. - - If you have an existing rules file using the unnumbered form, you -might want to use the numbered form in certain conditional blocks, -without having to update and retest all the old rules. To facilitate -this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of -'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores -them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned, -avoiding conflicts. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -13.2.4.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 - -13.2.4.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: separator, Next: if block, Prev: Field names, Up: CSV rules - -13.2.5 '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: if block, Next: if table, Prev: separator, Up: CSV rules - -13.2.6 'if' block ------------------ - -if MATCHER - RULE - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - Conditional blocks ("if blocks") are a block of rules that are -applied only to CSV records which match certain patterns. They are -often used for customising account names based on transaction -descriptions. - -* Menu: - -* Matching the whole record:: -* Matching individual fields:: -* Combining matchers:: -* Rules applied on successful match:: - - -File: hledger.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block - -13.2.6.1 Matching the whole record -.................................. - -Each MATCHER can be a record matcher, which looks like this: - -REGEX - - REGEX is a case-insensitive regular expression that tries to match -anywhere within the CSV record. It is a POSIX ERE (extended regular -expression) that also supports GNU word boundaries ('\b', '\B', '\<', -'\>'), and nothing else. If you have trouble, be sure to check our doc: -https://hledger.org/hledger.html#regular-expressions - - Important note: the record that is matched is not the original -record, but a synthetic one, with any enclosing double quotes (but not -enclosing whitespace) removed, and always comma-separated (which means -that a field containing a comma will appear like two fields). Eg, if -the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will -actually see '2020-01-01,Acme, Inc., 1,000'). - - -File: hledger.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block - -13.2.6.2 Matching individual fields -................................... - -Or, MATCHER can be a field matcher, like this: - -%CSVFIELD REGEX - - which matches just the content of a particular CSV field. CSVFIELD -is a percent sign followed by the field's name or column number, like -'%date' or '%1'. - - -File: hledger.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block - -13.2.6.3 Combining matchers -........................... - -A single matcher can be written on the same line as the "if"; or -multiple matchers can be written on the following lines, non-indented. -Multiple matchers are OR'd (any one of them can match), unless one -begins with an '&' symbol, in which case it is AND'ed with the previous -matcher. - -if -MATCHER -& MATCHER - RULE - - -File: hledger.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block - -13.2.6.4 Rules applied on successful match -.......................................... - -After the patterns there should be one or more rules to apply, all -indented by at least one space. Three kinds of rule are allowed in -conditional blocks: - - * field assignments (to set a hledger field) - * skip (to skip the matched CSV record) - * end (to skip all remaining CSV records). - - Examples: - -# if the CSV record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the CSV record contains any of these patterns, set account2 and comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - -File: hledger.info, Node: if table, Next: end, Prev: if block, Up: CSV rules - -13.2.7 'if' table ------------------ - -if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn -MATCHER1,VALUE11,VALUE12,...,VALUE1n -MATCHER2,VALUE21,VALUE22,...,VALUE2n -MATCHER3,VALUE31,VALUE32,...,VALUE3n - - - Conditional tables ("if tables") are a different syntax to specify -field assignments that will be applied only to CSV records which match -certain patterns. - - MATCHER could be either field or record matcher, as described above. -When MATCHER matches, values from that row would be assigned to the CSV -fields named on the 'if' line, in the same order. - - Therefore 'if' table is exactly equivalent to a sequence of of 'if' -blocks: - -if MATCHER1 - CSVFIELDNAME1 VALUE11 - CSVFIELDNAME2 VALUE12 - ... - CSVFIELDNAMEn VALUE1n - -if MATCHER2 - CSVFIELDNAME1 VALUE21 - CSVFIELDNAME2 VALUE22 - ... - CSVFIELDNAMEn VALUE2n - -if MATCHER3 - CSVFIELDNAME1 VALUE31 - CSVFIELDNAME2 VALUE32 - ... - CSVFIELDNAMEn VALUE3n - - Each line starting with MATCHER should contain enough (possibly -empty) values for all the listed fields. - - Rules would be checked and applied in the order they are listed in -the table and, like with 'if' blocks, later rules (in the same or -another table) or 'if' blocks could override the effect of any rule. - - Instead of ',' you can use a variety of other non-alphanumeric -characters as a separator. First character after 'if' is taken to be -the separator for the rest of the table. It is the responsibility of -the user to ensure that separator does not occur inside MATCHERs and -values - there is no way to escape separator. - - 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: end, Next: date-format, Prev: if table, Up: CSV rules - -13.2.8 'end' ------------- - -This rule can be used inside if blocks (only), to make hledger stop -reading this CSV file and move on to the next input file, or to command -execution. Eg: - -# ignore everything following the first empty record -if ,,,, - end - - -File: hledger.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV rules - -13.2.9 '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 -date parsing pattern, which 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 - - For the supported strptime syntax, see: -https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime - - Note that although you can parse date-times which include a time -zone, that time zone is ignored; it will not change the date that is -parsed. This means when reading CSV data with times not in your local -time zone, dates can be "off by one". - - -File: hledger.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV rules - -13.2.10 '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: newest-first, Next: include, Prev: decimal-mark, Up: CSV rules - -13.2.11 'newest-first' ----------------------- - -hledger always sorts the generated transactions by date. Transactions -on the same date should appear in the same order as their CSV records, -as hledger can usually auto-detect whether the CSV's normal order is -oldest first or newest first. But if all of the following are true: - - * the CSV might sometimes contain just one day of data (all records - having the same date) - * the CSV records are normally in reverse chronological order (newest - at the top) - * and you care about preserving the order of same-day transactions - - then, you should add the 'newest-first' rule as a hint. Eg: - -# tell hledger explicitly that the CSV is normally newest first -newest-first - - -File: hledger.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV rules - -13.2.12 '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: balance-type, Prev: include, Up: CSV rules - -13.2.13 '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: Tips, Prev: CSV rules, Up: CSV FORMAT - -13.3 Tips -========= - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* 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:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Tips - -13.3.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: Tips - -13.3.2 Valid CSV ----------------- - -hledger accepts CSV conforming to RFC 4180. When CSV values are -enclosed in quotes, note: - - * they must be double quotes (not single quotes) - * spaces outside the quotes are not allowed - - -File: hledger.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: Tips - -13.3.3 File Extension ---------------------- - -To help hledger identify the format and show the right error messages, -CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or -'.tsv' filename extension. Or, the file path should be prefixed with -'csv:', 'ssv:' or 'tsv:'. Eg: - -$ hledger -f foo.ssv print - - or: - -$ cat foo | hledger -f ssv:- foo - - You can override the file extension with a separator rule if needed. -See also: Input files in the hledger manual. - - -File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: Tips - -13.3.4 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: Tips - -13.3.5 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: Tips - -13.3.6 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: Tips - -13.3.7 Setting amounts ----------------------- - -Some tips on using the amount-setting rules discussed above. - - Here are the ways to set a posting's amount: - - 1. *If the CSV has a single amount field:* - Assign (via a fields list or a field assignment) to 'amountN'. - This sets the Nth posting's amount. N is usually 1 or 2 but can go - up to 99. - - 2. *If the CSV has separate amount fields for debit & credit (in & - out):* - - a. *If both fields are unsigned:* - Assign to 'amountN-in' and 'amountN-out'. This sets posting - N's amount to whichever of these has a non-zero value, and - negates the "-out" value. - - b. *If either field is signed (can contain a minus sign):* - Use a conditional rule to flip the sign (of non-empty values). - Since hledger always negates amountN-out, if it was already - negative, we must undo that by negating once more (but only if - the field is non-empty): - - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields, or neither field, can contain a non-zero - value:* - hledger normally expects exactly one of the fields to have a - non-zero value. Eg, the 'amountN-in'/'amountN-out' rules - would reject value pairs like these: - - "", "" - "0", "0" - "1", "none" - - So, use smarter conditional rules to set the amount from the - appropriate field. Eg, these rules would make it use only the - value containing non-zero digits, handling the above: - - 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:* - Assign to 'amount' (or to 'amount-in' and 'amount-out'). (This is - the legacy numberless syntax, which sets amount1 and amount2 and - converts amount2 to cost.) - - 4. *If the CSV has the balance instead of the transaction amount:* - Assign to 'balanceN', which sets posting N's amount indirectly via - a balance assignment. (Old syntax: 'balance', equivalent to - 'balance1'.) - - * *If hledger guesses the wrong default account name:* - When setting the amount via balance assertion, hledger may - guess the wrong default account name. So, set the account - name explicitly, eg: - - fields date, description, balance1 - account1 assets:checking - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Tips - -13.3.8 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: Tips - -13.3.9 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: Tips - -13.3.10 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: Tips - -13.3.11 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, Prev: Referencing other fields, Up: Tips - -13.3.12 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 %CSVFIELDNAME references), or a - default - * generate a synthetic hledger transaction 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: TIMECLOCK FORMAT, Next: TIMEDOT FORMAT, Prev: CSV FORMAT, Up: Top - -14 TIMECLOCK FORMAT -******************* - -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). - -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 FORMAT, Next: COMMON TASKS, Prev: TIMECLOCK FORMAT, Up: Top - -15 TIMEDOT FORMAT -***************** - -'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.: - - * Lines beginning with '#' or ';', and blank lines, are ignored. - - * 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.) - - * One or more stars ('*') followed by a space, at the start of a - line, is ignored. So date lines or time transaction lines can also - be Org-mode headlines. - - * All Org-mode headlines before the first date line are ignored. - - 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: COMMON TASKS, Next: LIMITATIONS, Prev: TIMEDOT FORMAT, Up: Top - -16 COMMON TASKS -*************** - -Here are some quick examples of how to do some basic tasks with hledger. -For more details, see the reference section below, the -hledger_journal(5) manual, or the more extensive docs at -https://hledger.org. - -* 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: COMMON TASKS - -16.1 Getting help -================= - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show common and command options, and command help -$ hledger help # show available manuals/topics -$ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) -$ hledger help journal -m # show the journal topic, as a man page scrolled to that section -$ hledger help --help # show more detailed help for the help command - - Find more docs, chat, mail list, reddit, issue tracker: -https://hledger.org/support.html-feedback - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS - -16.2 Constructing command lines -=============================== - -hledger has an extensive and powerful command line interface. We strive -to keep it simple and ergonomic, but you may run into one of the -confusing real world details described in OPTIONS, below. If that -happens, here are some tips that may help: - - * command-specific options must go after the command (it's fine to - put all options there) ('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 is being parsed, add '--debug=2'. - - -File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS - -16.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: COMMON TASKS - -16.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: COMMON TASKS - -16.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: COMMON TASKS - -16.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: COMMON TASKS - -16.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 --flat -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 --flat -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: COMMON TASKS - -16.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. - - -File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: COMMON TASKS, Up: Top - -17 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 file -format differences. - - On large data files, hledger is slower and uses more memory than -Ledger. - - -File: hledger.info, Node: TROUBLESHOOTING, Prev: LIMITATIONS, Up: Top - -18 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 - - -Tag Table: -Node: Top208 -Node: OPTIONS2612 -Ref: #options2713 -Node: General options2855 -Ref: #general-options2980 -Node: Command options7193 -Ref: #command-options7344 -Node: Command arguments7744 -Ref: #command-arguments7902 -Node: Special characters8782 -Ref: #special-characters8945 -Node: Single escaping shell metacharacters9108 -Ref: #single-escaping-shell-metacharacters9349 -Node: Double escaping regular expression metacharacters9952 -Ref: #double-escaping-regular-expression-metacharacters10263 -Node: Triple escaping for add-on commands10789 -Ref: #triple-escaping-for-add-on-commands11049 -Node: Less escaping11693 -Ref: #less-escaping11847 -Node: Unicode characters12171 -Ref: #unicode-characters12336 -Node: Regular expressions13748 -Ref: #regular-expressions13888 -Node: ENVIRONMENT15624 -Ref: #environment15740 -Node: DATA FILES17232 -Ref: #data-files17351 -Node: Data formats17890 -Ref: #data-formats18008 -Node: Multiple files19402 -Ref: #multiple-files19544 -Node: Strict mode20013 -Ref: #strict-mode20128 -Node: TIME PERIODS20852 -Ref: #time-periods20969 -Node: Smart dates21067 -Ref: #smart-dates21193 -Node: Report start & end date23023 -Ref: #report-start-end-date23198 -Node: Report intervals24865 -Ref: #report-intervals25033 -Node: Period expressions26772 -Ref: #period-expressions26912 -Node: Period expressions with a report interval28643 -Ref: #period-expressions-with-a-report-interval28875 -Node: More complex report intervals29956 -Ref: #more-complex-report-intervals30205 -Node: Intervals with custom start date30845 -Ref: #intervals-with-custom-start-date31077 -Node: Periods or dates ?32651 -Ref: #periods-or-dates32853 -Node: Events on multiple weekdays33295 -Ref: #events-on-multiple-weekdays33474 -Node: DEPTH34337 -Ref: #depth34437 -Node: QUERIES34771 -Ref: #queries34880 -Node: Query types35821 -Ref: #query-types35940 -Node: Combining query terms39114 -Ref: #combining-query-terms39289 -Node: Queries and command options40092 -Ref: #queries-and-command-options40295 -Node: Queries and account aliases40544 -Ref: #queries-and-account-aliases40747 -Node: Queries and valuation40867 -Ref: #queries-and-valuation41060 -Node: Querying with account aliases41289 -Ref: #querying-with-account-aliases41498 -Node: Querying with cost or value41628 -Ref: #querying-with-cost-or-value41803 -Node: CONVERSION & COST42104 -Ref: #conversion-cost42237 -Node: Recording conversions43126 -Ref: #recording-conversions43298 -Node: Implicit conversion43750 -Ref: #implicit-conversion43907 -Node: Priced conversion44726 -Ref: #priced-conversion44905 -Node: Equity conversion45313 -Ref: #equity-conversion45497 -Node: Priced equity conversion46285 -Ref: #priced-equity-conversion46457 -Node: Inferring missing conversion rates46805 -Ref: #inferring-missing-conversion-rates47045 -Node: Inferring missing equity postings47161 -Ref: #inferring-missing-equity-postings47392 -Node: Cost reporting47540 -Ref: #cost-reporting47717 -Node: Conversion summary48237 -Ref: #conversion-summary48380 -Node: VALUATION49102 -Ref: #valuation49220 -Node: -V Value49987 -Ref: #v-value50111 -Node: -X Value in specified commodity50306 -Ref: #x-value-in-specified-commodity50499 -Node: Valuation date50648 -Ref: #valuation-date50810 -Node: Market prices51247 -Ref: #market-prices51429 -Node: --infer-market-prices market prices from transactions52612 -Ref: #infer-market-prices-market-prices-from-transactions52879 -Node: Valuation commodity54763 -Ref: #valuation-commodity54974 -Node: Simple valuation examples56200 -Ref: #simple-valuation-examples56396 -Node: --value Flexible valuation57055 -Ref: #value-flexible-valuation57257 -Node: More valuation examples58901 -Ref: #more-valuation-examples59108 -Node: Interaction of valuation and queries61107 -Ref: #interaction-of-valuation-and-queries61346 -Node: Effect of valuation on reports61818 -Ref: #effect-of-valuation-on-reports62013 -Node: PIVOTING69710 -Ref: #pivoting69815 -Node: OUTPUT71501 -Ref: #output71603 -Node: Output destination71694 -Ref: #output-destination71828 -Node: Output styling72485 -Ref: #output-styling72633 -Node: Output format73390 -Ref: #output-format73534 -Node: CSV output74898 -Ref: #csv-output75016 -Node: HTML output75119 -Ref: #html-output75259 -Node: JSON output75353 -Ref: #json-output75493 -Node: SQL output76410 -Ref: #sql-output76528 -Node: Commodity styles77029 -Ref: #commodity-styles77156 -Node: COMMANDS77932 -Ref: #commands78044 -Node: accounts81409 -Ref: #accounts81509 -Node: activity82317 -Ref: #activity82429 -Node: add82812 -Ref: #add82915 -Node: aregister85710 -Ref: #aregister85824 -Node: aregister and custom posting dates88493 -Ref: #aregister-and-custom-posting-dates88659 -Node: balance89211 -Ref: #balance89330 -Node: balance features90323 -Ref: #balance-features90463 -Node: Simple balance report92387 -Ref: #simple-balance-report92569 -Node: Filtered balance report94049 -Ref: #filtered-balance-report94236 -Node: List or tree mode94563 -Ref: #list-or-tree-mode94731 -Node: Depth limiting96076 -Ref: #depth-limiting96242 -Node: Dropping top-level accounts96843 -Ref: #dropping-top-level-accounts97045 -Node: Multi-period balance report97355 -Ref: #multi-period-balance-report97568 -Node: Showing declared accounts99843 -Ref: #showing-declared-accounts100036 -Node: Data layout100567 -Ref: #data-layout100722 -Node: Sorting by amount108662 -Ref: #sorting-by-amount108817 -Node: Percentages109487 -Ref: #percentages109645 -Node: Balance change end balance110606 -Ref: #balance-change-end-balance110799 -Node: Balance report types112227 -Ref: #balance-report-types112417 -Node: Useful balance reports116696 -Ref: #useful-balance-reports116877 -Node: Budget report117962 -Ref: #budget-report118146 -Node: Budget report start date123421 -Ref: #budget-report-start-date123599 -Node: Budgets and subaccounts124931 -Ref: #budgets-and-subaccounts125138 -Node: Selecting budget goals128578 -Ref: #selecting-budget-goals128750 -Node: Customising single-period balance reports129784 -Ref: #customising-single-period-balance-reports129993 -Node: balancesheet132168 -Ref: #balancesheet132306 -Node: balancesheetequity133605 -Ref: #balancesheetequity133756 -Node: cashflow135136 -Ref: #cashflow135260 -Node: check136766 -Ref: #check136871 -Node: Basic checks137505 -Ref: #basic-checks137623 -Node: Strict checks138174 -Ref: #strict-checks138315 -Node: Other checks138751 -Ref: #other-checks138891 -Node: Custom checks139248 -Ref: #custom-checks139368 -Node: close139785 -Ref: #close139889 -Node: close and prices141980 -Ref: #close-and-prices142109 -Node: close date142504 -Ref: #close-date142688 -Node: Example close asset/liability accounts for file transition143445 -Ref: #example-close-assetliability-accounts-for-file-transition143746 -Node: Hiding opening/closing transactions144605 -Ref: #hiding-openingclosing-transactions144876 -Node: close and balance assertions146253 -Ref: #close-and-balance-assertions146511 -Node: Example close revenue/expense accounts to retained earnings147865 -Ref: #example-close-revenueexpense-accounts-to-retained-earnings148143 -Node: codes149033 -Ref: #codes149143 -Node: commodities149855 -Ref: #commodities149984 -Node: descriptions150066 -Ref: #descriptions150196 -Node: diff150500 -Ref: #diff150608 -Node: files151655 -Ref: #files151757 -Node: help151904 -Ref: #help152006 -Node: import152824 -Ref: #import152940 -Node: Deduplication154033 -Ref: #deduplication154158 -Node: Import testing156052 -Ref: #import-testing156217 -Node: Importing balance assignments156705 -Ref: #importing-balance-assignments156911 -Node: Commodity display styles157560 -Ref: #commodity-display-styles157733 -Node: incomestatement157862 -Ref: #incomestatement157997 -Node: notes159302 -Ref: #notes159417 -Node: payees159785 -Ref: #payees159893 -Node: prices160419 -Ref: #prices160527 -Node: print160896 -Ref: #print161008 -Node: print-unique166376 -Ref: #print-unique166504 -Node: register166789 -Ref: #register166918 -Node: Custom register output171668 -Ref: #custom-register-output171799 -Node: register-match173136 -Ref: #register-match173272 -Node: rewrite173623 -Ref: #rewrite173740 -Node: Re-write rules in a file175646 -Ref: #re-write-rules-in-a-file175809 -Node: Diff output format176958 -Ref: #diff-output-format177141 -Node: rewrite vs print --auto178233 -Ref: #rewrite-vs.-print---auto178393 -Node: roi178949 -Ref: #roi179049 -Node: Spaces and special characters in --inv and --pnl180774 -Ref: #spaces-and-special-characters-in---inv-and---pnl181014 -Node: Semantics of --inv and --pnl181502 -Ref: #semantics-of---inv-and---pnl181741 -Node: IRR and TWR explained183591 -Ref: #irr-and-twr-explained183751 -Node: stats186837 -Ref: #stats186938 -Node: tags188318 -Ref: #tags188418 -Node: test189432 -Ref: #test189548 -Node: About add-on commands190295 -Ref: #about-add-on-commands190432 -Node: JOURNAL FORMAT191563 -Ref: #journal-format191691 -Node: Transactions193918 -Ref: #transactions194033 -Node: Dates195047 -Ref: #dates195163 -Node: Simple dates195228 -Ref: #simple-dates195348 -Node: Secondary dates195857 -Ref: #secondary-dates196005 -Node: Posting dates197341 -Ref: #posting-dates197464 -Node: Status198836 -Ref: #status198946 -Node: Code200654 -Ref: #code200766 -Node: Description200998 -Ref: #description201126 -Node: Payee and note201446 -Ref: #payee-and-note201554 -Node: Comments201889 -Ref: #comments202011 -Node: Tags203205 -Ref: #tags-1203316 -Node: Postings204709 -Ref: #postings204833 -Node: Virtual postings205859 -Ref: #virtual-postings205970 -Node: Account names207275 -Ref: #account-names207412 -Node: Amounts207900 -Ref: #amounts208037 -Node: Decimal marks digit group marks209022 -Ref: #decimal-marks-digit-group-marks209199 -Node: Commodity210220 -Ref: #commodity210409 -Node: Directives influencing number parsing and display211361 -Ref: #directives-influencing-number-parsing-and-display211622 -Node: Commodity display style212115 -Ref: #commodity-display-style212323 -Node: Rounding214518 -Ref: #rounding214638 -Node: Transaction prices215050 -Ref: #transaction-prices215216 -Node: Lot prices lot dates217647 -Ref: #lot-prices-lot-dates217830 -Node: Balance assertions218318 -Ref: #balance-assertions218496 -Node: Assertions and ordering219569 -Ref: #assertions-and-ordering219760 -Node: Assertions and multiple included files220460 -Ref: #assertions-and-multiple-included-files220722 -Node: Assertions and multiple -f files221222 -Ref: #assertions-and-multiple--f-files221475 -Node: Assertions and commodities221872 -Ref: #assertions-and-commodities222096 -Node: Assertions and prices223276 -Ref: #assertions-and-prices223484 -Node: Assertions and subaccounts223924 -Ref: #assertions-and-subaccounts224147 -Node: Assertions and virtual postings224471 -Ref: #assertions-and-virtual-postings224711 -Node: Assertions and auto postings224843 -Ref: #assertions-and-auto-postings225075 -Node: Assertions and precision225720 -Ref: #assertions-and-precision225904 -Node: Balance assignments226171 -Ref: #balance-assignments226341 -Node: Balance assignments and prices227505 -Ref: #balance-assignments-and-prices227671 -Node: Directives227895 -Ref: #directives228058 -Node: Directives and multiple files232550 -Ref: #directives-and-multiple-files232746 -Node: Comment blocks233438 -Ref: #comment-blocks233615 -Node: Including other files233791 -Ref: #including-other-files233965 -Node: Default year234889 -Ref: #default-year235047 -Node: Declaring payees235454 -Ref: #declaring-payees235625 -Node: Declaring the decimal mark235871 -Ref: #declaring-the-decimal-mark236071 -Node: Declaring commodities236468 -Ref: #declaring-commodities236659 -Node: Commodity error checking239177 -Ref: #commodity-error-checking239327 -Node: Default commodity239842 -Ref: #default-commodity240022 -Node: Declaring market prices241138 -Ref: #declaring-market-prices241327 -Node: Declaring accounts242140 -Ref: #declaring-accounts242320 -Node: Account error checking243544 -Ref: #account-error-checking243710 -Node: Account comments244889 -Ref: #account-comments245073 -Node: Account subdirectives245514 -Ref: #account-subdirectives245699 -Node: Account types246017 -Ref: #account-types246191 -Node: Account display order249866 -Ref: #account-display-order250026 -Node: Rewriting accounts251177 -Ref: #rewriting-accounts251356 -Node: Basic aliases252396 -Ref: #basic-aliases252532 -Node: Regex aliases253276 -Ref: #regex-aliases253438 -Node: Combining aliases254328 -Ref: #combining-aliases254511 -Node: Aliases and multiple files255787 -Ref: #aliases-and-multiple-files255986 -Node: end aliases256565 -Ref: #end-aliases256759 -Node: Aliases can generate bad account names256908 -Ref: #aliases-can-generate-bad-account-names257151 -Node: Aliases and account types257736 -Ref: #aliases-and-account-types257933 -Node: Default parent account258629 -Ref: #default-parent-account258819 -Node: Periodic transactions259703 -Ref: #periodic-transactions259886 -Node: Periodic rule syntax261841 -Ref: #periodic-rule-syntax262021 -Node: Periodic rules and relative dates262480 -Ref: #periodic-rules-and-relative-dates262748 -Node: Two spaces between period expression and description!263259 -Ref: #two-spaces-between-period-expression-and-description263585 -Node: Forecasting with periodic transactions264269 -Ref: #forecasting-with-periodic-transactions264568 -Node: Budgeting with periodic transactions267339 -Ref: #budgeting-with-periodic-transactions267572 -Node: Auto postings267981 -Ref: #auto-postings268117 -Node: Auto postings and multiple files270296 -Ref: #auto-postings-and-multiple-files270494 -Node: Auto postings and dates270703 -Ref: #auto-postings-and-dates270971 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions271146 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions271491 -Node: Auto posting tags271994 -Ref: #auto-posting-tags272203 -Node: CSV FORMAT272839 -Ref: #csv-format272967 -Node: Examples275596 -Ref: #examples275699 -Node: Basic275907 -Ref: #basic276009 -Node: Bank of Ireland276551 -Ref: #bank-of-ireland276688 -Node: Amazon278150 -Ref: #amazon278270 -Node: Paypal279989 -Ref: #paypal280085 -Node: CSV rules287729 -Ref: #csv-rules287847 -Node: skip288180 -Ref: #skip288280 -Node: fields list288655 -Ref: #fields-list288794 -Node: field assignment290360 -Ref: #field-assignment290512 -Node: Field names291547 -Ref: #field-names291687 -Node: date field292067 -Ref: #date-field292187 -Node: date2 field292235 -Ref: #date2-field292378 -Node: status field292434 -Ref: #status-field292579 -Node: code field292628 -Ref: #code-field292775 -Node: description field292820 -Ref: #description-field292982 -Node: comment field293041 -Ref: #comment-field293198 -Node: account field293509 -Ref: #account-field293661 -Node: amount field294236 -Ref: #amount-field294387 -Node: currency field295632 -Ref: #currency-field295787 -Node: balance field296044 -Ref: #balance-field296178 -Node: separator296550 -Ref: #separator296682 -Node: if block297222 -Ref: #if-block297349 -Node: Matching the whole record297750 -Ref: #matching-the-whole-record297927 -Node: Matching individual fields298730 -Ref: #matching-individual-fields298936 -Node: Combining matchers299160 -Ref: #combining-matchers299358 -Node: Rules applied on successful match299671 -Ref: #rules-applied-on-successful-match299864 -Node: if table300518 -Ref: #if-table300639 -Node: end302377 -Ref: #end302491 -Node: date-format302715 -Ref: #date-format302849 -Node: decimal-mark303845 -Ref: #decimal-mark303992 -Node: newest-first304331 -Ref: #newest-first304474 -Node: include305157 -Ref: #include305290 -Node: balance-type305734 -Ref: #balance-type305856 -Node: Tips306556 -Ref: #tips306647 -Node: Rapid feedback306946 -Ref: #rapid-feedback307065 -Node: Valid CSV307517 -Ref: #valid-csv307649 -Node: File Extension307841 -Ref: #file-extension307995 -Node: Reading multiple CSV files308424 -Ref: #reading-multiple-csv-files308611 -Node: Valid transactions308852 -Ref: #valid-transactions309032 -Node: Deduplicating importing309660 -Ref: #deduplicating-importing309841 -Node: Setting amounts310877 -Ref: #setting-amounts311034 -Node: Amount signs313478 -Ref: #amount-signs313632 -Node: Setting currency/commodity314319 -Ref: #setting-currencycommodity314507 -Node: Amount decimal places315681 -Ref: #amount-decimal-places315873 -Node: Referencing other fields316185 -Ref: #referencing-other-fields316384 -Node: How CSV rules are evaluated317281 -Ref: #how-csv-rules-are-evaluated317456 -Node: TIMECLOCK FORMAT318907 -Ref: #timeclock-format319047 -Node: TIMEDOT FORMAT321108 -Ref: #timedot-format321246 -Node: COMMON TASKS325808 -Ref: #common-tasks325937 -Node: Getting help326344 -Ref: #getting-help326478 -Node: Constructing command lines327068 -Ref: #constructing-command-lines327262 -Node: Starting a journal file327959 -Ref: #starting-a-journal-file328159 -Node: Setting opening balances329347 -Ref: #setting-opening-balances329545 -Node: Recording transactions332686 -Ref: #recording-transactions332868 -Node: Reconciling333424 -Ref: #reconciling333569 -Node: Reporting335826 -Ref: #reporting335968 -Node: Migrating to a new file339967 -Ref: #migrating-to-a-new-file340117 -Node: LIMITATIONS340416 -Ref: #limitations340544 -Node: TROUBLESHOOTING341287 -Ref: #troubleshooting341402 +manual is for hledger 1.26.1. + + 'hledger' + + 'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]' + + 'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]' + + hledger is a reliable, cross-platform set of programs for tracking +money, time, or any other commodity, using double-entry accounting and a +simple, editable file format. hledger is inspired by and largely +compatible with ledger(1). + + The basic function of the hledger CLI is to read a plain text file +describing financial transactions (in accounting terms, a general +journal) and print useful reports on standard output, or export them as +CSV. hledger can also read some other file formats such as CSV files, +translating them to journal format. Additionally, hledger lists other +hledger-* executables found in the user's $PATH and can invoke them as +subcommands. + + hledger reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). If using '$LEDGER_FILE', note this +must be a real environment variable, not a shell variable. You can +specify standard input with '-f-'. + + Transactions are dated movements of money between two (or more) named +accounts, and are recorded with journal entries like this: + +2015/10/16 bought food + expenses:food $10 + assets:cash + + Most users use a text editor to edit the journal, usually with an +editor mode such as ledger-mode for added convenience. hledger's +interactive add command is another way to record new transactions. +hledger never changes existing transactions. + + To get started, you can either save some entries like the above in +'~/.hledger.journal', or run 'hledger add' and follow the prompts. Then +try some commands like 'hledger print' or 'hledger balance'. Run +'hledger' with no arguments for a list of commands. + +* Menu: + +* OPTIONS:: +* ENVIRONMENT:: +* DATA FILES:: +* TIME PERIODS:: +* DEPTH:: +* QUERIES:: +* CONVERSION & COST:: +* VALUATION:: +* PIVOTING:: +* OUTPUT:: +* COMMANDS:: +* JOURNAL FORMAT:: +* CSV FORMAT:: +* TIMECLOCK FORMAT:: +* TIMEDOT FORMAT:: +* COMMON TASKS:: +* LIMITATIONS:: +* TROUBLESHOOTING:: + + +File: hledger.info, Node: OPTIONS, Next: ENVIRONMENT, Prev: Top, Up: Top + +1 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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 + +1.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 directives and options: '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: DATA FILES, Prev: OPTIONS, Up: Top + +2 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\MyUserName\.hledger.journal'. You can change this by running +a command like this in a powershell window: + +> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" + + (Let us know if you need to be an Administrator, and if this persists +across a reboot.) + + *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: DATA FILES, Next: TIME PERIODS, Prev: ENVIRONMENT, Up: Top + +3 DATA FILES +************ + +hledger reads transactions from one or more data files. The default +data file is '$HOME/.hledger.journal' (or on Windows, something like +'C:/Users/USER/.hledger.journal'). + + You can override this with the '$LEDGER_FILE' environment variable: + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with 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: DATA FILES + +3.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 their own sections, 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: DATA FILES + +3.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: DATA FILES + +3.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: TIME PERIODS, Next: DEPTH, Prev: DATA FILES, Up: Top + +4 TIME PERIODS +************** + +* Menu: + +* Smart dates:: +* Report start & end date:: +* Report intervals:: +* Period expressions:: + + +File: hledger.info, Node: Smart dates, Next: Report start & end date, Up: TIME PERIODS + +4.1 Smart dates +=============== + +hledger's user interfaces accept a flexible "smart date" syntax. Smart +dates allow some english words, can be relative to today's date, and can +have less-significant date parts omitted (defaulting to 1). + + Examples: + +'2004/10/1', 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 + + 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 + + Note "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; those are not affected by '--today'.) + + +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: TIME PERIODS + +4.2 Report start & end date +=========================== + +By default, most hledger reports will show the full span of time +represented by the journal data. 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. + + 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. + * A report interval (see below) will adjust start/end dates, when + needed, so that they fall on subperiod boundaries. + + 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: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: TIME PERIODS + +4.3 Report intervals +==================== + +A report interval can be specified so that commands like register, +balance and activity become multi-period, showing each subperiod as a +separate row or column. + + The following "standard" report intervals can be enabled by using +their corresponding flag: + + * '-D/--daily' + * '-W/--weekly' + * '-M/--monthly' + * '-Q/--quarterly' + * '-Y/--yearly' + + These standard intervals always start on natural interval boundaries: +eg '--weekly' starts on mondays, '--monthly' starts on the first of the +month, '--yearly' always starts on January 1st, etc. + + Certain more complex intervals, and more flexible boundary dates, can +be specified by '-p/--period'. These are described in period +expressions, below. + + Report intervals can only be specified by the flags above, and not by +query arguments, currently. + + Report intervals have another effect: multi-period reports are always +expanded to fill a whole number of subperiods. So if you use a report +interval (other than '--daily'), and you have specified a start or end +date, you may notice those dates being overridden (ie, the report starts +earlier than your requested start date, or ends later than your +requested end date). This is done to ensure "full" first and last +subperiods, so that all subperiods' numbers are comparable. + + To summarise: + + * In multiperiod reports, all subperiods are forced to be the same + length, to simplify reporting. + * Reports with the standard + '--weekly'/'--monthly'/'--quarterly'/'--yearly' intervals are + required to start on the first day of a week/month/quarter/year. + We'd like more flexibility here but it isn't supported yet. + * '--period' (below) can specify more complex intervals, starting on + any date. + + +File: hledger.info, Node: Period expressions, Prev: Report intervals, Up: TIME PERIODS + +4.4 Period expressions +====================== + +The '-p/--period' option accepts period expressions, a shorthand way of +expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of +2009. Note, hledger always treats start dates as inclusive and end +dates as exclusive: + +'-p "from 2009/1/1 to 2009/4/1"' + + Keywords like "from" and "to" are optional, and so are the spaces, as +long as you don't run two dates together. "to" can also be written as +".." or "-". These are equivalent to the above: + +'-p "2009/1/1 2009/4/1"' +'-p2009/1/1to2009/4/1' +'-p2009/1/1..2009/4/1' + + Dates are smart dates, so if the current year is 2009, the above can +also be written as: + +'-p "1/1 4/1"' +'-p "january-apr"' +'-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction in your journal: + +'-p "from 2009/1/1"' everything after january 1, 2009 +'-p "from 2009/1"' the same +'-p "from 2009"' the same +'-p "to 2009"' everything before january 1, 2009 + + A single date with no "from" or "to" defines both the start and end +date like so: + +'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” +'-p "2009/1"' the month of jan; equivalent to “2009/1/1 to 2009/2/1” +'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2” + + Or you can specify a single quarter like so: + +'-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:: +* Intervals with custom start date:: +* Periods or dates ?:: +* Events on multiple weekdays:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +4.4.1 Period expressions with a report interval +----------------------------------------------- + +'-p/--period''s argument can also begin with, or entirely consist of, a +report interval. This should be separated from the start/end dates (if +any) by a space, or the word 'in'. The basic intervals (which can also +be written as command line flags) are 'daily', 'weekly', 'monthly', +'quarterly', and 'yearly'. Some examples: + +'-p "weekly from 2009/1/1 to 2009/4/1"' +'-p "monthly in 2008"' +'-p "quarterly"' + + As mentioned above, the 'weekly', 'monthly', 'quarterly' and 'yearly' +intervals require a report start date that is the first day of a week, +month, quarter or year. And, report start/end dates will be expanded if +needed to span a whole number of intervals. + + For example: + +'-p "weekly from starts on 2008/12/29, closest preceding +2009/1/1 to 2009/4/1"' Monday +'-p "monthly in starts on 2018/11/01 +2008/11/25"' +'-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, +2009-05-05 to which are first and last days of Q2 2009 +2009-06-01"' +'-p "yearly from starts on 2009/01/01, first day of 2009 +2009-12-29"' + + +File: hledger.info, Node: More complex report intervals, Next: Intervals with custom start date, Prev: Period expressions with a report interval, Up: Period expressions + +4.4.2 More complex report intervals +----------------------------------- + +Some more complex kinds of interval are also supported in period +expressions: + + * 'biweekly' + * 'fortnightly' + * 'bimonthly' + * 'every day|week|month|quarter|year' + * 'every N days|weeks|months|quarters|years' + + These too will cause report start/end dates to be expanded, if +needed, to span a whole number of intervals. Examples: + +'-p "bimonthly from periods will have boundaries on 2008/01/01, +2008"' 2008/03/01, ... +'-p "every 2 weeks"' starts on closest preceding Monday +'-p "every 5 months from periods will have boundaries on 2009/03/01, +2009/03"' 2009/08/01, ... + + +File: hledger.info, Node: Intervals with custom start date, Next: Periods or dates ?, Prev: More complex report intervals, Up: Period expressions + +4.4.3 Intervals with custom start date +-------------------------------------- + +All intervals mentioned above are required to start on their natural +calendar boundaries, but the following intervals can start on any date: + + Weekly on 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 custom day: + + * 'every Nth day [of month]' + * 'every Nth WEEKDAYNAME [of month]' + + Yearly on 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 "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 period boundaries will be on second Monday of +Monday"' each month +'-p "every 11/05"' yearly periods with boundaries on 5th of + November +'-p "every 5th same +November"' +'-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: Periods or dates ?, Next: Events on multiple weekdays, Prev: Intervals with custom start date, Up: Period expressions + +4.4.4 Periods or dates ? +------------------------ + +Report intervals like the above are most often used with '-p|--period', +to divide reports into multiple subperiods - each generated date marks a +subperiod boundary. Here, the periods between the dates are what's +important. + + But report intervals can also be used with '--forecast' to generate +future transactions, or with 'balance --budget' to generate budget +goal-setting transactions. For these, the dates themselves are what +matters. + + +File: hledger.info, Node: Events on multiple weekdays, Prev: Periods or dates ?, Up: Period expressions + +4.4.5 Events on multiple weekdays +--------------------------------- + +The 'every WEEKDAYNAME' form has a special variant with multiple day +names, comma-separated. Eg: 'every mon,thu,sat'. Also, 'weekday' and +'weekendday' are shorthand for 'mon,tue,wed,thu,fri' and 'sat,sun' +respectively. + + This form 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. (Because gaps between periods are not allowed; if you'd like to +change this, see #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 + +5 DEPTH +******* + +With the '--depth NUM' option (short form: '-NUM'), commands like +account, balance and register will show only the uppermost accounts in +the account tree, down to level NUM. 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: CONVERSION & COST, Prev: DEPTH, Up: Top + +6 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 account aliases:: +* Queries and valuation:: +* Querying with account aliases:: +* Querying with cost or value:: + + +File: hledger.info, Node: Query types, Next: Combining query terms, Up: QUERIES + +6.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 + +6.2 Combining 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. + + while the print command shows transactions which: + + * match any of the description terms AND + * have any postings matching any of the positive account terms AND + * have no postings matching any of the negative account terms AND + * match all the other terms. + + You can do more powerful queries (such as AND-ing two like terms) by +running a first query with 'print', and piping the result into a second +hledger command. Eg: how much of food expenses was paid with cash ? + +$ hledger print assets:cash | hledger -f- -I balance expenses:food + + If you are interested in full boolean expressions for queries, see +#203. + + +File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Combining query terms, Up: QUERIES + +6.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 account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: QUERIES + +6.4 Queries and account aliases +=============================== + +When account names are rewritten with '--alias' or 'alias', 'acct:' will +match either the old or the new account name. + + +File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and account aliases, Up: QUERIES + +6.5 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 + +6.6 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 + +6.7 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: CONVERSION & COST, Next: VALUATION, Prev: QUERIES, Up: Top + +7 CONVERSION & COST +******************* + +This section is about converting between commodities. Some definitions: + + * A "commodity conversion" is an exchange of one currency or + commodity for another. Eg a foreign currency exchange, or a + purchase or sale of stock or cryptocurrency. + + * A "conversion transaction" is a transaction involving one or more + such conversions. + + * "Conversion rate" is the exchange rate in a conversion - the cost + per unit of one commodity in the other. + + * "Cost" is how much of one commodity was paid to acquire the other + (when buying), or how much was received in exchange for the other + (when selling). We call both of these "cost" for convenience + (after all, it is cost for one party or the other). + +* Menu: + +* Recording conversions:: +* Inferring missing conversion rates:: +* Inferring missing equity postings:: +* Cost reporting:: +* Conversion summary:: + + +File: hledger.info, Node: Recording conversions, Next: Inferring missing conversion rates, Up: CONVERSION & COST + +7.1 Recording conversions +========================= + +As a concrete example, let's assume 100 EUR was converted to 120 USD. +There are several ways to record this in the journal, each with pros and +cons which will be explained in more detail below. (Also, these +examples use journal format which is properly explained much further +below; sorry about that, you may want to read some of that first.) + +* Menu: + +* Implicit conversion:: +* Priced conversion:: +* Equity conversion:: +* Priced equity conversion:: + + +File: hledger.info, Node: Implicit conversion, Next: Priced conversion, Up: Recording conversions + +7.1.1 Implicit conversion +------------------------- + +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: + + * Easy, concise + * hledger can do cost reporting + + Con: + + * Less error checking - typos in amounts or commodity symbols may not + be detected + * conversion rate is not clear + * disturbs the accounting equation + + 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: Priced conversion, Next: Equity conversion, Prev: Implicit conversion, Up: Recording conversions + +7.1.2 Priced conversion +----------------------- + +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 some error checking + * hledger can do cost reporting + + Con: + + * Disturbs the accounting equation + + +File: hledger.info, Node: Equity conversion, Next: Priced equity conversion, Prev: Priced conversion, Up: Recording conversions + +7.1.3 Equity conversion +----------------------- + +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 + * works in any double entry accounting system + + Con: + + * More verbose + * conversion rate is not clear + * hledger can not do cost reporting + + +File: hledger.info, Node: Priced equity conversion, Prev: Equity conversion, Up: Recording conversions + +7.1.4 Priced equity conversion +------------------------------ + +Another possible notation would be to record both the conversion rate +and the equity postings: + +2021-01-01 + assets:cash -100 EUR @ 1.20 USD + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + hledger currently does not allow this; instead, you can record the +conversion rate as a comment. + + +File: hledger.info, Node: Inferring missing conversion rates, Next: Inferring missing equity postings, Prev: Recording conversions, Up: CONVERSION & COST + +7.2 Inferring missing conversion rates +====================================== + +hledger will do this automatically for implicit conversions. Currently +it can not do this for equity conversions. + + +File: hledger.info, Node: Inferring missing equity postings, Next: Cost reporting, Prev: Inferring missing conversion rates, Up: CONVERSION & COST + +7.3 Inferring missing equity postings +===================================== + +With the '--infer-equity' flag, hledger will add equity postings to +priced and implicit conversions (and move the conversion rate into a +comment). + + +File: hledger.info, Node: Cost reporting, Next: Conversion summary, Prev: Inferring missing equity postings, Up: CONVERSION & COST + +7.4 Cost reporting +================== + +With the '-B/--cost' flag, hledger will convert the amounts in priced +and implicit conversions to their cost in the other commodity. This is +useful to see a report of what you paid for things (or how much you sold +things for). Currently '-B/--cost' does not work on equity conversions, +and it disables '--infer-equity'. + + These operations are transient, only affecting reports. If you want +to change the journal file permanently, you could pipe each entry +through 'hledger -f- -I print [-x] [--infer-equity] [-B]' + + +File: hledger.info, Node: Conversion summary, Prev: Cost reporting, Up: CONVERSION & COST + +7.5 Conversion summary +====================== + + * Recording the conversion rate is good because it makes that clear + and allows cost reporting. + * Recording equity postings is good because it balances the + accounting equation and is correct bookkeeping. + * Combining these is not yet supported, so you have to choose. For + now, priced conversions are a good compromise, so that: + * When you want to see the cost (or sale proceeds) of things, + use '-B/--cost'. + * When you want to see a balanced balance sheet or correct + journal entries, use '--infer-equity'. + * Combining these is not yet supported; '-B/--cost' will take + precedence. + + * Conversion/cost operations are performed before valuation. + + +File: hledger.info, Node: VALUATION, Next: PIVOTING, Prev: CONVERSION & COST, Up: Top + +8 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:: +* Market prices:: +* --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 + +8.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 + +8.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: Market prices, Prev: -X Value in specified commodity, Up: VALUATION + +8.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: Market prices, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: VALUATION + +8.4 Market prices +================= + +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 transaction prices. + + 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: Market prices, Up: VALUATION + +8.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 transaction prices as additional market +prices (as Ledger does) ? We could produce value reports without +needing P directives at all. + + 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. +(And 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.) + + * but not, currently, from "more correct" multicommodity transactions + (no '@', multiple commodities, balanced). + + There is another 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' + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: VALUATION + +8.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, transaction prices 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 + +8.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 + +8.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 + +8.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 + +8.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 + +8.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: PIVOTING, Next: OUTPUT, Prev: VALUATION, Up: Top + +9 PIVOTING +********** + +Normally hledger sums amounts, and organizes them in a hierarchy, based +on account name. The '--pivot FIELD' option causes it to sum and +organize hierarchy based on the value of some other field instead. +FIELD can be: 'status', 'code', 'description', 'payee', 'note', or the +full name (case insensitive) of any tag. As with account names, values +containing 'colon:separated:parts' will be displayed hierarchically in +reports. + + '--pivot' is a general option affecting all reports; you can think of +hledger transforming the journal before any other processing, replacing +every posting's account name with the value of the specified field on +that posting, inheriting it from the transaction or using a blank value +if it's not present. + + An example: + +2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query, +described below): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: OUTPUT, Next: COMMANDS, Prev: PIVOTING, Up: Top + +10 OUTPUT +********* + +* Menu: + +* Output destination:: +* Output styling:: +* Output format:: +* Commodity styles:: + + +File: hledger.info, Node: Output destination, Next: Output styling, Up: OUTPUT + +10.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) + + hledger can optionally produce debug output (if enabled with +'--debug=N'); this goes to stderr, and is not affected by +'-o/--output-file'. If you need to capture it, use shell redirects, eg: +'hledger bal --debug=3 >file 2>&1'. + + +File: hledger.info, Node: Output styling, Next: Output format, Prev: Output destination, Up: OUTPUT + +10.2 Output styling +=================== + +hledger commands can produce colour output when the terminal supports +it. This is controlled by the '--color/--colour' option: - 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. + + hledger commands can also use unicode box-drawing characters to +produce prettier tables and output. This is controlled by the +'--pretty' option: - 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: Output format, Next: Commodity styles, Prev: Output styling, Up: OUTPUT + +10.3 Output format +================== + +Some commands offer additional output formats, other than the usual +plain text terminal output. Here are those commands and the formats +currently supported: + +- txt csv html json sql +------------------------------------------------------------ +aregister 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 + +* Menu: + +* CSV output:: +* HTML output:: +* JSON output:: +* SQL output:: + + +File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format + +10.3.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 + +10.3.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 + +10.3.3 JSON output +------------------ + + * Not yet much used; real-world feedback is welcome. + + * Our JSON is rather large and verbose, as it is quite 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 + +10.3.4 SQL output +----------------- + + * 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, Prev: Output format, Up: OUTPUT + +10.4 Commodity styles +===================== + +The display style of a commodity/currency is inferred according to the +rules described in Commodity display style. The inferred display style +can be overridden by an optional '-c/--commodity-style' option +(Exceptions: as is the case for inferred styles, price amounts, and all +amounts displayed by the 'print' command, will be displayed with all of +their decimal digits visible, regardless of the specified precision). +For example, the following will override the display style for dollars. + +$ hledger print -c '$1.000,0' + + The format specification of the style is identical to the commodity +display style specification for the commodity directive. The command +line option can be supplied repeatedly to override the display style for +multiple commodity/currency symbols. + + +File: hledger.info, Node: COMMANDS, Next: JOURNAL FORMAT, Prev: OUTPUT, Up: Top + +11 COMMANDS +*********** + +hledger provides a number of commands for producing reports and managing +your data. 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'. + + Here are the built-in commands, with the most often-used in bold: + + *Data entry:* + + These data entry commands are the only ones which can modify your +journal file. + + * *add* - add transactions using guided prompts + * *import* - add any new transactions from other files (eg csv) + + *Data management:* + + * check - check for various kinds of issue in the data + * close (equity) - generate balance-resetting transactions + * diff - compare account transactions in two journal files + * rewrite - generate extra postings, similar to print -auto + + *Financial statements:* + + * *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 + * roi - show return on investments + + *Miscellaneous reports:* + + * accounts - show account names + * activity - show postings-per-interval bar charts + * *balance (bal)* - show balance changes/end balances/budgets in any + accounts + * codes - show transaction codes + * commodities - show commodity/currency symbols + * descriptions - show unique transaction descriptions + * files - show input file paths + * help - show hledger user manuals in several formats + * notes - show unique note segments of transaction descriptions + * payees - show unique payee segments of transaction descriptions + * prices - show market price records + * *print* - show transactions (journal entries) + * print-unique - show only transactions with unique descriptions + * *register (reg)* - show postings in one or more accounts & running + total + * register-match - show a recent posting that best matches a + description + * stats - show journal statistics + * tags - show tag names + * test - run self tests + + *Add-on commands:* + + Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on +commands; these appear in the commands list with a '+' mark. Two of +these are maintained and released with hledger: + + * *ui* - an efficient terminal interface (TUI) for hledger + * *web* - a simple web interface (WUI) for hledger + + And these add-ons are maintained separately: + + * iadd - a more interactive alternative for the add command + * interest - generates interest transactions according to various + schemes + * stockquotes - downloads market prices for your commodities from + AlphaVantage _(experimental)_ + + Next, the detailed command docs, in alphabetical order. + +* Menu: + +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* payees:: +* prices:: +* print:: +* print-unique:: +* register:: +* register-match:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: +* About add-on commands:: + + +File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS + +11.1 accounts +============= + +accounts +Show account names. + + This command lists account names, either declared with account +directives (-declared), posted to (-used), or both (the default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +'--tree', it uses indentation to show the account hierarchy. In flat +mode you can add '--drop N' to omit the first few account name +components. Account names can be depth-clipped with 'depth:N' or +'--depth N' or '-N'. + + With '--types', it also shows each account's type, if it's known. +(See Declaring accounts > Account types.) + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS + +11.2 activity +============= + +activity +Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). With query arguments, it counts only matched transactions. + + Examples: + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** + + +File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS + +11.3 add +======== + +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, + 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 the tutorial for a detailed explanation): + +$ hledger add +Adding transactions to journal file /src/hledger/examples/sample.journal +Any command line arguments will be used as defaults. +Use tab key to complete, readline keys to edit, enter to accept defaults. +An optional (CODE) may follow transaction dates. +An optional ; COMMENT may follow descriptions or amounts. +If you make a mistake, enter < at any prompt to 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: COMMANDS + +11.4 aregister +============== + +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. +(Eg if you have 'assets:aaa:checking' and 'assets:bbb:checking' +accounts, 'hledger areg checking' would select 'assets:aaa:checking'.) + + 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 + +11.4.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: COMMANDS + +11.5 balance +============ + +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:: +* Filtered balance report:: +* List or tree mode:: +* Depth limiting:: +* Dropping top-level accounts:: +* Multi-period balance report:: +* Showing declared accounts:: +* Data layout:: +* Sorting by amount:: +* Percentages:: +* Balance change end balance:: +* Balance report types:: +* Useful balance reports:: +* Budget report:: +* Customising single-period balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +11.5.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: Filtered balance report, Prev: balance features, Up: balance + +11.5.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. For real-world +accounts, this should also match 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: Filtered balance report, Next: List or tree mode, Prev: Simple balance report, Up: balance + +11.5.3 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 + +11.5.4 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 + +11.5.5 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: Multi-period balance report, Prev: Depth limiting, Up: balance + +11.5.6 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: Multi-period balance report, Next: Showing declared accounts, Prev: Dropping top-level accounts, Up: balance + +11.5.7 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: Showing declared accounts, Next: Data layout, Prev: Multi-period balance report, Up: balance + +11.5.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: Data layout, Next: Sorting by amount, Prev: Showing declared accounts, Up: balance + +11.5.9 Data layout +------------------ + +The '--layout' option affects how multi-commodity amounts are displayed, +and some other things, influencing the overall layout of the report +data: + + * '--layout=wide[,WIDTH]': commodities are shown on a single line, + possibly elided to the specified width + * '--layout=tall': each commodity is shown on a separate line + * '--layout=bare': amounts are shown as bare numbers, with commodity + symbols in a separate column + * '--layout=tidy': data is normalised to tidy form, with one row per + data value. We currently support this with CSV output only. In + tidy mode, totals and row averages are disabled ('-N/--no-total' is + implied and '-T/--row-total' and '-A/--average' will be ignored). + + These '--layout' modes are supported with some but not all of the +output formats: + +- 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 when 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 + is a column and each row represents a single data point (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). + This kind of data is the easiest to process with other software: + + $ 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: Sorting by amount, Next: Percentages, Prev: Data layout, Up: balance + +11.5.10 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: Balance change end balance, Prev: Sorting by amount, Up: balance + +11.5.11 Percentages +------------------- + +With '-%/--percent', balance reports show each account's value expressed +as a percentage of the (column) total: + +$ hledger -f examples/sample.journal bal expenses -Q -% +Balance changes in 2008: + + || 2008Q1 2008Q2 2008Q3 2008Q4 +===================++================================= + expenses:food || 0 50.0 % 0 0 + expenses:supplies || 0 50.0 % 0 0 +-------------------++--------------------------------- + || 0 100.0 % 0 0 + + 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: Balance change end balance, Next: Balance report types, Prev: Percentages, Up: balance + +11.5.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: Useful balance reports, Prev: Balance change end balance, Up: balance + +11.5.13 Balance report types +---------------------------- + +For more flexible reporting, there are three important option groups: + + 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] +...' + + The first two are the most important: calculation type selects the +basic calculation to perform for each table cell, while accumulation +type says which postings should be included in each cell's calculation. +Typically one or both of these are selected by default, so you don't +need to write them explicitly. A valuation type can be added if you +want to convert the basic report to value or cost. + + *Calculation type:* +The basic calculation to perform for each table cell. It is one of: + + * '--sum' : sum the posting amounts (*default*) + * '--budget' : like -sum but also show a goal amount + * '--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) + + *Accumulation type:* +Which postings should be included in each cell's calculation. It is one +of: + + * '--change' : postings from column start to column end, ie within + the cell's period. Typically used to see revenues/expenses. + (*default for balance, incomestatement*) + + * '--cumulative' : postings from report start to column end, eg to + show changes accumulated since the report's start date. Rarely + used. + + * '--historical/-H' : postings from journal start to column end, ie + all postings from account creation to the end of the cell's period. + Typically used to see historical end balances of + assets/liabilities/equity. (*default for balancesheet, + balancesheetequity, cashflow*) + + *Valuation type:* +Which kind of valuation, valuation date(s) and optionally a target +valuation commodity to use. It is one of: + + * no valuation, show amounts in their original commodities + (*default*) + * '--value=cost[,COMM]' : no valuation, show amounts converted to + cost + * '--value=then[,COMM]' : show value at transaction dates + * '--value=end[,COMM]' : show value at period end date(s) (*default + with '--valuechange', '--gain'*) + * '--value=now[,COMM]' : show value at today's date + * '--value=YYYY-MM-DD[,COMM]' : show value at another date + + or one of their aliases: '--cost/-B', '--market/-V' or +'--exchange/-X'. + + 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: YYYY-MM-DD +v /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: Useful balance reports, Next: Budget report, Prev: Balance report types, Up: balance + +11.5.14 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: Budget report, Next: Customising single-period balance reports, Prev: Useful balance reports, Up: balance + +11.5.15 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 very 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] + + For more examples and notes, see Budgeting. + +* Menu: + +* Budget report start date:: +* Budgets and subaccounts:: +* Selecting budget goals:: + + +File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report + +11.5.15.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 + +11.5.15.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, Prev: Budgets and subaccounts, Up: Budget report + +11.5.15.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 the +print command 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: Customising single-period balance reports, Prev: Budget report, Up: balance + +11.5.16 Customising single-period balance reports +------------------------------------------------- + +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 (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS + +11.6 balancesheet +================= + +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: COMMANDS + +11.7 balancesheetequity +======================= + +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: COMMANDS + +11.8 cashflow +============= + +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: COMMANDS + +11.9 check +========== + +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 + + Here are the checks currently available: + +* Menu: + +* Basic checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: + + +File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check + +11.9.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 transaction prices or automatically-inferred + transaction prices + + * *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 + +11.9.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 transaction prices but not inferred ones + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +11.9.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 + + * *uniqueleafnames* - all account leaf names are unique + + +File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check + +11.9.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: close, Next: codes, Prev: check, Up: COMMANDS + +11.10 close +=========== + +close, equity +Prints a sample "closing" transaction bringing specified account +balances to zero, and an inverse "opening" transaction restoring the +same account balances. + + If like most people you split your journal files by time, eg by year: +at the end of the year you can use this command to "close out" your +asset and liability (and perhaps equity) balances in the old file, and +reinitialise them in the new file. This helps ensure that report +balances remain correct whether you are including old files or not. +(Because all closing/opening transactions except the very first will +cancel out - see example below.) + + Some people also use this command to close out revenue and expense +balances at the end of an accounting period. This properly records the +period's profit/loss as "retained earnings" (part of equity), and allows +the accounting equation (A-L=E) to balance, which you could then check +by the bse report's zero total. + + You can print just the closing transaction by using the '--close' +flag, or just the opening transaction with the '--open' flag. + + Their descriptions are 'closing balances' and 'opening balances' by +default; you can customise these with the '--close-desc' and +'--open-desc' options. + + Just one balancing equity posting is used by default, with the amount +left implicit. The default account name is 'equity:opening/closing +balances'. You can customise the account name(s) with '--close-acct' +and '--open-acct'. (If you specify only one of these, it will be used +for both.) + + With '--x/--explicit', the equity posting's amount will be shown +explicitly, and if it involves multiple commodities, there will be a +separate equity posting for each commodity (as in the print command). + + With '--interleaved', each equity posting is shown next to the +posting it balances (good for troubleshooting). + +* Menu: + +* close and prices:: +* close date:: +* Example close asset/liability accounts for file transition:: +* Hiding opening/closing transactions:: +* close and balance assertions:: +* Example close revenue/expense accounts to retained earnings:: + + +File: hledger.info, Node: close and prices, Next: close date, Up: close + +11.10.1 close and prices +------------------------ + +Transaction prices are ignored (and discarded) by closing/opening +transactions, by default. With '--show-costs', they are preserved; +there will be a separate equity posting for each cost in each commodity. +This means 'balance -B' reports will look the same after the transition. +Note if you have many foreign currency or investment transactions, this +will generate very large journal entries. + + +File: hledger.info, Node: close date, Next: Example close asset/liability accounts for file transition, Prev: close and prices, Up: close + +11.10.2 close date +------------------ + +The default closing date is yesterday, or the journal's end date, +whichever is later. + + Unless you are running 'close' on exactly the first day of the new +period, you'll want to override the closing date. This is done by +specifying a report end date, where "last day of the report period" will +be the closing date. The opening date is always the following day. So +to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any +of these will work: + +end date explanation +argument +------------------------------------------------------------------- +'-e 2021-01-01' end dates are exclusive +'-e 2021' equivalent, per smart dates +'-p 2020' equivalent, the period's begin date is ignored +'date:2020' equivalent query + + +File: hledger.info, Node: Example close asset/liability accounts for file transition, Next: Hiding opening/closing transactions, Prev: close date, Up: close + +11.10.3 Example: close asset/liability accounts for file transition +------------------------------------------------------------------- + +Carrying asset/liability balances from 2020.journal into a new file for +2021: + +$ hledger close -f 2020.journal -p 2020 assets liabilities +# copy/paste the closing transaction to the end of 2020.journal +# copy/paste the opening transaction to the start of 2021.journal + + Or: + +$ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction +$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction + + Now, + +$ hledger bs -f 2021.journal # just new file - balances correct +$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct +$ hledger bs -f 2020.journal # just old files - balances are zero ? + # (exclude final closing txn, see below) + + +File: hledger.info, Node: Hiding opening/closing transactions, Next: close and balance assertions, Prev: Example close asset/liability accounts for file transition, Up: close + +11.10.4 Hiding opening/closing transactions +------------------------------------------- + +Although the closing/opening transactions cancel out, they will be +visible in reports like 'print' and 'register', creating some visual +clutter. You can exclude them all with a query, like: + +$ hledger print not:desc:'opening|closing' # less typing +$ hledger print not:'equity:opening/closing balances' # more precise + + But when reporting on multiple files, this can get a bit tricky; you +may need to keep the earliest opening balances, for a historical +register report; or you may need to suppress a closing transaction, to +see year-end balances. If you find yourself needing more precise +queries, here's one solution: add more easily-matched tags to +opening/closing transactions, like this: + +; 2019.journal +2019-01-01 opening balances ; earliest opening txn, no tag here +... +2019-12-31 closing balances ; clopen:2020 +... + +; 2020.journal +2020-01-01 opening balances ; clopen:2020 +... +2020-12-31 closing balances ; clopen:2021 +... + +; 2021.journal +2021-01-01 opening balances ; clopen:2021 +... + + Now with + +; all.journal +include 2019.journal +include 2020.journal +include 2021.journal + + you could do eg: + +$ hledger -f all.journal reg -H checking not:tag:clopen + # all years checking register, hiding non-essential opening/closing txns + +$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 + # 2020 year end balances, suppressing 2020 closing txn + + +File: hledger.info, Node: close and balance assertions, Next: Example close revenue/expense accounts to retained earnings, Prev: Hiding opening/closing transactions, Up: close + +11.10.5 close and balance assertions +------------------------------------ + +The closing and opening transactions will include balance assertions, +verifying that the accounts have first been reset to zero and then +restored to their previous balance. These provide valuable error +checking, alerting you when things get out of line, but you can ignore +them temporarily with '-I' or just remove them if you prefer. + + You probably shouldn't use status or realness filters (like -C or -R +or 'status:') with 'close', or the generated balance assertions will +depend on these flags. Likewise, if you run this command with '--auto', +the balance assertions would probably always require '--auto'. + + Multi-day transactions (where some postings have a different date) +break the balance assertions, because the money is temporarily +"invisible" while in transit: + +2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + assets:bank:checking -5 ; date: 2021/1/2 + + To fix the assertions, you can add a temporary account to track such +in-transit money (splitting the multi-day transaction into two +single-day transactions): + +; in 2020.journal: +2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + liabilities:pending + +; in 2021.journal: +2021/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:bank:checking + + +File: hledger.info, Node: Example close revenue/expense accounts to retained earnings, Prev: close and balance assertions, Up: close + +11.10.6 Example: close revenue/expense accounts to retained earnings +-------------------------------------------------------------------- + +For this, use '--close' to suppress the opening transaction, as it's not +needed. Also you'll want to change the equity account name to your +equivalent of "equity:retained earnings". + + Closing 2021's first quarter revenues/expenses: + +$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ + --close-acct='equity:retained earnings' >> 2021.journal + + The same, using the default journal and current year: + +$ hledger close --close revenues expenses -p Q1 \ + --close-acct='equity:retained earnings' >> $LEDGER_FILE + + Now, the first quarter's balance sheet should show a zero (unless you +are using @/@@ notation without equity postings): + +$ hledger bse -p Q1 + + And we must suppress the closing transaction to see the first +quarter's income statement (using the description; 'not:'retained +earnings'' won't work here): + +$ hledger is -p Q1 not:desc:'closing balances' + + +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS + +11.11 codes +=========== + +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: + +1/1 (123) + (a) 1 + +1/1 () + (a) 1 + +1/1 + (a) 1 + +1/1 (126) + (a) 1 + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + + +126 + + +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS + +11.12 commodities +================= + +commodities +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS + +11.13 descriptions +================== + +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: COMMANDS + +11.14 diff +========== + +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: COMMANDS + +11.15 files +=========== + +files +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + + +File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS + +11.16 help +========== + +help +Show the hledger user manual in one of several formats, optionally +positioned at a given TOPIC (if possible). + + TOPIC is any heading in the manual, or the start of any heading (but +not the middle). It is case insensitive. + + Some examples: 'commands', 'print', 'forecast', '"auto postings"', +'"commodity column"'. + + This command shows the user manual built in to this hledger version. +It can be useful if the correct version of the hledger manual, or the +usual viewing tools, are not installed on your system. + + By default it uses the best viewer it can find in $PATH, in this +order: 'info', 'man', $PAGER (unless a topic is specified), 'less', or +stdout. When run non-interactively, it always uses stdout. Or you can +select a particular viewer with the '-i' (info), '-m' (man), or '-p' +(pager) flags. + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS + +11.17 import +============ + +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 + +11.17.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 + +11.17.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' + + +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import + +11.17.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 + +11.17.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: COMMANDS + +11.18 incomestatement +===================== + +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: COMMANDS + +11.19 notes +=========== + +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: COMMANDS + +11.20 payees +============ + +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: COMMANDS + +11.21 prices +============ + +prices +Print market price directives from the journal. With +-infer-market-prices, generate additional market prices from transaction +prices. With -infer-reverse-prices, also generate market prices by +inverting transaction prices. Prices (and postings providing +transaction prices) can be filtered by a query. Price amounts are +displayed with their full precision. + + +File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS + +11.22 print +=========== + +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 transaction price is +implied but not written, it will not appear in the output. You can use +the '-x'/'--explicit' flag to make all amounts and transaction prices +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 transaction prices are converted to +cost using that price. This can be used for troubleshooting. + + With '-m'/'--match' and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there +is no similar-enough match, no transaction will be shown. + + With '--new', 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: print-unique, Next: register, Prev: print, Up: COMMANDS + +11.23 print-unique +================== + +print-unique +Print transactions which do not reuse an already-seen description. + + Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 + + +File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS + +11.24 register +============== + +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. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +11.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: register-match, Next: rewrite, Prev: register, Up: COMMANDS + +11.25 register-match +==================== + +register-match +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. If there are multiple equally +good matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS + +11.26 rewrite +============= + +rewrite +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +$ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +11.26.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 + +11.26.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 + +11.26.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: COMMANDS + +11.27 roi +========= + +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 + +11.27.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 + +11.27.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 + +11.27.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: COMMANDS + +11.28 stats +=========== + +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 also supports output destination and output format +selection. + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS + +11.29 tags +========== + +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, Next: About add-on commands, Prev: tags, Up: COMMANDS + +11.30 test +========== + +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: About add-on commands, Prev: test, Up: COMMANDS + +11.31 About add-on commands +=========================== + +Add-on commands are 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. + + Add-ons are a relatively easy way to add local features or experiment +with new ideas. They can be written in any language, but haskell +scripts have a big advantage: they can use the same hledger library +functions that built-in commands use for command-line options, parsing +and reporting. Some experimental/example add-on scripts can be found in +the hledger repo's bin/ directory. + + 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: JOURNAL FORMAT, Next: CSV FORMAT, Prev: COMMANDS, Up: Top + +12 JOURNAL FORMAT +***************** + +hledger's default file format, representing a General Journal. + + 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). These are mostly in the order you'll use them, but in some +cases related concepts have been grouped together for easy reference, or +linked before they are introduced, so feel free to skip over anything +that looks unnecessary right now. + +* Menu: + +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Comments:: +* Tags:: +* Postings:: +* Account names:: +* Amounts:: +* Transaction prices:: +* Lot prices lot dates:: +* Balance assertions:: +* Balance assignments:: +* Directives:: +* Directives and multiple files:: +* Comment blocks:: +* Including other files:: +* Default year:: +* Declaring payees:: +* Declaring the decimal mark:: +* Declaring commodities:: +* Default commodity:: +* Declaring market prices:: +* Declaring accounts:: +* Rewriting accounts:: +* Default parent account:: +* Periodic transactions:: +* Auto postings:: + + +File: hledger.info, Node: Transactions, Next: Dates, Up: JOURNAL FORMAT + +12.1 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 FORMAT + +12.2 Dates +========== + +* Menu: + +* Simple dates:: +* Secondary dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Secondary dates, Up: Dates + +12.2.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 default year 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: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates + +12.2.2 Secondary dates +---------------------- + +Real-life transactions sometimes involve more than one date - eg the +date you write a cheque, and the date it clears in your bank. When you +want to model this, for more accurate daily balances, you can specify +individual posting dates. + + Or, you can use the older _secondary date_ feature (Ledger calls it +auxiliary date or effective date). Note: we support this for +compatibility, but I usually recommend avoiding this feature; posting +dates are almost always clearer and simpler. + + 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", as shown here: + +2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + +$ hledger register checking +2010-02-23 movie ticket assets:checking $-10 $-10 + +$ hledger register checking --date2 +2010-02-19 movie ticket assets:checking $-10 $-10 + + +File: hledger.info, Node: Posting dates, Prev: Secondary dates, Up: Dates + +12.2.3 Posting dates +-------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like 'date:DATE'. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction's date. You can set the secondary date +similarly, with 'date2:DATE2'. The 'date:' or 'date2:' tags must have a +valid simple date value if they are present, eg a 'date:' tag with no +value is not allowed. + + Ledger's earlier, more compact bracketed date syntax is also +supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'. hledger will attempt +to parse any square-bracketed sequence of the '0123456789/-.=' +characters in this way. With this syntax, DATE infers its year from the +transaction and DATE2 infers its year from DATE. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: JOURNAL FORMAT + +12.3 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 FORMAT + +12.4 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: Comments, Prev: Code, Up: JOURNAL FORMAT + +12.5 Description +================ + +A transaction's description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +12.5.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: Comments, Next: Tags, Prev: Description, Up: JOURNAL FORMAT + +12.6 Comments +============= + +Lines in the journal beginning with a semicolon (';') or hash ('#') or +star ('*') are comments, and will be ignored. (Star comments cause +org-mode nodes to be ignored, allowing emacs users to fold and navigate +their journals with org-mode or orgstruct-mode.) + + You can attach comments to a transaction by writing them after the +description and/or indented on the following lines (before the +postings). Similarly, you can attach comments to an individual posting +by writing them after the amount and/or indented on the following lines. +Transaction and posting comments must begin with a semicolon (';'). + + Some examples: + +# a file comment +; another file comment +* also a file comment, useful in org/orgstruct mode + +comment +A multiline file comment, which continues +until a line containing just "end comment" +(or end of file). +end comment + +2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 +; a file comment (because not indented) + + You can also comment larger regions of a file using 'comment' and +'end comment' directives. + + +File: hledger.info, Node: Tags, Next: Postings, Prev: Comments, Up: JOURNAL FORMAT + +12.7 Tags +========= + +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: + +2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the +next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or +newlines. Ending at commas means you can write multiple short tags on +one line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + * "'a comment containing'" is just comment text, not a tag + * "'tag1'" is a tag with no value + * "'tag2'" is another tag, whose value is "'some value ...'" + + Tags in a transaction comment affect the transaction and all of its +postings, while tags in a posting comment affect only that posting. For +example, the following transaction has three tags ('A', 'TAG2', +'third-tag') and the posting has four (those plus 'posting-tag'): + +1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values +are simple strings. + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Tags, Up: JOURNAL FORMAT + +12.8 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. + +* Menu: + +* Virtual postings:: + + +File: hledger.info, Node: Virtual postings, Up: Postings + +12.8.1 Virtual postings +----------------------- + +A posting with a parenthesised 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 accounting, 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: + +1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with a bracketed 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: + +1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance + + Ordinary non-parenthesised, non-bracketed postings are called _real +postings_. You can exclude virtual postings from reports with the +'-R/--real' flag or 'real:1' query. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: JOURNAL FORMAT + +12.9 Account names +================== + +Account names typically have several parts separated by a full colon, +from which hledger derives a hierarchical chart of accounts. They can +be anything you like, but in finance there are traditionally five +top-level accounts: 'assets', 'liabilities', 'revenue', 'expenses', and +'equity'. + + Account names may contain single spaces, eg: 'assets:accounts +receivable'. Because of this, they must always be followed by *two or +more spaces* (or newline). + + Account names can be aliased. + + +File: hledger.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: JOURNAL FORMAT + +12.10 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 + +12.10.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 detail below. + + +File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts + +12.10.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 + +12.10.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, in JOURNAL FORMAT -> Declaring commodities. 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 + +12.10.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. + + Transaction price 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 transaction price). 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 + +12.10.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"). (Guaranteed since hledger 1.17.1; in older versions +this could vary if hledger was built with Decimal < 0.5.1.) + + +File: hledger.info, Node: Transaction prices, Next: Lot prices lot dates, Prev: Amounts, Up: JOURNAL FORMAT + +12.11 Transaction prices +======================== + +Within a transaction, you can note an amount's price in another +commodity. This can be used to document the cost (in a purchase) or +selling price (in a sale). For example, transaction prices are useful +to record purchases of a foreign currency. Note transaction prices are +fixed at the time of the transaction, and do not change over time. See +also market prices, which represent prevailing exchange rates on a +certain date. + + There are several ways to record a transaction price: + + 1. Write the price per unit, as '@ UNITPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as '@@ TOTALPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + 4. Like 1, but the '@' is parenthesised, i.e. '(@)'; this is for + compatibility with Ledger journals (Virtual posting costs), and is + equivalent to 1 in hledger. + + 5. Like 2, but as in 4 the '@@' is parenthesised, i.e. '(@@)'; in + hledger, this is equivalent to 2. + + Use the '-B/--cost' flag to convert amounts to their transaction +price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in +Ledger). Eg here is how -B affects the balance report for the example +above: + +$ hledger bal -N --flat + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction +price is inferred: the inferred price will be in the commodity of the +last amount. So if example 3's postings are reversed, while the +transaction is equivalent, -B shows something different: + +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N --flat -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros + + +File: hledger.info, Node: Lot prices lot dates, Next: Balance assertions, Prev: Transaction prices, Up: JOURNAL FORMAT + +12.12 Lot prices, lot dates +=========================== + +Ledger allows another kind of price, lot price (four variants: +'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}', +'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified. +These are normally used to select a lot when selling investments. +hledger will parse these, for compatibility with Ledger journals, but +currently ignores them. A transaction price, lot price and/or lot date +may appear in any order, after the posting amount and before the balance +assertion if any. + + +File: hledger.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices lot dates, Up: JOURNAL FORMAT + +12.13 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, 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 + +12.13.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 + +12.13.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 + +12.13.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 + +12.13.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 + +12.13.5 Assertions and prices +----------------------------- + +Balance assertions ignore transaction prices, and should normally be +written without one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below). + + +File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions + +12.13.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 + +12.13.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 + +12.13.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 + +12.13.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: Balance assignments, Next: Directives, Prev: Balance assertions, Up: JOURNAL FORMAT + +12.14 Balance assignments +========================= + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). Note that using balance assignments makes your journal a +little less explicit; to know the exact amount posted, you have to run +hledger or do the calculations yourself, instead of just reading it. + +* Menu: + +* Balance assignments and prices:: + + +File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments + +12.14.1 Balance assignments and prices +-------------------------------------- + +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019-01-01 + (a) $1 @ €2 = $1 @ €2 + + +File: hledger.info, Node: Directives, Next: Directives and multiple files, Prev: Balance assignments, Up: JOURNAL FORMAT + +12.15 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 add some as your needs grow. Here is an overview of +directives by purpose: + +purpose directives command line + options with + similar effect +--------------------------------------------------------------------------- +*READING/GENERATING DATA:* +Declare a commodity's or 'commodity', 'D', +file's decimal mark to help 'decimal-mark' +parse amounts accurately +Apply changes to the data 'alias', 'apply '--alias' +while parsing account', 'comment', + 'D', 'Y' +Inline extra data files 'include' multiple + '-f/--file''s +Generate extra transactions or '~' +budget goals +Generate extra postings '=' +*CHECKING FOR ERRORS:* +Define valid entities to allow 'account', +stricter error checking 'commodity', 'payee' +*DISPLAYING REPORTS:* +Declare accounts' display 'account' +order and accounting type +Declare commodity display 'commodity', 'D' '-c/--commodity-style' +styles + + And here are all the directives and their precise effects: + +directiveeffects ends + at + file + end? +--------------------------------------------------------------------------- +*'account'*Declares an account, for checking all entries in all files; + and its display order and type, for reports. Subdirectives: + any text, ignored. +*'alias'*Rewrites account names, in following entries until end of Y + current file or 'end aliases'. +*'applyPrepends a common parent account to all account names, in Y +account'*following entries until end of current file or 'end apply + account'. +*'comment'*Ignores part of the journal file, until end of current fileY + or 'end comment'. +*'commodity'*Declares a commodity, for checking all entries in all files;N, + the decimal mark for parsing amounts of this commodity, for Y + following entries until end of current file; and its display + style, for reports. Takes precedence over 'D'. + Subdirectives: 'format' (alternate syntax). +*'D'* Sets a default commodity to use for no-symbol amounts, and Y + its decimal mark for parsing amounts of this commodity in + following entries until end of current file; and its display + style, for reports. +*'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 they + were written inline. +*'payee'*Declares a payee name, for checking all entries in all files. +*'P'* Declares a market price for a commodity on some date, for + valuation reports. +*'Y'* Declares a year for yearless dates, for following entries Y + until end of current file. +*'~'* Declares a periodic transaction rule that generates future +(tilde)transactions with '--forecast' and budget goals with 'balance + --budget'. +*'='* Declares an auto posting rule that generates extra postings partly +(equals)on matched transactions with '--auto', in current, parent, + and child files (but not sibling files, see #1212). + + +File: hledger.info, Node: Directives and multiple files, Next: Comment blocks, Prev: Directives, Up: JOURNAL FORMAT + +12.16 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: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: JOURNAL FORMAT + +12.17 Comment blocks +==================== + +A line containing just 'comment' starts a commented region of the file, +and a line containing just 'end comment' (or the end of the current +file) ends it. See also comments. + + +File: hledger.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: JOURNAL FORMAT + +12.18 Including other files +=========================== + +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: Default year, Next: Declaring payees, Prev: Including other files, Up: JOURNAL FORMAT + +12.19 Default year +================== + +You can set a default year to be used for subsequent dates which don't +specify a year. This is a line beginning with 'Y' followed by the year. +Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +Y2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + +File: hledger.info, Node: Declaring payees, Next: Declaring the decimal mark, Prev: Default year, Up: JOURNAL FORMAT + +12.20 Declaring payees +====================== + +The 'payee' 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 + + +File: hledger.info, Node: Declaring the decimal mark, Next: Declaring commodities, Prev: Declaring payees, Up: JOURNAL FORMAT + +12.21 Declaring the decimal mark +================================ + +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: Declaring commodities, Next: Default commodity, Prev: Declaring the decimal mark, Up: JOURNAL FORMAT + +12.22 Declaring commodities +=========================== + +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 + + 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: Declaring commodities + +12.22.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: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: JOURNAL FORMAT + +12.23 Default commodity +======================= + +The 'D' 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). + + The syntax is 'D AMOUNT'. As with 'commodity', 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 + + If both 'commodity' and 'D' directives are found for a commodity, +'commodity' takes precedence for setting decimal mark and display style. + + If you are using 'D' and also checking commodities, you will need to +add a 'commodity' directive similar to the 'D'. (The 'hledger check +commodities' command expects 'commodity' directives, and ignores 'D'). + + +File: hledger.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: JOURNAL FORMAT + +12.24 Declaring market prices +============================= + +The 'P' directive declares a market price, which is an exchange rate +between two commodities on a certain date. (In Ledger, they are called +"historical prices".) These are often obtained from a stock exchange, +cryptocurrency exchange, or the 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: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: JOURNAL FORMAT + +12.25 Declaring accounts +======================== + +'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. + * They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + * They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and + incomestatement. + * They can store other account information, as comments or as tags + which can be used to filter reports. + * They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + * In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + + The simplest form is just the word 'account' followed by a +hledger-style account name, eg this account directive declares the +'assets:bank:checking' account: + +account assets:bank:checking + +* Menu: + +* Account error checking:: +* Account comments:: +* Account subdirectives:: +* Account types:: +* Account display order:: + + +File: hledger.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts + +12.25.1 Account error checking +------------------------------ + +By default, accounts come into existence when a transaction references +them by name. 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 +the 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 in other formats). + * 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 comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts + +12.25.2 Account comments +------------------------ + +Comments, beginning with a semicolon, can be added: + + * on the same line, *after two or more spaces* (because ; is allowed + in account names) + * on the next lines, indented + + An example of both: + +account assets:bank:checking ; same-line comment, note 2+ spaces required before ; + ; next-line comment + ; some tags, type:A, acctnum:12345 + + Compatibility note: same-line comments are not supported by Ledger or +hledger <1.13. + + +File: hledger.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts + +12.25.3 Account subdirectives +----------------------------- + +We also allow (and ignore) Ledger-style indented subdirectives, just for +compatibility.: + +account assets:bank:checking + format blah blah ; <- subdirective, ignored + + Here is the full syntax of account directives: + +account ACCTNAME [;type:ACCTTYPE] [COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] + + +File: hledger.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts + +12.25.4 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 + CONVERSION & COST).) + + 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. Note the Cash + regexp changed in hledger 1.24.99.2. + + 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 each of them, 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: Account display order, Prev: Account types, Up: Declaring accounts + +12.25.5 Account display order +----------------------------- + +Account directives also set the order in which accounts are displayed, +eg in reports, the hledger-ui accounts screen, and the hledger-web +sidebar. By default accounts are listed in alphabetical order. But if +you have these account directives in the journal: + +account assets +account liabilities +account equity +account revenues +account expenses + + you'll see those accounts displayed in declaration order, not +alphabetically: + +$ hledger accounts -1 +assets +liabilities +equity +revenues +expenses + + Undeclared accounts, if any, are displayed last, in alphabetical +order. + + Note that sorting is done at each level of the account tree (within +each group of sibling accounts under the same parent). And currently, +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: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: JOURNAL FORMAT + +12.26 Rewriting accounts +======================== + +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:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts + +12.26.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: Rewriting accounts + +12.26.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: Rewriting accounts + +12.26.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, Prev: Combining aliases, Up: Rewriting accounts + +12.26.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, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: Rewriting accounts + +12.26.5 'end aliases' +--------------------- + +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, Up: Rewriting accounts + +12.26.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: Rewriting accounts + +12.26.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: Default parent account, Next: Periodic transactions, Prev: Rewriting accounts, Up: JOURNAL FORMAT + +12.27 Default parent account +============================ + +You can specify a parent account which will be prepended to all accounts +within a section of the journal. Use the 'apply account' and 'end apply +account' directives like so: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + which is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + If 'end apply account' is omitted, the effect lasts to the end of the +file. Included files are also affected, eg: + +apply account business +include biz.journal +end apply account +apply account personal +include personal.journal + + Prior to hledger 1.0, legacy 'account' and 'end' spellings were also +supported. + + A default parent account also affects account directives. It does +not affect account names being entered via hledger add or hledger-web. +If account aliases are present, they are applied after the default +parent account. + + +File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: Default parent account, Up: JOURNAL FORMAT + +12.28 Periodic transactions +=========================== + +Periodic transaction rules describe transactions that recur. They allow +hledger to generate temporary future transactions to help with +forecasting, so you don't have to write out each one in the journal, and +it's easy to try out different forecasts. + + 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. + + Periodic transaction rules also have a second meaning: they are used +to define budget goals, shown in budget reports. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: +* Forecasting with periodic transactions:: +* Budgeting with periodic transactions:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +12.28.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.): + +~ monthly + expenses:rent $2000 + assets:bank:checking + + There is an additional constraint on the period expression: the start +date must fall on a natural boundary of the interval. Eg 'monthly from +2018/1/1' is valid, but 'monthly from 2018/1/15' is not. + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +12.28.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!, Next: Forecasting with periodic transactions, Prev: Periodic rules and relative dates, Up: Periodic transactions + +12.28.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: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions + +12.28.4 Forecasting with periodic transactions +---------------------------------------------- + +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 with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions + +12.28.5 Budgeting with periodic transactions +-------------------------------------------- + +With the '--budget' flag, currently supported by the balance command, +each periodic transaction rule declares recurring budget goals for the +specified accounts. Eg the first example above declares a goal of +spending $2000 on rent (and also, a goal of depositing $2000 into +checking) every month. Goals and actual performance can then be +compared in budget reports. + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Auto postings, Prev: Periodic transactions, Up: JOURNAL FORMAT + +12.29 Auto postings +=================== + +"Automated postings" or "auto postings" are extra postings which get +added automatically to transactions which match certain queries, defined +by "auto posting rules", when you use the '--auto' flag. + + 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 + +12.29.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 + +12.29.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 + +12.29.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 + +12.29.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: CSV FORMAT, Next: TIMECLOCK FORMAT, Prev: JOURNAL FORMAT, Up: Top + +13 CSV FORMAT +************* + +How hledger reads CSV data, and the CSV rules file format. + + hledger can read CSV files (Character Separated Value - usually +comma, semicolon, or tab) containing dated records as if they were +journal files, automatically converting each CSV record into a +transaction. + + (To learn about _writing_ CSV, see CSV output.) + + We describe each CSV file's format with a corresponding _rules file_. +By default this is named like the CSV file with a '.rules' extension +added. Eg when reading 'FILE.csv', hledger also looks for +'FILE.csv.rules' in the same directory as 'FILE.csv'. You can specify a +different rules file with the '--rules-file' option. If a rules file is +not found, hledger will create a sample rules file, which you'll need to +adjust. + + This file contains rules describing the CSV data (header line, fields +layout, date format etc.), and how to construct hledger journal entries +(transactions) from it. Often there will also be a list of conditional +rules for categorising transactions based on their descriptions. Here's +an overview of the CSV rules; these are described more fully below, +after the examples: + +*'skip'* skip one or more header lines or matched + CSV records +*'fields' list* name CSV fields, assign them to hledger + fields +*field assignment* assign a value to one hledger field, with + interpolation +*Field names* hledger field names, used in the fields + list and field assignments +*'separator'* a custom field separator +*'if' block* apply some rules to CSV records matched by + patterns +*'if' table* apply some rules to CSV records matched by + patterns, alternate syntax +*'end'* skip the remaining CSV records +*'date-format'* how to parse dates in CSV records +*'decimal-mark'* the decimal mark used in CSV amounts, if + ambiguous +*'newest-first'* disambiguate record order when there's only + one date +*'include'* inline another CSV rules file +*'balance-type'* choose which type of balance assignments to + use + + Note, for best error messages when reading CSV files, use a '.csv', +'.tsv' or '.ssv' file extension or file prefix - see File Extension +below. + + There's an introductory Convert CSV files tutorial on hledger.org. + +* Menu: + +* Examples:: +* CSV rules:: +* Tips:: + + +File: hledger.info, Node: Examples, Next: CSV rules, Up: CSV FORMAT + +13.1 Examples +============= + +Here are some sample hledger CSV rules files. See also the full +collection at: +https://github.com/simonmichael/hledger/tree/master/examples/csv + +* Menu: + +* Basic:: +* Bank of Ireland:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Basic, Next: Bank of Ireland, Up: Examples + +13.1.1 Basic +------------ + +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 + + Default account names are chosen, since we didn't set them. + + +File: hledger.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: Examples + +13.1.2 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: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: Examples + +13.1.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: Examples + +13.1.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: CSV rules, Next: Tips, Prev: Examples, Up: CSV FORMAT + +13.2 CSV rules +============== + +The following kinds of rule can appear in the rules file, in any order. +Blank lines and lines beginning with '#' or ';' are ignored. + +* Menu: + +* skip:: +* fields list:: +* field assignment:: +* Field names:: +* separator:: +* if block:: +* if table:: +* end:: +* date-format:: +* decimal-mark:: +* newest-first:: +* include:: +* balance-type:: + + +File: hledger.info, Node: skip, Next: fields list, Up: CSV rules + +13.2.1 'skip' +------------- + +skip N + + The word "skip" followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines preceding the CSV data. +(Empty/blank lines are skipped automatically.) You'll need this +whenever your CSV data contains header lines. + + It also has a second purpose: it can be used inside if blocks to +ignore certain CSV records (described below). + + +File: hledger.info, Node: fields list, Next: field assignment, Prev: skip, Up: CSV rules + +13.2.2 'fields' list +-------------------- + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word "fields" followed by comma-separated field +names) is the quick way to assign CSV field values to hledger fields. +(The other way is field assignments, see below.) A fields list does +does two things: + + 1. It names the CSV fields. This is optional, but can be convenient + later for interpolating them. + + 2. Whenever you use a standard hledger field name (defined below), the + CSV value is assigned to that part of the hledger 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 + + Tips: + + * The fields list always use commas, even if your CSV data uses + another separator character. + * Currently 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). + * If the CSV contains column headings, it's a good idea to use these, + suitably modified, as the basis for your field names (eg + lower-cased, with underscores instead of spaces). + * If some heading names match standard hledger fields, but you don't + want to set the hledger fields directly, alter those names, eg by + appending an underscore. + * Fields you don't care about can be given a dummy name (eg: '_' ), + or no name. + + +File: hledger.info, Node: field assignment, Next: Field names, Prev: fields list, Up: CSV rules + +13.2.3 field assignment +----------------------- + +HLEDGERFIELDNAME 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 +('%CSVFIELDNAME'). + + 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: separator, Prev: field assignment, Up: CSV rules + +13.2.4 Field names +------------------ + +Here are the standard hledger field (and pseudo-field) names, which you +can use in a fields list and in field assignments. For more about the +transaction parts they refer to, see Transactions. + +* 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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.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 + +13.2.4.6 comment field +...................... + +'comment' sets the transaction's comment, if any. + + 'commentN', where N is a number, sets the Nth posting's comment. + + Tips: + + * 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 + +13.2.4.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, and in conditional blocks. + + 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 + +13.2.4.8 amount field +..................... + +'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. + + 'amountN-in' and 'amountN-out' can be used instead, if the CSV uses +separate fields for debits and credits (inflows and outflows). hledger +assumes both of these CSV fields are unsigned, and will automatically +negate the "-out" value. If they are signed, see "Setting amounts" +below. + + 'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep +pre-hledger-1.17 CSV rules files working (and for occasional +convenience). They are suitable only for two-posting transactions; they +set both posting 1's and posting 2's amount. Posting 2's amount will be +negated, and also converted to cost if there's a transaction price. + + If you have an existing rules file using the unnumbered form, you +might want to use the numbered form in certain conditional blocks, +without having to update and retest all the old rules. To facilitate +this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of +'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores +them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned, +avoiding conflicts. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +13.2.4.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 + +13.2.4.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: separator, Next: if block, Prev: Field names, Up: CSV rules + +13.2.5 '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: if block, Next: if table, Prev: separator, Up: CSV rules + +13.2.6 'if' block +----------------- + +if MATCHER + RULE + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + Conditional blocks ("if blocks") are a block of rules that are +applied only to CSV records which match certain patterns. They are +often used for customising account names based on transaction +descriptions. + +* Menu: + +* Matching the whole record:: +* Matching individual fields:: +* Combining matchers:: +* Rules applied on successful match:: + + +File: hledger.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block + +13.2.6.1 Matching the whole record +.................................. + +Each MATCHER can be a record matcher, which looks like this: + +REGEX + + REGEX is a case-insensitive regular expression that tries to match +anywhere within the CSV record. It is a POSIX ERE (extended regular +expression) that also supports GNU word boundaries ('\b', '\B', '\<', +'\>'), and nothing else. If you have trouble, be sure to check our doc: +https://hledger.org/hledger.html#regular-expressions + + Important note: the record that is matched is not the original +record, but a synthetic one, with any enclosing double quotes (but not +enclosing whitespace) removed, and always comma-separated (which means +that a field containing a comma will appear like two fields). Eg, if +the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will +actually see '2020-01-01,Acme, Inc., 1,000'). + + +File: hledger.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block + +13.2.6.2 Matching individual fields +................................... + +Or, MATCHER can be a field matcher, like this: + +%CSVFIELD REGEX + + which matches just the content of a particular CSV field. CSVFIELD +is a percent sign followed by the field's name or column number, like +'%date' or '%1'. + + +File: hledger.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block + +13.2.6.3 Combining matchers +........................... + +A single matcher can be written on the same line as the "if"; or +multiple matchers can be written on the following lines, non-indented. +Multiple matchers are OR'd (any one of them can match), unless one +begins with an '&' symbol, in which case it is AND'ed with the previous +matcher. + +if +MATCHER +& MATCHER + RULE + + +File: hledger.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block + +13.2.6.4 Rules applied on successful match +.......................................... + +After the patterns there should be one or more rules to apply, all +indented by at least one space. Three kinds of rule are allowed in +conditional blocks: + + * field assignments (to set a hledger field) + * skip (to skip the matched CSV record) + * end (to skip all remaining CSV records). + + Examples: + +# if the CSV record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the CSV record contains any of these patterns, set account2 and comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + +File: hledger.info, Node: if table, Next: end, Prev: if block, Up: CSV rules + +13.2.7 'if' table +----------------- + +if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn +MATCHER1,VALUE11,VALUE12,...,VALUE1n +MATCHER2,VALUE21,VALUE22,...,VALUE2n +MATCHER3,VALUE31,VALUE32,...,VALUE3n + + + Conditional tables ("if tables") are a different syntax to specify +field assignments that will be applied only to CSV records which match +certain patterns. + + MATCHER could be either field or record matcher, as described above. +When MATCHER matches, values from that row would be assigned to the CSV +fields named on the 'if' line, in the same order. + + Therefore 'if' table is exactly equivalent to a sequence of of 'if' +blocks: + +if MATCHER1 + CSVFIELDNAME1 VALUE11 + CSVFIELDNAME2 VALUE12 + ... + CSVFIELDNAMEn VALUE1n + +if MATCHER2 + CSVFIELDNAME1 VALUE21 + CSVFIELDNAME2 VALUE22 + ... + CSVFIELDNAMEn VALUE2n + +if MATCHER3 + CSVFIELDNAME1 VALUE31 + CSVFIELDNAME2 VALUE32 + ... + CSVFIELDNAMEn VALUE3n + + Each line starting with MATCHER should contain enough (possibly +empty) values for all the listed fields. + + Rules would be checked and applied in the order they are listed in +the table and, like with 'if' blocks, later rules (in the same or +another table) or 'if' blocks could override the effect of any rule. + + Instead of ',' you can use a variety of other non-alphanumeric +characters as a separator. First character after 'if' is taken to be +the separator for the rest of the table. It is the responsibility of +the user to ensure that separator does not occur inside MATCHERs and +values - there is no way to escape separator. + + 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: end, Next: date-format, Prev: if table, Up: CSV rules + +13.2.8 'end' +------------ + +This rule can be used inside if blocks (only), to make hledger stop +reading this CSV file and move on to the next input file, or to command +execution. Eg: + +# ignore everything following the first empty record +if ,,,, + end + + +File: hledger.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV rules + +13.2.9 '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 +date parsing pattern, which 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 + + For the supported strptime syntax, see: +https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime + + Note that although you can parse date-times which include a time +zone, that time zone is ignored; it will not change the date that is +parsed. This means when reading CSV data with times not in your local +time zone, dates can be "off by one". + + +File: hledger.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV rules + +13.2.10 '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: newest-first, Next: include, Prev: decimal-mark, Up: CSV rules + +13.2.11 'newest-first' +---------------------- + +hledger always sorts the generated transactions by date. Transactions +on the same date should appear in the same order as their CSV records, +as hledger can usually auto-detect whether the CSV's normal order is +oldest first or newest first. But if all of the following are true: + + * the CSV might sometimes contain just one day of data (all records + having the same date) + * the CSV records are normally in reverse chronological order (newest + at the top) + * and you care about preserving the order of same-day transactions + + then, you should add the 'newest-first' rule as a hint. Eg: + +# tell hledger explicitly that the CSV is normally newest first +newest-first + + +File: hledger.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV rules + +13.2.12 '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: balance-type, Prev: include, Up: CSV rules + +13.2.13 '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: Tips, Prev: CSV rules, Up: CSV FORMAT + +13.3 Tips +========= + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* 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:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Tips + +13.3.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: Tips + +13.3.2 Valid CSV +---------------- + +hledger accepts CSV conforming to RFC 4180. When CSV values are +enclosed in quotes, note: + + * they must be double quotes (not single quotes) + * spaces outside the quotes are not allowed + + +File: hledger.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: Tips + +13.3.3 File Extension +--------------------- + +To help hledger identify the format and show the right error messages, +CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or +'.tsv' filename extension. Or, the file path should be prefixed with +'csv:', 'ssv:' or 'tsv:'. Eg: + +$ hledger -f foo.ssv print + + or: + +$ cat foo | hledger -f ssv:- foo + + You can override the file extension with a separator rule if needed. +See also: Input files in the hledger manual. + + +File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: Tips + +13.3.4 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: Tips + +13.3.5 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: Tips + +13.3.6 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: Tips + +13.3.7 Setting amounts +---------------------- + +Some tips on using the amount-setting rules discussed above. + + Here are the ways to set a posting's amount: + + 1. *If the CSV has a single amount field:* + Assign (via a fields list or a field assignment) to 'amountN'. + This sets the Nth posting's amount. N is usually 1 or 2 but can go + up to 99. + + 2. *If the CSV has separate amount fields for debit & credit (in & + out):* + + a. *If both fields are unsigned:* + Assign to 'amountN-in' and 'amountN-out'. This sets posting + N's amount to whichever of these has a non-zero value, and + negates the "-out" value. + + b. *If either field is signed (can contain a minus sign):* + Use a conditional rule to flip the sign (of non-empty values). + Since hledger always negates amountN-out, if it was already + negative, we must undo that by negating once more (but only if + the field is non-empty): + + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields, or neither field, can contain a non-zero + value:* + hledger normally expects exactly one of the fields to have a + non-zero value. Eg, the 'amountN-in'/'amountN-out' rules + would reject value pairs like these: + + "", "" + "0", "0" + "1", "none" + + So, use smarter conditional rules to set the amount from the + appropriate field. Eg, these rules would make it use only the + value containing non-zero digits, handling the above: + + 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:* + Assign to 'amount' (or to 'amount-in' and 'amount-out'). (This is + the legacy numberless syntax, which sets amount1 and amount2 and + converts amount2 to cost.) + + 4. *If the CSV has the balance instead of the transaction amount:* + Assign to 'balanceN', which sets posting N's amount indirectly via + a balance assignment. (Old syntax: 'balance', equivalent to + 'balance1'.) + + * *If hledger guesses the wrong default account name:* + When setting the amount via balance assertion, hledger may + guess the wrong default account name. So, set the account + name explicitly, eg: + + fields date, description, balance1 + account1 assets:checking + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Tips + +13.3.8 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: Tips + +13.3.9 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: Tips + +13.3.10 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: Tips + +13.3.11 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, Prev: Referencing other fields, Up: Tips + +13.3.12 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 %CSVFIELDNAME references), or a + default + * generate a synthetic hledger transaction 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: TIMECLOCK FORMAT, Next: TIMEDOT FORMAT, Prev: CSV FORMAT, Up: Top + +14 TIMECLOCK FORMAT +******************* + +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). + +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 FORMAT, Next: COMMON TASKS, Prev: TIMECLOCK FORMAT, Up: Top + +15 TIMEDOT FORMAT +***************** + +'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.: + + * Lines beginning with '#' or ';', and blank lines, are ignored. + + * 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.) + + * One or more stars ('*') followed by a space, at the start of a + line, is ignored. So date lines or time transaction lines can also + be Org-mode headlines. + + * All Org-mode headlines before the first date line are ignored. + + 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: COMMON TASKS, Next: LIMITATIONS, Prev: TIMEDOT FORMAT, Up: Top + +16 COMMON TASKS +*************** + +Here are some quick examples of how to do some basic tasks with hledger. +For more details, see the reference section below, the +hledger_journal(5) manual, or the more extensive docs at +https://hledger.org. + +* 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: COMMON TASKS + +16.1 Getting help +================= + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show common and command options, and command help +$ hledger help # show available manuals/topics +$ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) +$ hledger help journal -m # show the journal topic, as a man page scrolled to that section +$ hledger help --help # show more detailed help for the help command + + Find more docs, chat, mail list, reddit, issue tracker: +https://hledger.org/support.html-feedback + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS + +16.2 Constructing command lines +=============================== + +hledger has an extensive and powerful command line interface. We strive +to keep it simple and ergonomic, but you may run into one of the +confusing real world details described in OPTIONS, below. If that +happens, here are some tips that may help: + + * command-specific options must go after the command (it's fine to + put all options there) ('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 is being parsed, add '--debug=2'. + + +File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS + +16.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: COMMON TASKS + +16.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: COMMON TASKS + +16.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: COMMON TASKS + +16.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: COMMON TASKS + +16.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 --flat -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 --flat -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: COMMON TASKS + +16.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. + + +File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: COMMON TASKS, Up: Top + +17 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 file +format differences. + + On large data files, hledger is slower and uses more memory than +Ledger. + + +File: hledger.info, Node: TROUBLESHOOTING, Prev: LIMITATIONS, Up: Top + +18 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 + + +Tag Table: +Node: Top208 +Node: OPTIONS2614 +Ref: #options2715 +Node: General options2857 +Ref: #general-options2982 +Node: Command options7195 +Ref: #command-options7346 +Node: Command arguments7746 +Ref: #command-arguments7904 +Node: Special characters8784 +Ref: #special-characters8947 +Node: Single escaping shell metacharacters9110 +Ref: #single-escaping-shell-metacharacters9351 +Node: Double escaping regular expression metacharacters9954 +Ref: #double-escaping-regular-expression-metacharacters10265 +Node: Triple escaping for add-on commands10791 +Ref: #triple-escaping-for-add-on-commands11051 +Node: Less escaping11695 +Ref: #less-escaping11849 +Node: Unicode characters12173 +Ref: #unicode-characters12338 +Node: Regular expressions13750 +Ref: #regular-expressions13890 +Node: ENVIRONMENT15626 +Ref: #environment15742 +Node: DATA FILES17234 +Ref: #data-files17353 +Node: Data formats17892 +Ref: #data-formats18010 +Node: Multiple files19404 +Ref: #multiple-files19546 +Node: Strict mode20015 +Ref: #strict-mode20130 +Node: TIME PERIODS20854 +Ref: #time-periods20971 +Node: Smart dates21069 +Ref: #smart-dates21195 +Node: Report start & end date23025 +Ref: #report-start-end-date23200 +Node: Report intervals24867 +Ref: #report-intervals25035 +Node: Period expressions26774 +Ref: #period-expressions26914 +Node: Period expressions with a report interval28645 +Ref: #period-expressions-with-a-report-interval28877 +Node: More complex report intervals29958 +Ref: #more-complex-report-intervals30207 +Node: Intervals with custom start date30847 +Ref: #intervals-with-custom-start-date31079 +Node: Periods or dates ?32653 +Ref: #periods-or-dates32855 +Node: Events on multiple weekdays33297 +Ref: #events-on-multiple-weekdays33476 +Node: DEPTH34339 +Ref: #depth34439 +Node: QUERIES34773 +Ref: #queries34882 +Node: Query types35823 +Ref: #query-types35942 +Node: Combining query terms39116 +Ref: #combining-query-terms39291 +Node: Queries and command options40094 +Ref: #queries-and-command-options40297 +Node: Queries and account aliases40546 +Ref: #queries-and-account-aliases40749 +Node: Queries and valuation40869 +Ref: #queries-and-valuation41062 +Node: Querying with account aliases41291 +Ref: #querying-with-account-aliases41500 +Node: Querying with cost or value41630 +Ref: #querying-with-cost-or-value41805 +Node: CONVERSION & COST42106 +Ref: #conversion-cost42239 +Node: Recording conversions43128 +Ref: #recording-conversions43300 +Node: Implicit conversion43752 +Ref: #implicit-conversion43909 +Node: Priced conversion44728 +Ref: #priced-conversion44907 +Node: Equity conversion45315 +Ref: #equity-conversion45499 +Node: Priced equity conversion46287 +Ref: #priced-equity-conversion46459 +Node: Inferring missing conversion rates46807 +Ref: #inferring-missing-conversion-rates47047 +Node: Inferring missing equity postings47163 +Ref: #inferring-missing-equity-postings47394 +Node: Cost reporting47542 +Ref: #cost-reporting47719 +Node: Conversion summary48239 +Ref: #conversion-summary48382 +Node: VALUATION49104 +Ref: #valuation49222 +Node: -V Value49989 +Ref: #v-value50113 +Node: -X Value in specified commodity50308 +Ref: #x-value-in-specified-commodity50501 +Node: Valuation date50650 +Ref: #valuation-date50812 +Node: Market prices51249 +Ref: #market-prices51431 +Node: --infer-market-prices market prices from transactions52614 +Ref: #infer-market-prices-market-prices-from-transactions52881 +Node: Valuation commodity54765 +Ref: #valuation-commodity54976 +Node: Simple valuation examples56202 +Ref: #simple-valuation-examples56398 +Node: --value Flexible valuation57057 +Ref: #value-flexible-valuation57259 +Node: More valuation examples58903 +Ref: #more-valuation-examples59110 +Node: Interaction of valuation and queries61109 +Ref: #interaction-of-valuation-and-queries61348 +Node: Effect of valuation on reports61820 +Ref: #effect-of-valuation-on-reports62015 +Node: PIVOTING69712 +Ref: #pivoting69817 +Node: OUTPUT71503 +Ref: #output71605 +Node: Output destination71696 +Ref: #output-destination71830 +Node: Output styling72487 +Ref: #output-styling72635 +Node: Output format73392 +Ref: #output-format73536 +Node: CSV output74900 +Ref: #csv-output75018 +Node: HTML output75121 +Ref: #html-output75261 +Node: JSON output75355 +Ref: #json-output75495 +Node: SQL output76412 +Ref: #sql-output76530 +Node: Commodity styles77031 +Ref: #commodity-styles77158 +Node: COMMANDS77934 +Ref: #commands78046 +Node: accounts81411 +Ref: #accounts81511 +Node: activity82319 +Ref: #activity82431 +Node: add82814 +Ref: #add82917 +Node: aregister85712 +Ref: #aregister85826 +Node: aregister and custom posting dates88495 +Ref: #aregister-and-custom-posting-dates88661 +Node: balance89213 +Ref: #balance89332 +Node: balance features90325 +Ref: #balance-features90465 +Node: Simple balance report92389 +Ref: #simple-balance-report92571 +Node: Filtered balance report94051 +Ref: #filtered-balance-report94238 +Node: List or tree mode94565 +Ref: #list-or-tree-mode94733 +Node: Depth limiting96078 +Ref: #depth-limiting96244 +Node: Dropping top-level accounts96845 +Ref: #dropping-top-level-accounts97047 +Node: Multi-period balance report97357 +Ref: #multi-period-balance-report97570 +Node: Showing declared accounts99845 +Ref: #showing-declared-accounts100038 +Node: Data layout100569 +Ref: #data-layout100724 +Node: Sorting by amount108664 +Ref: #sorting-by-amount108819 +Node: Percentages109489 +Ref: #percentages109647 +Node: Balance change end balance110608 +Ref: #balance-change-end-balance110801 +Node: Balance report types112229 +Ref: #balance-report-types112419 +Node: Useful balance reports116698 +Ref: #useful-balance-reports116879 +Node: Budget report117964 +Ref: #budget-report118148 +Node: Budget report start date123423 +Ref: #budget-report-start-date123601 +Node: Budgets and subaccounts124933 +Ref: #budgets-and-subaccounts125140 +Node: Selecting budget goals128580 +Ref: #selecting-budget-goals128752 +Node: Customising single-period balance reports129786 +Ref: #customising-single-period-balance-reports129995 +Node: balancesheet132170 +Ref: #balancesheet132308 +Node: balancesheetequity133636 +Ref: #balancesheetequity133787 +Node: cashflow135190 +Ref: #cashflow135314 +Node: check136746 +Ref: #check136851 +Node: Basic checks137485 +Ref: #basic-checks137603 +Node: Strict checks138154 +Ref: #strict-checks138295 +Node: Other checks138731 +Ref: #other-checks138871 +Node: Custom checks139228 +Ref: #custom-checks139348 +Node: close139765 +Ref: #close139869 +Node: close and prices141960 +Ref: #close-and-prices142089 +Node: close date142484 +Ref: #close-date142668 +Node: Example close asset/liability accounts for file transition143425 +Ref: #example-close-assetliability-accounts-for-file-transition143726 +Node: Hiding opening/closing transactions144585 +Ref: #hiding-openingclosing-transactions144856 +Node: close and balance assertions146233 +Ref: #close-and-balance-assertions146491 +Node: Example close revenue/expense accounts to retained earnings147845 +Ref: #example-close-revenueexpense-accounts-to-retained-earnings148123 +Node: codes149013 +Ref: #codes149123 +Node: commodities149835 +Ref: #commodities149964 +Node: descriptions150046 +Ref: #descriptions150176 +Node: diff150480 +Ref: #diff150588 +Node: files151635 +Ref: #files151737 +Node: help151884 +Ref: #help151986 +Node: import152804 +Ref: #import152920 +Node: Deduplication154013 +Ref: #deduplication154138 +Node: Import testing156032 +Ref: #import-testing156197 +Node: Importing balance assignments156685 +Ref: #importing-balance-assignments156891 +Node: Commodity display styles157540 +Ref: #commodity-display-styles157713 +Node: incomestatement157842 +Ref: #incomestatement157977 +Node: notes159309 +Ref: #notes159424 +Node: payees159792 +Ref: #payees159900 +Node: prices160426 +Ref: #prices160534 +Node: print160903 +Ref: #print161015 +Node: print-unique166383 +Ref: #print-unique166511 +Node: register166796 +Ref: #register166925 +Node: Custom register output171675 +Ref: #custom-register-output171806 +Node: register-match173143 +Ref: #register-match173279 +Node: rewrite173630 +Ref: #rewrite173747 +Node: Re-write rules in a file175653 +Ref: #re-write-rules-in-a-file175816 +Node: Diff output format176965 +Ref: #diff-output-format177148 +Node: rewrite vs print --auto178240 +Ref: #rewrite-vs.-print---auto178400 +Node: roi178956 +Ref: #roi179056 +Node: Spaces and special characters in --inv and --pnl180781 +Ref: #spaces-and-special-characters-in---inv-and---pnl181021 +Node: Semantics of --inv and --pnl181509 +Ref: #semantics-of---inv-and---pnl181748 +Node: IRR and TWR explained183598 +Ref: #irr-and-twr-explained183758 +Node: stats186844 +Ref: #stats186945 +Node: tags188325 +Ref: #tags188425 +Node: test189439 +Ref: #test189555 +Node: About add-on commands190302 +Ref: #about-add-on-commands190439 +Node: JOURNAL FORMAT191570 +Ref: #journal-format191698 +Node: Transactions193925 +Ref: #transactions194040 +Node: Dates195054 +Ref: #dates195170 +Node: Simple dates195235 +Ref: #simple-dates195355 +Node: Secondary dates195864 +Ref: #secondary-dates196012 +Node: Posting dates197348 +Ref: #posting-dates197471 +Node: Status198843 +Ref: #status198953 +Node: Code200661 +Ref: #code200773 +Node: Description201005 +Ref: #description201133 +Node: Payee and note201453 +Ref: #payee-and-note201561 +Node: Comments201896 +Ref: #comments202018 +Node: Tags203212 +Ref: #tags-1203323 +Node: Postings204716 +Ref: #postings204840 +Node: Virtual postings205866 +Ref: #virtual-postings205977 +Node: Account names207282 +Ref: #account-names207419 +Node: Amounts207907 +Ref: #amounts208044 +Node: Decimal marks digit group marks209029 +Ref: #decimal-marks-digit-group-marks209206 +Node: Commodity210227 +Ref: #commodity210416 +Node: Directives influencing number parsing and display211368 +Ref: #directives-influencing-number-parsing-and-display211629 +Node: Commodity display style212122 +Ref: #commodity-display-style212330 +Node: Rounding214525 +Ref: #rounding214645 +Node: Transaction prices215057 +Ref: #transaction-prices215223 +Node: Lot prices lot dates217654 +Ref: #lot-prices-lot-dates217837 +Node: Balance assertions218325 +Ref: #balance-assertions218503 +Node: Assertions and ordering219576 +Ref: #assertions-and-ordering219767 +Node: Assertions and multiple included files220467 +Ref: #assertions-and-multiple-included-files220729 +Node: Assertions and multiple -f files221229 +Ref: #assertions-and-multiple--f-files221482 +Node: Assertions and commodities221879 +Ref: #assertions-and-commodities222103 +Node: Assertions and prices223283 +Ref: #assertions-and-prices223491 +Node: Assertions and subaccounts223931 +Ref: #assertions-and-subaccounts224154 +Node: Assertions and virtual postings224478 +Ref: #assertions-and-virtual-postings224718 +Node: Assertions and auto postings224850 +Ref: #assertions-and-auto-postings225082 +Node: Assertions and precision225727 +Ref: #assertions-and-precision225911 +Node: Balance assignments226178 +Ref: #balance-assignments226348 +Node: Balance assignments and prices227512 +Ref: #balance-assignments-and-prices227678 +Node: Directives227902 +Ref: #directives228065 +Node: Directives and multiple files232557 +Ref: #directives-and-multiple-files232753 +Node: Comment blocks233445 +Ref: #comment-blocks233622 +Node: Including other files233798 +Ref: #including-other-files233972 +Node: Default year234896 +Ref: #default-year235054 +Node: Declaring payees235461 +Ref: #declaring-payees235632 +Node: Declaring the decimal mark235878 +Ref: #declaring-the-decimal-mark236078 +Node: Declaring commodities236475 +Ref: #declaring-commodities236666 +Node: Commodity error checking239184 +Ref: #commodity-error-checking239334 +Node: Default commodity239849 +Ref: #default-commodity240029 +Node: Declaring market prices241145 +Ref: #declaring-market-prices241334 +Node: Declaring accounts242147 +Ref: #declaring-accounts242327 +Node: Account error checking243551 +Ref: #account-error-checking243717 +Node: Account comments244896 +Ref: #account-comments245080 +Node: Account subdirectives245521 +Ref: #account-subdirectives245706 +Node: Account types246024 +Ref: #account-types246198 +Node: Account display order249873 +Ref: #account-display-order250033 +Node: Rewriting accounts251184 +Ref: #rewriting-accounts251363 +Node: Basic aliases252403 +Ref: #basic-aliases252539 +Node: Regex aliases253283 +Ref: #regex-aliases253445 +Node: Combining aliases254335 +Ref: #combining-aliases254518 +Node: Aliases and multiple files255794 +Ref: #aliases-and-multiple-files255993 +Node: end aliases256572 +Ref: #end-aliases256766 +Node: Aliases can generate bad account names256915 +Ref: #aliases-can-generate-bad-account-names257158 +Node: Aliases and account types257743 +Ref: #aliases-and-account-types257940 +Node: Default parent account258636 +Ref: #default-parent-account258826 +Node: Periodic transactions259710 +Ref: #periodic-transactions259893 +Node: Periodic rule syntax261848 +Ref: #periodic-rule-syntax262028 +Node: Periodic rules and relative dates262487 +Ref: #periodic-rules-and-relative-dates262755 +Node: Two spaces between period expression and description!263266 +Ref: #two-spaces-between-period-expression-and-description263592 +Node: Forecasting with periodic transactions264276 +Ref: #forecasting-with-periodic-transactions264575 +Node: Budgeting with periodic transactions267346 +Ref: #budgeting-with-periodic-transactions267579 +Node: Auto postings267988 +Ref: #auto-postings268124 +Node: Auto postings and multiple files270303 +Ref: #auto-postings-and-multiple-files270501 +Node: Auto postings and dates270710 +Ref: #auto-postings-and-dates270978 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions271153 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions271498 +Node: Auto posting tags272001 +Ref: #auto-posting-tags272210 +Node: CSV FORMAT272846 +Ref: #csv-format272974 +Node: Examples275603 +Ref: #examples275706 +Node: Basic275914 +Ref: #basic276016 +Node: Bank of Ireland276558 +Ref: #bank-of-ireland276695 +Node: Amazon278157 +Ref: #amazon278277 +Node: Paypal279996 +Ref: #paypal280092 +Node: CSV rules287736 +Ref: #csv-rules287854 +Node: skip288187 +Ref: #skip288287 +Node: fields list288662 +Ref: #fields-list288801 +Node: field assignment290367 +Ref: #field-assignment290519 +Node: Field names291554 +Ref: #field-names291694 +Node: date field292074 +Ref: #date-field292194 +Node: date2 field292242 +Ref: #date2-field292385 +Node: status field292441 +Ref: #status-field292586 +Node: code field292635 +Ref: #code-field292782 +Node: description field292827 +Ref: #description-field292989 +Node: comment field293048 +Ref: #comment-field293205 +Node: account field293516 +Ref: #account-field293668 +Node: amount field294243 +Ref: #amount-field294394 +Node: currency field295639 +Ref: #currency-field295794 +Node: balance field296051 +Ref: #balance-field296185 +Node: separator296557 +Ref: #separator296689 +Node: if block297229 +Ref: #if-block297356 +Node: Matching the whole record297757 +Ref: #matching-the-whole-record297934 +Node: Matching individual fields298737 +Ref: #matching-individual-fields298943 +Node: Combining matchers299167 +Ref: #combining-matchers299365 +Node: Rules applied on successful match299678 +Ref: #rules-applied-on-successful-match299871 +Node: if table300525 +Ref: #if-table300646 +Node: end302384 +Ref: #end302498 +Node: date-format302722 +Ref: #date-format302856 +Node: decimal-mark303852 +Ref: #decimal-mark303999 +Node: newest-first304338 +Ref: #newest-first304481 +Node: include305164 +Ref: #include305297 +Node: balance-type305741 +Ref: #balance-type305863 +Node: Tips306563 +Ref: #tips306654 +Node: Rapid feedback306953 +Ref: #rapid-feedback307072 +Node: Valid CSV307524 +Ref: #valid-csv307656 +Node: File Extension307848 +Ref: #file-extension308002 +Node: Reading multiple CSV files308431 +Ref: #reading-multiple-csv-files308618 +Node: Valid transactions308859 +Ref: #valid-transactions309039 +Node: Deduplicating importing309667 +Ref: #deduplicating-importing309848 +Node: Setting amounts310884 +Ref: #setting-amounts311041 +Node: Amount signs313485 +Ref: #amount-signs313639 +Node: Setting currency/commodity314326 +Ref: #setting-currencycommodity314514 +Node: Amount decimal places315688 +Ref: #amount-decimal-places315880 +Node: Referencing other fields316192 +Ref: #referencing-other-fields316391 +Node: How CSV rules are evaluated317288 +Ref: #how-csv-rules-are-evaluated317463 +Node: TIMECLOCK FORMAT318914 +Ref: #timeclock-format319054 +Node: TIMEDOT FORMAT321115 +Ref: #timedot-format321253 +Node: COMMON TASKS325815 +Ref: #common-tasks325944 +Node: Getting help326351 +Ref: #getting-help326485 +Node: Constructing command lines327075 +Ref: #constructing-command-lines327269 +Node: Starting a journal file327966 +Ref: #starting-a-journal-file328166 +Node: Setting opening balances329354 +Ref: #setting-opening-balances329552 +Node: Recording transactions332693 +Ref: #recording-transactions332875 +Node: Reconciling333431 +Ref: #reconciling333576 +Node: Reporting335833 +Ref: #reporting335975 +Node: Migrating to a new file339974 +Ref: #migrating-to-a-new-file340124 +Node: LIMITATIONS340423 +Ref: #limitations340551 +Node: TROUBLESHOOTING341294 +Ref: #troubleshooting341409  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -6,8004 +6,7998 @@ NAME This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger's concepts and file formats. This - manual is for hledger 1.26. - -SYNOPSIS - hledger - - hledger [-f FILE] COMMAND [OPTIONS] [ARGS] - - hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] - -DESCRIPTION - hledger is a reliable, cross-platform set of programs for tracking - money, time, or any other commodity, using double-entry accounting and - a simple, editable file format. hledger is inspired by and largely - compatible with ledger(1). - - The basic function of the hledger CLI is to read a plain text file - describing financial transactions (in accounting terms, a general jour- - nal) and print useful reports on standard output, or export them as - CSV. hledger can also read some other file formats such as CSV files, - translating them to journal format. Additionally, hledger lists other - hledger-* executables found in the user's $PATH and can invoke them as - subcommands. - - hledger reads data from one or more files in hledger journal, time- - clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must - be a real environment variable, not a shell variable. You can specify - standard input with -f-. - - Transactions are dated movements of money between two (or more) named - accounts, and are recorded with journal entries like this: - - 2015/10/16 bought food - expenses:food $10 - assets:cash - - Most users use a text editor to edit the journal, usually with an edi- - tor mode such as ledger-mode for added convenience. hledger's interac- - tive add command is another way to record new transactions. hledger - never changes existing transactions. - - To get started, you can either save some entries like the above in - ~/.hledger.journal, or run hledger add and follow the prompts. Then - try some commands like hledger print or hledger balance. Run hledger - with no arguments for a list of commands. - -OPTIONS - General options - To see general usage help, including general options which are sup- - ported by most hledger commands, run hledger -h. - - General help options: - - -h --help - show general 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 fol- - lowing 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 com- - modities - - -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 charac- - ters. 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. - - 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. - - 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 noth- - ing). 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. - - Special characters - 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 dou- - ble 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. - - 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:\\$ - - 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 argu- - ments 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:\\$ - - 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: - - o an @argumentfile - - o hledger-ui's filter field - - o hledger-web's search form - - o GHCI's prompt (used by developers). - - Unicode characters - hledger is expected to handle non-ascii characters correctly: - - o 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.) - - o 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: - - o 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 Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- - grams). - - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode - - o the terminal must be using a font which includes the required unicode - glyphs - - o the terminal should be configured to display wide characters as dou- - ble width (for report alignment) - - o 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 stan- - dard 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). - - Regular expressions - hledger uses regular expressions in a number of places: - - o query terms, on the command line and in the hledger-web search form: - REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX - - o CSV rules conditional blocks: if REGEX ... - - o account alias directives and options: alias /REGEX/ = REPLACEMENT, - --alias /REGEX/=REPLACEMENT - - hledger's regular expressions come from the regex-tdfa library. 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: - - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, - these are not required. - - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts - with the dollar sign in hledger-web, write cur:\$. - - o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped at least once more. See Spe- - cial characters. - -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\MyUser- - Name\.hledger.journal. You can change this by running a command like - this in a powershell window: - - > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - - (Let us know if you need to be an Administrator, and if this persists - across a reboot.) - - 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. - -DATA FILES - hledger reads transactions from one or more data files. The default - data file is $HOME/.hledger.journal (or on Windows, something like - C:/Users/USER/.hledger.journal). - - You can override this with the $LEDGER_FILE environment variable: - - $ setenv LEDGER_FILE ~/finance/2016.journal - $ hledger stats - - or with 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- - - 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 exten- - sions: - ----------------------------------------------------------------------------- - journal hledger journal files and some Ledger .journal .j .hledger - journals, for transactions .ledger - time- timeclock files, for precise time log- .timeclock - clock ging - 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 their own sections, 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:- - - Multiple files - You can specify multiple -f options, to read multiple files as one big - journal. There are some limitations with this: - - o most directives do not affect sibling files - - o balance assertions will not see any account balances from previous - files - - If you need either of those things, you can - - o use a single parent file which includes the others - - o or concatenate the files into one before reading, eg: cat a.journal - b.journal | hledger -f- CMD. - - Strict mode - hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files - without a lot of declarations: - - o Are the input files parseable, with valid syntax ? - - o Are all transactions balanced ? - - o Do all balance assertions pass ? - - With the -s/--strict flag, additional checks are performed: - - o Are all accounts posted to, declared with an account directive ? - (Account error checking) - - o Are all commodities declared with a commodity directive ? (Commodity - error checking) - - o Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks -- the ones - listed above and some more. - -TIME PERIODS - Smart dates - hledger's user interfaces accept a flexible "smart date" syntax. Smart - dates allow some english words, can be relative to today's date, and - can have less-significant date parts omitted (defaulting to 1). - - Examples: - - - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year - 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 - 2004 start of year - 2004/10 start of month - 10/1 month and day in current year - 21 day in current month - october, oct start of month in current year - yesterday, today, tomor- -1, 0, 1 days from today - row - last/this/next -1, 0, 1 periods from the current period - day/week/month/quar- - ter/year - in n n periods from the current period - days/weeks/months/quar- - ters/years - n n periods from the current period - days/weeks/months/quar- - ters/years ahead - n -n periods from the current period - days/weeks/months/quar- - ters/years ago - 20181201 8 digit YYYYMMDD with valid year month and day - 201812 6 digit YYYYMM with valid year and month - - Counterexamples - malformed digit sequences might give surprising - results: - - - 201813 6 digits with an invalid month is parsed as start of - 6-digit year - 20181301 8 digits with an invalid month is parsed as start of - 8-digit year - 20181232 8 digits with an invalid day gives an error - 201801012 9+ digits beginning with a valid YYYYMMDD gives an error - - Note "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; those are not affected by --today.) - - - Report start & end date - By default, most hledger reports will show the full span of time repre- - sented by the journal data. 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. - - Some notes: - - o End dates are exclusive, as in Ledger, so you should write the date - after the last day you want to see in the report. - - o As noted in reporting options: among start/end dates specified with - options, the last (i.e. right-most) option takes precedence. - - o 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. - - o A report interval (see below) will adjust start/end dates, when - needed, so that they fall on subperiod boundaries. - - Examples: - - - -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year - (11/30 will be the last date included) - -b thismonth all transactions on or after the 1st of the current month - -p thismonth all transactions in the current month - date:2016/3/17.. the above written as queries instead (.. can also be - replaced with -) - date:..12/1 - date:thismonth.. - date:thismonth - - Report intervals - A report interval can be specified so that commands like register, bal- - ance and activity become multi-period, showing each subperiod as a sep- - arate row or column. - - The following "standard" report intervals can be enabled by using their - corresponding flag: - - o -D/--daily - - o -W/--weekly - - o -M/--monthly - - o -Q/--quarterly - - o -Y/--yearly - - These standard intervals always start on natural interval boundaries: - eg --weekly starts on mondays, --monthly starts on the first of the - month, --yearly always starts on January 1st, etc. - - Certain more complex intervals, and more flexible boundary dates, can - be specified by -p/--period. These are described in period expres- - sions, below. - - Report intervals can only be specified by the flags above, and not by - query arguments, currently. - - Report intervals have another effect: multi-period reports are always - expanded to fill a whole number of subperiods. So if you use a report - interval (other than --daily), and you have specified a start or end - date, you may notice those dates being overridden (ie, the report - starts earlier than your requested start date, or ends later than your - requested end date). This is done to ensure "full" first and last sub- - periods, so that all subperiods' numbers are comparable. - - To summarise: - - o In multiperiod reports, all subperiods are forced to be the same - length, to simplify reporting. - - o Reports with the standard --weekly/--monthly/--quarterly/--yearly - intervals are required to start on the first day of a - week/month/quarter/year. We'd like more flexibility here but it - isn't supported yet. - - o --period (below) can specify more complex intervals, starting on any - date. - - Period expressions - The -p/--period option accepts period expressions, a shorthand way of - expressing a start date, end date, and/or report interval all at once. - - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as - exclusive: - - - -p "from 2009/1/1 to 2009/4/1" - - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as - ".." or "-". These are equivalent to the above: - - - -p "2009/1/1 2009/4/1" - -p2009/1/1to2009/4/1 - -p2009/1/1..2009/4/1 - - Dates are smart dates, so if the current year is 2009, the above can - also be written as: - - - -p "1/1 4/1" - -p "january-apr" - -p "this year to 4/1" - - If you specify only one date, the missing start or end date will be the - earliest or latest transaction in your journal: - - - -p "from 2009/1/1" everything after january - 1, 2009 - -p "from 2009/1" the same - -p "from 2009" the same - -p "to 2009" everything before january - 1, 2009 - - A single date with no "from" or "to" defines both the start and end - date like so: - - - -p "2009" the year 2009; equivalent - to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- - lent to "2009/1/1 to - 2009/2/1" - -p "2009/1/1" just that day; equivalent - to "2009/1/1 to 2009/1/2" - - Or you can specify a single quarter like so: - - - -p "2009Q1" first quarter of 2009, - equivalent to "2009/1/1 to - 2009/4/1" - -p "q4" fourth quarter of the cur- - rent year - - Period expressions with a report interval - -p/--period's argument can also begin with, or entirely consist of, a - report interval. This should be separated from the start/end dates (if - any) by a space, or the word in. The basic intervals (which can also - be written as command line flags) are daily, weekly, monthly, quar- - terly, and yearly. Some examples: - - - -p "weekly from 2009/1/1 to 2009/4/1" - -p "monthly in 2008" - -p "quarterly" - - As mentioned above, the weekly, monthly, quarterly and yearly intervals - require a report start date that is the first day of a week, month, - quarter or year. And, report start/end dates will be expanded if - needed to span a whole number of intervals. - - For example: - - - -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- - to 2009/4/1" day - -p "monthly in starts on 2018/11/01 - 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, - 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 - -p "yearly from starts on 2009/01/01, first day of 2009 - 2009-12-29" - - More complex report intervals - Some more complex kinds of interval are also supported in period - expressions: - - o biweekly - - o fortnightly - - o bimonthly - - o every day|week|month|quarter|year - - o every N days|weeks|months|quarters|years - - These too will cause report start/end dates to be expanded, if needed, - to span a whole number of intervals. Examples: - - - -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, - 2008/03/01, ... - -p "every 2 weeks" starts on closest preceding Monday - -p "every 5 months from periods will have boundaries on 2009/03/01, - 2009/03" 2009/08/01, ... - - Intervals with custom start date - All intervals mentioned above are required to start on their natural - calendar boundaries, but the following intervals can start on any date: - - Weekly on custom day: - - o every Nth day of week (th, nd, rd, or st are all accepted after the - number) - - o every WEEKDAYNAME (full or three-letter english weekday name, case - insensitive) - - Monthly on custom day: - - o every Nth day [of month] - - o every Nth WEEKDAYNAME [of month] - - Yearly on custom day: - - o every MM/DD [of year] (month number and day of month number) - - o every MONTHNAME DDth [of year] (full or three-letter english month - name, case insensitive, and day of month number) - - o every DDth MONTHNAME [of year] (equivalent to the above) - - Examples: - - - - - -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" - - Periods or dates ? - Report intervals like the above are most often used with -p|--period, - to divide reports into multiple subperiods - each generated date marks - a subperiod boundary. Here, the periods between the dates are what's - important. - - But report intervals can also be used with --forecast to generate - future transactions, or with balance --budget to generate budget goal- - setting transactions. For these, the dates themselves are what mat- - ters. - - Events on multiple weekdays - The every WEEKDAYNAME form has a special variant with multiple day - names, comma-separated. Eg: every mon,thu,sat. Also, weekday and - weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec- - tively. - - This form is mainly intended for use with --forecast, to generate peri- - odic transactions on arbitrary days of the week. It may be less useful - with -p, since it divides each week into subperiods of unequal length. - (Because gaps between periods are not allowed; if you'd like to change - this, see #1632.) - - Examples: - - - -p "every dates will be Mon, Wed, Fri; periods will be Mon- - mon,wed,fri" Tue, Wed-Thu, Fri-Sun - -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will - be Mon, Tue, Wed, Thu, Fri-Sun - -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri - day" - -DEPTH - With the --depth NUM option (short form: -NUM), commands like account, - balance and register will show only the uppermost accounts in the - account tree, down to level NUM. 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. - -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 argu- - ments to restrict their scope. The syntax is as follows: - - o Zero or more space-separated query terms. These are most often - account name substrings: - - utilities food:groceries - - o Terms with spaces or other special characters should be enclosed in - quotes: - - "personal care" - - o Regular expressions are also supported: - - "^expenses\b" "accounts (payable|receivable)" - - o Add a query type prefix to match other parts of the data: - - date:202012- desc:amazon cur:USD amt:">100" status: - - o Add a not: prefix to negate a term: - - not:cur:USD - - 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 expres- - sion. This is the default query type when there is no prefix, and reg- - ular 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. Oth- - erwise, the absolute magnitudes are compared, ignoring sign. - - code:REGEX - Match by transaction code (eg check number). - - cur:REGEX - Match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a 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). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, - case insensitive. Note type:A and type:E will also match their respec- - tive 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: - - o Accounts also inherit the tags of their parent accounts - - o Postings also inherit the tags of their account and their transaction - - o 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.) - - Combining query terms - Most commands select things which match: - - o any of the description terms AND - - o any of the account terms AND - - o any of the status terms AND - - o all the other terms. - - while the print command shows transactions which: - - o match any of the description terms AND - - o have any postings matching any of the positive account terms AND - - o have no postings matching any of the negative account terms AND - - o match all the other terms. - - You can do more powerful queries (such as AND-ing two like terms) by - running a first query with print, and piping the result into a second - hledger command. Eg: how much of food expenses was paid with cash ? - - $ hledger print assets:cash | hledger -f- -I balance expenses:food - - If you are interested in full boolean expressions for queries, see - #203. - - 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. - - Queries and account aliases - When account names are rewritten with --alias or alias, acct: will - match either the old or the new account name. - - 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). - - 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. - - 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. - -CONVERSION & COST - This section is about converting between commodities. Some defini- - tions: - - o A "commodity conversion" is an exchange of one currency or commodity - for another. Eg a foreign currency exchange, or a purchase or sale - of stock or cryptocurrency. - - o A "conversion transaction" is a transaction involving one or more - such conversions. - - o "Conversion rate" is the exchange rate in a conversion - the cost per - unit of one commodity in the other. - - o "Cost" is how much of one commodity was paid to acquire the other - (when buying), or how much was received in exchange for the other - (when selling). We call both of these "cost" for convenience (after - all, it is cost for one party or the other). - - Recording conversions - As a concrete example, let's assume 100 EUR was converted to 120 USD. - There are several ways to record this in the journal, each with pros - and cons which will be explained in more detail below. (Also, these - examples use journal format which is properly explained much further - below; sorry about that, you may want to read some of that first.) - - Implicit conversion - 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: - - o Easy, concise - - o hledger can do cost reporting - - Con: - - o Less error checking - typos in amounts or commodity symbols may not - be detected - - o conversion rate is not clear - - o disturbs the accounting equation - - You can prevent accidental implicit conversions due to a mistyped com- - modity symbol, by using hledger check commodities. You can prevent - implicit conversions entirely, by using hledger check balancednoauto- - conversion, or -s/--strict. - - Priced conversion - 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: - - o Still concise - - o makes the conversion rate clear - - o provides some error checking - - o hledger can do cost reporting - - Con: - - o Disturbs the accounting equation - - Equity conversion - In strict double entry bookkeeping, the above transaction is not bal- - anced 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: - - o Preserves the accounting equation - - o keeps track of conversions and related gains/losses in one place - - o works in any double entry accounting system - - Con: - - o More verbose - - o conversion rate is not clear - - o hledger can not do cost reporting - - Priced equity conversion - Another possible notation would be to record both the conversion rate - and the equity postings: - - 2021-01-01 - assets:cash -100 EUR @ 1.20 USD - equity:conversion 100 EUR - equity:conversion -120 USD - assets:cash 120 USD - - hledger currently does not allow this; instead, you can record the con- - version rate as a comment. - - Inferring missing conversion rates - hledger will do this automatically for implicit conversions. Currently - it can not do this for equity conversions. - - Inferring missing equity postings - With the --infer-equity flag, hledger will add equity postings to - priced and implicit conversions (and move the conversion rate into a - comment). - - Cost reporting - With the -B/--cost flag, hledger will convert the amounts in priced and - implicit conversions to their cost in the other commodity. This is - useful to see a report of what you paid for things (or how much you - sold things for). Currently -B/--cost does not work on equity conver- - sions, and it disables --infer-equity. - - These operations are transient, only affecting reports. If you want to - change the journal file permanently, you could pipe each entry through - hledger -f- -I print [-x] [--infer-equity] [-B] - - Conversion summary - o Recording the conversion rate is good because it makes that clear and - allows cost reporting. - - o Recording equity postings is good because it balances the accounting - equation and is correct bookkeeping. - - o Combining these is not yet supported, so you have to choose. For - now, priced conversions are a good compromise, so that: - - o When you want to see the cost (or sale proceeds) of things, use - -B/--cost. - - o When you want to see a balanced balance sheet or correct journal - entries, use --infer-equity. - - o Combining these is not yet supported; -B/--cost will take prece- - dence. - - o Conversion/cost operations are performed before valuation. - -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: - - -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. - - -X: Value in specified commodity - The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to - that. - - 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. - - Market prices - 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 direc- - tive, or (with the --infer-market-prices flag) inferred from trans- - action prices. - - 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 com- - bining 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 con- - verted. - - --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 transaction prices as additional market - prices (as Ledger does) ? We could produce value reports without need- - ing P directives at all. - - 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. (And if - both occur on the same day, the P directive takes precedence). - - There is a downside: value reports can sometimes be affected in confus- - ing/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: - - o multicommodity transactions with explicit prices (@/@@) - - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. - hledger print -x can be useful for troubleshooting.) - - o but not, currently, from "more correct" multicommodity transactions - (no @, multiple commodities, balanced). - - There is another 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 con- - version might not happen because no valuation commodity was detected - (--debug=2 will show this). To be safe, specify the valuation commmod- - ity, eg: - - o -X EUR --infer-market-prices, not -V --infer-market-prices - - o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- - ket-prices - - 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 suit- - able 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: - - o If you have P directives, they determine which commodities -V will - convert, and to what. - - o If you have no P directives, and use the --infer-market-prices flag, - transaction prices determine it. - - Amounts for which no valuation commodity can be found are not con- - verted. - - Simple valuation examples - Here are some quick examples of -V: - - ; one euro is worth this many dollars from nov 1 - P 2016/11/01 EUR $1.10 - - ; purchase some euros on nov 3 - 2016/11/3 - assets:euros EUR100 - assets:checking - - ; the euro is worth fewer dollars by dec 21 - P 2016/12/21 EUR $1.03 - - How many euros do I have ? - - $ hledger -f t.j bal -N euros - EUR100 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 - - --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 commod- - ity, using market prices on each posting's date. - - --value=end - Convert amounts to their value in the default valuation commod- - ity, 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 commod- - ity using current market prices (as of when report is gener- - ated). - - --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- - ity 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. - - 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 specify- - ing a display style for A, 0.5A gets the default style, which shows no - decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- - modity 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 - - 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 - - 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, --cost -V, -X --value=then --value=end --value=DATE, - type --value=now - ----------------------------------------------------------------------------------------------- - print - posting cost value at value at posting value at value at - amounts report end date report or DATE/today - or today journal end - balance unchanged unchanged unchanged unchanged unchanged - asser- - tions/assign- - ments - - register - starting bal- cost value at valued at day value at value at - ance (-H) report or each historical report or DATE/today - journal end posting was made journal end - starting bal- cost value at day valued at day value at day value at - ance (-H) before each historical before DATE/today - with report report or posting was made report or - interval journal journal - start start - posting cost value at value at posting value at value at - amounts report or date report or DATE/today - journal end journal end - summary post- summarised value at sum of postings value at value at - ing amounts cost period ends in interval, val- period ends DATE/today - with report ued at interval - interval start - running sum/average sum/average sum/average of sum/average sum/average - total/average of displayed of displayed displayed values of displayed of displayed - values values values values - - balance (bs, - bse, cf, is) - balance sums of value at value at posting value at value at - changes costs report end date report or DATE/today of - or today of journal end sums of post- - sums of of sums of ings - postings postings - budget like balance like balance like balance like bal- like balance - amounts changes changes changes ances changes - (--budget) - grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- - played val- played val- valued played val- played values - ues ues ues - - - - balance (bs, - bse, cf, is) - with report - interval - starting bal- sums of value at sums of values of value at sums of post- - ances (-H) costs of report start postings before report start ings before - postings of sums of report start at of sums of report start - before all postings respective post- all postings - report start before ing dates before - report start report start - balance sums of same as sums of values of balance value at - changes (bal, costs of --value=end postings in change in DATE/today of - is, bs postings in period at respec- each period, sums of post- - --change, cf period tive posting valued at ings - --change) dates period ends - end balances sums of same as sums of values of period end value at - (bal -H, is costs of --value=end postings from balances, DATE/today of - --H, bs, cf) postings before period valued at sums of post- - from before start to period period ends ings - report start end at respective - to period posting dates - end - budget like balance like balance like balance like bal- like balance - amounts changes/end changes/end changes/end bal- ances changes/end - (--budget) balances balances ances balances - row totals, sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- - (-T, -A) played val- played val- played val- played values - ues ues ues - column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- - played val- played val- values played val- played values - ues ues ues - grand total, sum, average sum, average sum, average of sum, average sum, average - grand average of column of column column totals of column of column - totals totals totals 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 subperi- - ods). - -PIVOTING - Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD - can be: status, code, description, payee, note, or the full name (case - insensitive) of any tag. As with account names, values containing - colon:separated:parts will be displayed hierarchically in reports. - - --pivot is a general option affecting all reports; you can think of - hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on - that posting, inheriting it from the transaction or using a blank value - if it's not present. - - An example: - - 2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe - - Normal balance report showing account names: - - $ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees - -------------------- - 0 - - Pivoted balance report, using member: tag values instead: - - $ hledger balance --pivot member - 2 EUR - -2 EUR John Doe - -------------------- - 0 - - One way to show only amounts with a member: value (using a query, - described below): - - $ hledger balance --pivot member tag:member=. - -2 EUR John Doe - -------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account - name"): - - $ hledger balance --pivot member acct:. - -2 EUR John Doe - -------------------- - -2 EUR - -OUTPUT - 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 pro- - vide 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) - - hledger can optionally produce debug output (if enabled with - --debug=N); this goes to stderr, and is not affected by -o/--output- - file. If you need to capture it, use shell redirects, eg: hledger bal - --debug=3 >file 2>&1. - - Output styling - hledger commands can produce colour output when the terminal supports - it. This is controlled by the --color/--colour option: - 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. - - hledger commands can also use unicode box-drawing characters to produce - prettier tables and output. This is controlled by the --pretty option: - - 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. - - Output format - Some commands offer additional output formats, other than the usual - plain text terminal output. Here are those commands and the formats - currently supported: - - - - txt csv html json sql - --------------------------------------------- - aregister Y Y Y - balance Y 1 Y 1 Y 1,2 Y - bal- Y 1 Y 1 Y 1 Y - ancesheet - bal- Y 1 Y 1 Y 1 Y - ancesheete- - quity - cashflow Y 1 Y 1 Y 1 Y - incomes- Y 1 Y 1 Y 1 Y - tatement - print Y Y Y Y - register Y Y Y - - o 1 Also affected by the balance commands' --layout option. - - o 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 - - CSV output - o In CSV output, digit group marks (such as thousands separators) are - disabled automatically. - - HTML output - o HTML output can be styled by an optional hledger.css file in the same - directory. - - JSON output - o Not yet much used; real-world feedback is welcome. - - o Our JSON is rather large and verbose, as it is quite a faithful rep- - resentation 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. - - o 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) - - SQL output - o Not yet much used; real-world feedback is welcome. - - o SQL output is expected to work with sqlite, MySQL and PostgreSQL - - o SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables cre- - ated 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. - - Commodity styles - The display style of a commodity/currency is inferred according to the - rules described in Commodity display style. The inferred display style - can be overridden by an optional -c/--commodity-style option (Excep- - tions: as is the case for inferred styles, price amounts, and all - amounts displayed by the print command, will be displayed with all of - their decimal digits visible, regardless of the specified precision). - For example, the following will override the display style for dollars. - - $ hledger print -c '$1.000,0' - - The format specification of the style is identical to the commodity - display style specification for the commodity directive. The command - line option can be supplied repeatedly to override the display style - for multiple commodity/currency symbols. - -COMMANDS - hledger provides a number of commands for producing reports and manag- - ing your data. Run hledger with no arguments to list the commands - available, and hledger CMD to run a command. CMD can be the full com- - mand name, or its standard abbreviation shown in the commands list, or - any unambiguous prefix of the name. Eg: hledger bal. - - Here are the built-in commands, with the most often-used in bold: - - Data entry: - - These data entry commands are the only ones which can modify your jour- - nal file. - - o add - add transactions using guided prompts - - o import - add any new transactions from other files (eg csv) - - Data management: - - o check - check for various kinds of issue in the data - - o close (equity) - generate balance-resetting transactions - - o diff - compare account transactions in two journal files - - o rewrite - generate extra postings, similar to print --auto - - Financial statements: - - o aregister (areg) - show transactions in a particular account - - o balancesheet (bs) - show assets, liabilities and net worth - - o balancesheetequity (bse) - show assets, liabilities and equity - - o cashflow (cf) - show changes in liquid assets - - o incomestatement (is) - show revenues and expenses - - o roi - show return on investments - - Miscellaneous reports: - - o accounts - show account names - - o activity - show postings-per-interval bar charts - - o balance (bal) - show balance changes/end balances/budgets in any - accounts - - o codes - show transaction codes - - o commodities - show commodity/currency symbols - - o descriptions - show unique transaction descriptions - - o files - show input file paths - - o help - show hledger user manuals in several formats - - o notes - show unique note segments of transaction descriptions - - o payees - show unique payee segments of transaction descriptions - - o prices - show market price records - - o print - show transactions (journal entries) - - o print-unique - show only transactions with unique descriptions - - o register (reg) - show postings in one or more accounts & running - total - - o register-match - show a recent posting that best matches a descrip- - tion - - o stats - show journal statistics - - o tags - show tag names - - o test - run self tests - - Add-on commands: - - Programs or scripts named hledger-SOMETHING in your PATH are add-on - commands; these appear in the commands list with a + mark. Two of - these are maintained and released with hledger: - - o ui - an efficient terminal interface (TUI) for hledger - - o web - a simple web interface (WUI) for hledger - - And these add-ons are maintained separately: - - o iadd - a more interactive alternative for the add command - - o interest - generates interest transactions according to various - schemes - - o stockquotes - downloads market prices for your commodities from - AlphaVantage (experimental) - - Next, the detailed command docs, in alphabetical order. - - accounts - accounts - Show account names. - - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N - or -N. - - With --types, it also shows each account's type, if it's known. (See - Declaring accounts > Account types.) - - Examples: - - $ hledger accounts - assets:bank:checking - assets:bank:saving - assets:cash - expenses:food - expenses:supplies - income:gifts - income:salary - liabilities:debts - - activity - activity - Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the - default). With query arguments, it counts only matched transactions. - - Examples: - - $ hledger activity --quarterly - 2008-01-01 ** - 2008-04-01 ******* - 2008-07-01 - 2008-10-01 ** - - add - add - Prompt for transactions and add them to the journal. 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 trans- - actions, 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: - - o add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as a - template. - - o You can also set the initial defaults with command line arguments. - - o Readline-style edit keys can be used during data entry. - - o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is - empty, it will insert the default value. - - o If the journal defines a default commodity, it will be added to any - bare numbers entered. - - o A parenthesised transaction code may be entered following a date. - - o Comments and tags may be entered following a description or amount. - - o If you make a mistake, enter < at any prompt to go one step backward. - - o Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see the tutorial for a detailed explanation): - - $ hledger add - Adding transactions to journal file /src/hledger/examples/sample.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to 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). - - aregister - 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 areg- - ister 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. - (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, - hledger areg checking would select assets:aaa:checking.) - - 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 transac- - tions shown. Note some queries will disturb the running balance, caus- - ing 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: - - o the transaction's date (or the relevant posting's date if different, - see below) - - o the names of all the other account(s) involved in this transaction - (probably abbreviated) - - o the total change to this account's balance from this transaction - - o 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. - - 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. - - balance - 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, bal- - ancesheetequity, cashflow and incomestatement. When you need more con- - trol, then use balance. - - 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.. - - o accounts as a list (-l) or a tree (-t) - - o optionally depth-limited (-[1-9]) - - o sorted by declaration order and name, or by amount - - ..and their.. - - o balance changes (the default) - - o or actual and planned balance changes (--budget) - - o or value of balance changes (-V) - - o or change of balance values (--valuechange) - - o or unrealised capital gain/loss (--gain) - - ..in.. - - o one time period (the whole journal period by default) - - o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) - - ..either.. - - o per period (the default) - - o or accumulated since report start date (--cumulative) - - o or accumulated since account creation (--historical/-H) - - ..possibly converted to.. - - o cost (--value=cost[,COMM]/--cost/-B) - - o or market value, as of transaction dates (--value=then[,COMM]) - - o or at period ends (--value=end[,COMM]) - - o or now (--value=now) - - o or at some other date (--value=YYYY-MM-DD) - - ..with.. - - o totals (-T), averages (-A), percentages (-%), inverted sign - (--invert) - - o rows and columns swapped (--transpose) - - o another field used as account name (--pivot) - - o custom-formatted line items (single-period reports only) (--format) - - o 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. - - 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. For real-world - accounts, this should also match their end balance at the end of the - journal period (more on this below). - - Accounts are sorted by declaration order if any, and then alphabeti- - cally 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. - - 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 - - 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: - - o "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). - - o 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-plaintextac- - counting-users. A tree mode report's final total is the sum of the - top-level balances shown, not of all the balances shown. - - o Each group of sibling accounts (ie, under a common parent) is sorted - separately. - - 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 - - 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 - - - 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), bal- - ance 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: - - o The report's start/end dates will be expanded, if necessary, to fully - encompass the displayed subperiods (so that the first and last subpe- - riods have the same duration as the others). - - o Leading and trailing periods (columns) containing all zeroes are not - shown, unless -E/--empty is used. - - o Accounts (rows) containing all zeroes are not shown, unless - -E/--empty is used. - - o Amounts with many commodities are shown in abbreviated form, unless - --no-elide is used. (experimental) - - o Average and/or total columns can be added with the -A/--average and - -T/--row-total flags. - - o The --transpose flag can be used to exchange rows and columns. - - o 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: - - o Hide the totals row with -N/--no-total - - o Convert to a single currency with -V - - o Maximize the terminal window - - o Reduce the terminal's font size - - o View with a pager like less, eg: hledger bal -D --color=yes | less - -RS - - o 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) - - o Output as HTML and view with a browser: hledger bal -D -o a.html && - open a.html - - 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. - - Data layout - The --layout option affects how multi-commodity amounts are displayed, - and some other things, influencing the overall layout of the report - data: - - o --layout=wide[,WIDTH]: commodities are shown on a single line, possi- - bly elided to the specified width - - o --layout=tall: each commodity is shown on a separate line - - o --layout=bare: amounts are shown as bare numbers, with commodity sym- - bols in a separate column - - o --layout=tidy: data is normalised to tidy form, with one row per data - value. We currently support this with CSV output only. In tidy - mode, totals and row averages are disabled (-N/--no-total is implied - and -T/--row-total and -A/--average will be ignored). - - These --layout modes are supported with some but not all of the output - formats: - - - - txt csv html json sql - ------------------------------------- - wide Y Y Y - tall Y Y Y - bare Y Y Y - tidy Y - - Examples: - - o 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 - - o Limited wide layout. A width limit reduces the width, but some com- - modities 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.. - - o 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 - - o Bare layout. Commodity symbols are kept in one column, each commod- - ity 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 - - o Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg when 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" - - o Tidy layout produces normalised "tidy data", where every variable is - a column and each row represents a single data point (see - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- - data.html). This kind of data is the easiest to process with other - software: - - $ 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" - - Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. Eg: hledger bal expenses -MAS shows your big- - gest 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). - - - Percentages - With -%/--percent, balance reports show each account's value expressed - as a percentage of the (column) total: - - $ hledger -f examples/sample.journal bal expenses -Q -% - Balance changes in 2008: - - || 2008Q1 2008Q2 2008Q3 2008Q4 - ===================++================================= - expenses:food || 0 50.0 % 0 0 - expenses:supplies || 0 50.0 % 0 0 - -------------------++--------------------------------- - || 0 100.0 % 0 0 - - Note it is not useful to calculate percentages if the amounts in a col- - umn 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:EUR - - Balance change, end balance - It's important to be clear on the meaning of the numbers shown in bal- - ance 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 post- - ings.) - - Balance report types - For more flexible reporting, there are three important option groups: - - hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] - ... - - The first two are the most important: calculation type selects the - basic calculation to perform for each table cell, while accumulation - type says which postings should be included in each cell's calculation. - Typically one or both of these are selected by default, so you don't - need to write them explicitly. A valuation type can be added if you - want to convert the basic report to value or cost. - - Calculation type: - The basic calculation to perform for each table cell. It is one of: - - o --sum : sum the posting amounts (default) - - o --budget : like --sum but also show a goal amount - - o --valuechange : show the change in period-end historical balance val- - ues (caused by deposits, withdrawals, and/or market price fluctua- - tions) - - o --gain : show the unrealised capital gain/loss, (the current valued - balance minus each amount's original cost) - - Accumulation type: - Which postings should be included in each cell's calculation. It is - one of: - - o --change : postings from column start to column end, ie within the - cell's period. Typically used to see revenues/expenses. (default - for balance, incomestatement) - - o --cumulative : postings from report start to column end, eg to show - changes accumulated since the report's start date. Rarely used. - - o --historical/-H : postings from journal start to column end, ie all - postings from account creation to the end of the cell's period. Typ- - ically used to see historical end balances of assets/liabili- - ties/equity. (default for balancesheet, balancesheetequity, cash- - flow) - - Valuation type: - Which kind of valuation, valuation date(s) and optionally a target val- - uation commodity to use. It is one of: - - o no valuation, show amounts in their original commodities (default) - - o --value=cost[,COMM] : no valuation, show amounts converted to cost - - o --value=then[,COMM] : show value at transaction dates - - o --value=end[,COMM] : show value at period end date(s) (default with - --valuechange, --gain) - - o --value=now[,COMM] : show value at today's date - - o --value=YYYY-MM-DD[,COMM] : show value at another date - - or one of their aliases: --cost/-B, --market/-V or --exchange/-X. - - 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: - - o --valuechange implies --value=end - - o --valuechange makes --change the default when used with the bal- - ancesheet/balancesheetequity commands - - o --cumulative or --historical disables --row-total/-T - - For reference, here is what the combinations of accumulation and valua- - tion show: - - - - Valua- no valuation --value= then --value= end --value= YYYY- - tion: MM-DD /now - >Accumu- - lation: - v - ------------------------------------------------------------------------------------ - --change change in period sum of posting- period-end DATE-value of - date market val- value of change change in - ues in period in period period - --cumu- change from sum of posting- period-end DATE-value of - lative report start to date market val- value of change change from - period end ues from report from report report start - start to period start to period to period end - end end - --his- change from sum of posting- period-end DATE-value of - torical journal start to date market val- value of change change from - /-H period end (his- ues from journal from journal journal start - torical end bal- start to period start to period to period end - ance) end end - - Useful balance reports - Some frequently used balance options/reports are: - - o bal -M revenues expenses - Show revenues/expenses in each month. Also available as the incomes- - tatement command. - - o bal -M -H assets liabilities - Show historical asset/liability balances at each month end. Also - available as the balancesheet command. - - o bal -M -H assets liabilities equity - Show historical asset/liability/equity balances at each month end. - Also available as the balancesheetequity command. - - o bal -M assets not:receivable - Show changes to liquid assets in each month. Also available as the - cashflow command. - - Also: - - o bal -M expenses -2 -SA - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - o bal -M --budget expenses - Show monthly expenses and budget goals. - - o bal -M --valuechange investments - Show monthly change in market value of investment assets. - - o bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert] - Show top gainers [or losers] last week - - 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 very 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: - - o Only accounts with budget goals during the report period are shown, - by default. - - o In each column, in square brackets after the actual amount, budget - goal amounts are shown, and the actual/goal percentage. (Note: bud- - get goals should be in the same commodity as the actual amount.) - - o All parent accounts are always shown, even in list mode. Eg assets, - assets:bank, and expenses above. - - o 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 transac- - tions, 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] - - For more examples and notes, see Budgeting. - - 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] - - 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 bud- - get(s) of the child account(s) would be added to the budget of their - parent, much like account balances behave. - - In the most simple case this means that once you add a budget to any - account, all its parents would have budget as well. - - To illustrate this, consider the following budget: - - ~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which 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 transac- - tions in any other subaccount of expenses:personal would be counted - towards only towards the budget of expenses:personal. - - For example, let's consider these transactions: - - ~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - 2019/01/01 Google home hub - expenses:personal:electronics $90.00 - liabilities $-90.00 - - 2019/01/02 Phone screen protector - expenses:personal:electronics:upgrades $10.00 - liabilities - - 2019/01/02 Weekly train ticket - expenses:personal:train tickets $153.00 - liabilities - - 2019/01/03 Flowers - expenses:personal $30.00 - liabilities - - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- - tions would be counted towards budgets of expenses:personal:electronics - and expenses:personal accordingly: - - $ hledger balance --budget -M - Budget performance in 2019/01: - - || Jan - ===============================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] - -------------------------------++------------------------------- - || 0 [ 0] - - And with --empty, we can get a better picture of budget allocation and - consumption: - - $ hledger balance --budget -M --empty - Budget performance in 2019/01: - - || Jan - ========================================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] - ----------------------------------------++------------------------------- - || 0 [ 0] - - Selecting budget goals - The budget report evaluates periodic transaction rules to generate spe- - cial "goal transactions", which generate the goal amounts for each - account in each report subperiod. When troubleshooting, you can use - the print command 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. - - Customising single-period balance reports - 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 (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with - data fields interpolated like so: - - %[MIN][.MAX](FIELDNAME) - - o MIN pads with spaces to at least this width (optional) - - o MAX truncates at this width (optional) - - o FIELDNAME must be enclosed in parentheses, and can be one of: - - o depth_spacer - a number of spaces equal to the account's depth, or - if MIN is specified, MIN * depth spaces. - - o account - the account's name - - o total - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how multi-com- - modity amounts are rendered: - - o %_ - render on multiple lines, bottom-aligned (the default) - - o %^ - render on multiple lines, top-aligned - - o %, - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, %(depth_spacer) has no - effect, instead %(account) has indentation built in. Experimentation - may be needed to get pleasing results. - - Some example formats: - - o %(total) - the account's total - - o %-20.20(account) - the account's name, left justified, padded to 20 - characters and clipped at 20 characters - - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on - one line - - o %20(total) %2(depth_spacer)%-(account) - the default format for the - single-column balance report - - balancesheet - balancesheet, bs - This command displays a balance sheet, showing historical ending bal- - ances 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. - - The asset and liability accounts shown are those accounts declared with - the Asset or Cash or Liability type, or otherwise all accounts under a - top-level asset or liability account (case insensitive, plurals - allowed). - - 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 sup- - ports 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 (experi- - mental) json. - - balancesheetequity - balancesheetequity, bse - This command displays a balance sheet, showing historical ending bal- - ances of asset, liability and equity accounts. Amounts are shown with - normal positive sign, as in conventional financial statements. - - The asset, liability and equity accounts shown are those accounts - declared with the Asset, Cash, Liability or Equity type, or otherwise - all accounts under a top-level asset, liability or equity account (case - insensitive, plurals allowed). - - 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 sup- - ports 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 (experi- - mental) json. - - cashflow - 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 finan- - cial statements. - - "Cash" assets are those accounts which are (or whose parents are) - declared as Cash by an account directive, like this: - - account some:liquid:asset ; type:C - - Or if there are no such declarations, all accounts - - o under a top-level asset account (case insensitive, plural allowed) - - o with some variation of cash, bank, checking or saving in their name. - - 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 sup- - ports 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 (experi- - mental) json. - - check - 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 - - Here are the checks currently available: - - Basic checks - These checks are always run automatically, by (almost) all hledger com- - mands, including check: - - o parseable - data files are well-formed and can be successfully parsed - - o balancedwithautoconversion - all transactions are balanced, inferring - missing amounts where necessary, and possibly converting commodities - using transaction prices or automatically-inferred transaction prices - - o assertions - all balance assertions in the journal are passing. - (This check can be disabled with -I/--ignore-assertions.) - - 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: - - o accounts - all account names used by transactions have been declared - - o commodities - all commodity symbols used have been declared - - o balancednoautoconversion - transactions are balanced, possibly using - explicit transaction prices but not inferred ones - - 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: - - o ordereddates - transactions are ordered by date within each file - - o payees - all payees used by transactions have been declared - - o uniqueleafnames - all account leaf names are unique - - Custom checks - A few more checks are are available as separate add-on commands, in - https://github.com/simonmichael/hledger/tree/master/bin: - - o hledger-check-tagfiles - all tag values containing / (a forward - slash) exist as file paths - - o hledger-check-fancyassertions - more complex balance assertions are - passing - - You could make similar scripts to perform your own custom checks. See: - Cookbook -> Scripting. - - close - close, equity - Prints a sample "closing" transaction bringing specified account bal- - ances to zero, and an inverse "opening" transaction restoring the same - account balances. - - If like most people you split your journal files by time, eg by year: - at the end of the year you can use this command to "close out" your - asset and liability (and perhaps equity) balances in the old file, and - reinitialise them in the new file. This helps ensure that report bal- - ances remain correct whether you are including old files or not. - (Because all closing/opening transactions except the very first will - cancel out - see example below.) - - Some people also use this command to close out revenue and expense bal- - ances at the end of an accounting period. This properly records the - period's profit/loss as "retained earnings" (part of equity), and - allows the accounting equation (A-L=E) to balance, which you could then - check by the bse report's zero total. - - You can print just the closing transaction by using the --close flag, - or just the opening transaction with the --open flag. - - Their descriptions are closing balances and opening balances by - default; you can customise these with the --close-desc and --open-desc - options. - - Just one balancing equity posting is used by default, with the amount - left implicit. The default account name is equity:opening/closing bal- - ances. You can customise the account name(s) with --close-acct and - --open-acct. (If you specify only one of these, it will be used for - both.) - - With --x/--explicit, the equity posting's amount will be shown explic- - itly, and if it involves multiple commodities, there will be a separate - equity posting for each commodity (as in the print command). - - With --interleaved, each equity posting is shown next to the posting it - balances (good for troubleshooting). - - close and prices - Transaction prices are ignored (and discarded) by closing/opening - transactions, by default. With --show-costs, they are preserved; there - will be a separate equity posting for each cost in each commodity. - This means balance -B reports will look the same after the transition. - Note if you have many foreign currency or investment transactions, this - will generate very large journal entries. - - close date - The default closing date is yesterday, or the journal's end date, - whichever is later. - - Unless you are running close on exactly the first day of the new - period, you'll want to override the closing date. This is done by - specifying a report end date, where "last day of the report period" - will be the closing date. The opening date is always the following - day. So to close on (end of) 2020-12-31 and open on (start of) - 2021-01-01, any of these will work: - - - end date argument explanation - ----------------------------------------------- - -e 2021-01-01 end dates are exclusive - -e 2021 equivalent, per smart - dates - -p 2020 equivalent, the period's - begin date is ignored - date:2020 equivalent query - - Example: close asset/liability accounts for file transition - Carrying asset/liability balances from 2020.journal into a new file for - 2021: - - $ hledger close -f 2020.journal -p 2020 assets liabilities - # copy/paste the closing transaction to the end of 2020.journal - # copy/paste the opening transaction to the start of 2021.journal - - Or: - - $ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction - $ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction - - Now, - - $ hledger bs -f 2021.journal # just new file - balances correct - $ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct - $ hledger bs -f 2020.journal # just old files - balances are zero ? - # (exclude final closing txn, see below) - - Hiding opening/closing transactions - Although the closing/opening transactions cancel out, they will be vis- - ible in reports like print and register, creating some visual clutter. - You can exclude them all with a query, like: - - $ hledger print not:desc:'opening|closing' # less typing - $ hledger print not:'equity:opening/closing balances' # more precise - - But when reporting on multiple files, this can get a bit tricky; you - may need to keep the earliest opening balances, for a historical regis- - ter report; or you may need to suppress a closing transaction, to see - year-end balances. If you find yourself needing more precise queries, - here's one solution: add more easily-matched tags to opening/closing - transactions, like this: - - ; 2019.journal - 2019-01-01 opening balances ; earliest opening txn, no tag here - ... - 2019-12-31 closing balances ; clopen:2020 - ... - - ; 2020.journal - 2020-01-01 opening balances ; clopen:2020 - ... - 2020-12-31 closing balances ; clopen:2021 - ... - - ; 2021.journal - 2021-01-01 opening balances ; clopen:2021 - ... - - Now with - - ; all.journal - include 2019.journal - include 2020.journal - include 2021.journal - - you could do eg: - - $ hledger -f all.journal reg -H checking not:tag:clopen - # all years checking register, hiding non-essential opening/closing txns - - $ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 - # 2020 year end balances, suppressing 2020 closing txn - - close and balance assertions - The closing and opening transactions will include balance assertions, - verifying that the accounts have first been reset to zero and then - restored to their previous balance. These provide valuable error - checking, alerting you when things get out of line, but you can ignore - them temporarily with -I or just remove them if you prefer. - - You probably shouldn't use status or realness filters (like -C or -R or - status:) with close, or the generated balance assertions will depend on - these flags. Likewise, if you run this command with --auto, the bal- - ance assertions would probably always require --auto. - - Multi-day transactions (where some postings have a different date) - break the balance assertions, because the money is temporarily "invisi- - ble" while in transit: - - 2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - assets:bank:checking -5 ; date: 2021/1/2 - - To fix the assertions, you can add a temporary account to track such - in-transit money (splitting the multi-day transaction into two single- - day transactions): - - ; in 2020.journal: - 2020/12/30 a purchase made in december, cleared in the next year - expenses:food 5 - liabilities:pending - - ; in 2021.journal: - 2021/1/2 clearance of last year's pending transactions - liabilities:pending 5 = 0 - assets:bank:checking - - Example: close revenue/expense accounts to retained earnings - For this, use --close to suppress the opening transaction, as it's not - needed. Also you'll want to change the equity account name to your - equivalent of "equity:retained earnings". - - Closing 2021's first quarter revenues/expenses: - - $ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ - --close-acct='equity:retained earnings' >> 2021.journal - - The same, using the default journal and current year: - - $ hledger close --close revenues expenses -p Q1 \ - --close-acct='equity:retained earnings' >> $LEDGER_FILE - - Now, the first quarter's balance sheet should show a zero (unless you - are using @/@@ notation without equity postings): - - $ hledger bse -p Q1 - - And we must suppress the closing transaction to see the first quarter's - income statement (using the description; not:'retained earnings' won't - work here): - - $ hledger is -p Q1 not:desc:'closing balances' - - codes - 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: - - 1/1 (123) - (a) 1 - - 1/1 () - (a) 1 - - 1/1 - (a) 1 - - 1/1 (126) - (a) 1 - - $ hledger codes - 123 - 124 - 126 - - $ hledger codes -E - 123 - 124 - - - 126 - - commodities - commodities - List all commodity/currency symbols used or declared in the journal. - - descriptions - 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 trans- - actions. - - Example: - - $ hledger descriptions - Store Name - Gas Station | Petrol - Person A - - diff - 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 mul- - tiple 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: - - files - files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - help - help - Show the hledger user manual in one of several formats, optionally - positioned at a given TOPIC (if possible). - - TOPIC is any heading in the manual, or the start of any heading (but - not the middle). It is case insensitive. - - Some examples: commands, print, forecast, "auto postings", "commodity - column". - - This command shows the user manual built in to this hledger version. - It can be useful if the correct version of the hledger manual, or the - usual viewing tools, are not installed on your system. - - By default it uses the best viewer it can find in $PATH, in this order: - info, man, $PAGER (unless a topic is specified), less, or stdout. When - run non-interactively, it always uses stdout. Or you can select a par- - ticular viewer with the -i (info), -m (man), or -p (pager) flags. - - import - 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' trans- - actions 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 out- - put 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. - - 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 idem- - potent.) - - 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 sav- - ing a hidden ".latest" state file in the same directory. Eg when read- - ing finance/bank.csv, it will look for and update the finance/.lat- - est.bank.csv state file. The format is simple: one or more lines con- - taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- - cessed 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 cer- - tain date. - - Note deduplication (and updating of state files) can also be done by - print --new, but this is less often used. - - 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' - - 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.) - - Commodity display styles - Imported amounts will be formatted according to the canonical commodity - styles (declared or inferred) in the main journal file. - - incomestatement - 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. - - The revenue and expense accounts shown are those accounts declared with - the Revenue or Expense type, or otherwise all accounts under a top- - level revenue or income or expense account (case insensitive, plurals - allowed). - - 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 sup- - ports 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 (experi- - mental) json. - - notes - 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 transac- - tions. 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 - - payees - 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 - - prices - prices - Print market price directives from the journal. With --infer-market- - prices, generate additional market prices from transaction prices. - With --infer-reverse-prices, also generate market prices by inverting - transaction prices. Prices (and postings providing transaction prices) - can be filtered by a query. Price amounts are displayed with their - full precision. - - print - 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 deci- - mal places are shown, as in the original journal entry (with one alter- - ation: 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: - - o Valuation affects posting amounts but not balance assertion or bal- - ance assignment amounts, potentially causing those to fail. - - o Auto postings can generate postings with too many missing amounts. - - o Account aliases can generate bad account names. - - Normally, the journal entry's explicit or implicit amount style is pre- - served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a transaction price is - implied but not written, it will not appear in the output. You can use - the -x/--explicit flag to make all amounts and transaction prices - 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 transaction prices are converted to cost - using that price. This can be used for troubleshooting. - - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is - no similar-enough match, no transaction will be shown. - - With --new, hledger prints only transactions it has not seen on a pre- - vious run. This uses the same deduplication system as the import com- - mand. (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","","","" - - o There is one CSV record per posting, with the parent transaction's - fields repeated. - - o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different - order, etc.) - - o The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - - o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or - greater amounts under debit.) - - print-unique - print-unique - Print transactions which do not reuse an already-seen description. - - Example: - - $ cat unique.journal - 1/1 test - (acct:one) 1 - 2/2 test - (acct:two) 2 - $ LEDGER_FILE=unique.journal hledger print-unique - (-f option not supported) - 2015/01/01 test - (acct:one) 1 - - register - register, reg - 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 num- - bers. 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. - - 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. - - register-match - register-match - Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger- - autosync detect already-seen transactions when importing. - - rewrite - rewrite - Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print - --auto. - - This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds - one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- - tion's first posting amount. - - Examples: - - $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' - $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' - $ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - - = ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the - two spaces between account and amount. - - More: - - $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... - $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' - $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' - $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can - use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount - includes a commodity name, the new posting amount will be in the new - commodity; otherwise, it will be in the matched posting amount's com- - modity. - - Re-write rules in a file - During the run this tool will execute so called "Automated Transac- - tions" found in any journal it process. I.e instead of specifying this - operations in command line you can put them in a journal file. - - $ rewrite-rules.journal - - Make contents look like this: - - = ^income - (liabilities:tax) *.33 - - = expenses:gifts - budget:gifts *-1 - assets:budget *1 - - Note that '=' (equality symbol) that is used instead of date in trans- - actions you usually write. It indicates the query by which you want to - match the posting to add new ones. - - $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal - - This is something similar to the commands pipeline: - - $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ - | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ - --add-posting 'assets:budget *1' \ - > rewritten-tidy-output.journal - - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- - ings. - - Diff output format - To use this tool for batch modification of your journal files you may - find useful output in form of unified diff. - - $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' - - Output might look like: - - --- /tmp/examples/sample.journal - +++ /tmp/examples/sample.journal - @@ -18,3 +18,4 @@ - 2008/01/01 income - - assets:bank:checking $1 - + assets:bank:checking $1 - income:salary - + (liabilities:tax) 0 - @@ -22,3 +23,4 @@ - 2008/06/01 gift - - assets:bank:checking $1 - + assets:bank:checking $1 - income:gifts - + (liabilities:tax) 0 - - If you'll pass this through patch tool you'll get transactions contain- - ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via - --file options and include directives inside of these files. - - Be careful. Whole transaction being re-formatted in a style of output - from hledger print. - - See also: - - https://github.com/simonmichael/hledger/issues/99 - - rewrite vs. print --auto - This command predates print --auto, and currently does much the same - thing, but with these differences: - - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect - only child files. - - o rewrite's query limits which transactions can be rewritten; all are - printed. print --auto's query limits which transactions are printed. - - o rewrite applies rules specified on command line or in the journal. - print --auto applies rules specified in the journal. - - roi - roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return - on your investments. - - 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: - - o 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. - - o Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or con- - verges too slowly. - - Examples: - - o Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/invest- - ing/roi-unrealised.ledger - - o Cookbook > Return on Investment: https://hledger.org/roi.html - - 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'" - - 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. - - o "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 - - o "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 - - IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- - tial value, expressed in percentage of the initial value. - - However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of - growth is fixed over time. For more complex scenarios you need differ- - ent 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 percent- - age of your initial investment, and if you are adding to your invest- - ment, 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 "unreal- - ized 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: - - o Explanation of rate of return - - o Explanation of IRR - - o Explanation of TWR - - o Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - stats - 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 also supports output destination and output format selec- - tion. - - tags - tags - List the tags used in the journal, or their values. - - This command lists the tag names used in the journal, whether on trans- - actions, postings, or account declarations. - - With a TAGREGEX argument, only tag names matching this regular expres- - sion (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. - - test - 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). - - About add-on commands - Add-on commands are programs or scripts in your PATH - - o whose name starts with hledger- - - o whose name ends with a recognised file extension: .bat,.com,.exe, - .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none - - o and (on unix, mac) which are executable by the current user. - - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger library - functions that built-in commands use for command-line options, parsing - and reporting. Some experimental/example add-on scripts can be found - in the hledger repo's bin/ directory. - - 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 - -JOURNAL FORMAT - hledger's default file format, representing a General Journal. - - hledger's usual data source is a plain text file containing journal - entries in hledger journal format. This file represents a standard - accounting general journal. I use file names ending in .journal, but - that's not required. The journal file contains a number of transaction - entries, each describing a transfer of money (or any commodity) between - two or more named accounts, in a simple format readable by both hledger - and humans. - - hledger's journal format is a compatible subset, mostly, of ledger's - journal format, so hledger can work with compatible ledger journal - files as well. It's safe, and encouraged, to run both hledger and - ledger on the same journal file, eg to validate the results you're get- - ting. - - You can use hledger without learning any more about this file; just use - the add or web 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 configura- - tion at hledger.org for the full list. - - Here's a description of each part of the file format (and hledger's - data model). These are mostly in the order you'll use them, but in - some cases related concepts have been grouped together for easy refer- - ence, or linked before they are introduced, so feel free to skip over - anything that looks unnecessary right now. - - 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 sim- - ple date in column 0. This can be followed by any of the following - optional fields, separated by spaces: - - o a status character (empty, !, or *) - - o a code (any short number or text, enclosed in parentheses) - - o a description (any remaining text until end of line or a semicolon) - - o a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - - o 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 - - Dates - 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 cur- - rent transaction, the default year set with a default year 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.) - - Secondary dates - Real-life transactions sometimes involve more than one date - eg the - date you write a cheque, and the date it clears in your bank. When you - want to model this, for more accurate daily balances, you can specify - individual posting dates. - - Or, you can use the older secondary date feature (Ledger calls it aux- - iliary date or effective date). Note: we support this for compatibil- - ity, but I usually recommend avoiding this feature; posting dates are - almost always clearer and simpler. - - 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", as shown here: - - 2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking - - $ hledger register checking - 2010-02-23 movie ticket assets:checking $-10 $-10 - - $ hledger register checking --date2 - 2010-02-19 movie ticket assets:checking $-10 $-10 - - Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) - like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May - reports, and the deduction from checking should be reported on 6/1 for - easy bank reconciliation: - - 2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - - $ hledger -f t.j register food - 2015-05-30 expenses:food $10 $10 - - $ hledger -f t.j register checking - 2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. You can set the secondary date - similarly, with date2:DATE2. The date: or date2: tags must have a - valid simple date value if they are present, eg a date: tag with no - value is not allowed. - - Ledger's earlier, more compact bracketed date syntax is also supported: - [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any - square-bracketed sequence of the 0123456789/-.= characters in this way. - With this syntax, DATE infers its year from the transaction and DATE2 - infers its year from DATE. - - Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction - description or posting account name, separated from it by a space, - indicating one of three statuses: - - - mark status - ------------------ - unmarked - ! pending - * cleared - - When reporting, you can filter by status with the -U/--unmarked, - -P/--pending, and -C/--cleared flags; or the status:, status:!, and - status:* queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" state - is called "uncleared". As of hledger 1.3 we have renamed it to - unmarked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching pend- - ing, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with - real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle - transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to you. - Here's one suggestion: - - - status meaning - -------------------------------------------------------------------------- - uncleared recorded but not yet reconciled; needs review - pending tentatively reconciled (if needed, eg during a big reconcil- - iation) - cleared complete, reconciled as far as possible, and considered cor- - rect - - With this scheme, you would use -PC to see the current balance at your - bank, -U to see things which will probably hit your bank soon (like - uncashed checks), and no flags to see the most up-to-date state of your - finances. - - 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. - - Description - A transaction's description is the rest of the line following the date - and status mark (or until a comment begins). Sometimes called the - "narration" in traditional bookkeeping, it can be used for whatever you - wish, or left blank. Transaction descriptions can be queried, unlike - comments. - - Payee and note - You can optionally include a | (pipe) character in descriptions to sub- - divide 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. - - Comments - Lines in the journal beginning with a semicolon (;) or hash (#) or star - (*) are comments, and will be ignored. (Star comments cause org-mode - nodes to be ignored, allowing emacs users to fold and navigate their - journals with org-mode or orgstruct-mode.) - - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. - Transaction and posting comments must begin with a semicolon (;). - - Some examples: - - # a file comment - ; another file comment - * also a file comment, useful in org/orgstruct mode - - comment - A multiline file comment, which continues - until a line containing just "end comment" - (or end of file). - end comment - - 2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 - ; a file comment (because not indented) - - You can also comment larger regions of a file using comment and end - comment directives. - - Tags - Tags are a way to add extra labels or labelled data to postings and - transactions, which you can then search or pivot on. - - A simple tag is a word (which may contain hyphens) followed by a full - colon, written inside a transaction or posting comment line: - - 2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the - next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or new- - lines. Ending at commas means you can write multiple short tags on one - line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - o "a comment containing" is just comment text, not a tag - - o "tag1" is a tag with no value - - o "tag2" is another tag, whose value is "some value ..." - - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, third- - tag) and the posting has four (those plus posting-tag): - - 1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values - are simple strings. - - Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or - tab (2 or 4 spaces is common), followed by: - - o (optional) a status character (empty, !, or *), followed by a space - - o (required) an account name (any text, optionally containing single - spaces, until end of line or a double space) - - o (optional) two or more spaces or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are - being removed. - - The amounts within a transaction must always sum up to zero. As a con- - venience, one amount may be left blank; it will be inferred so as to - balance the transaction. - - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing spa- - ces. But if you accidentally leave only one space (or tab) before the - amount, the amount will be considered part of the account name. - - Virtual postings - A posting with a parenthesised 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 accounting, 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: - - 1/1 opening balances - (assets:checking) $1000 - (assets:savings) $2000 - - A posting with a bracketed 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: - - 1/1 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- not required to balance - - Ordinary non-parenthesised, non-bracketed postings are called real - postings. You can exclude virtual postings from reports with the - -R/--real flag or real:1 query. - - Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five top- - level accounts: assets, liabilities, revenue, expenses, and equity. - - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more - spaces (or newline). - - Account names can be aliased. - - Amounts - After the account name, there is usually an amount. (Important: - between account name and amount, there must be two or more spaces.) - - hledger's amount format is flexible, supporting several international - formats. Here are some examples. Amounts have a number (the "quan- - tity"): - - 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 com- - modity 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 - - 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 jour- - nal 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 detail below. - - 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 punctu- - ation), 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.) - - 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, in JOURNAL FORMAT -> Declaring commodities. - 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 - - - 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: - - o The commodity directive for that commodity (including the no-symbol - commodity), if any. - - o The amounts in that commodity seen in the journal's transactions. - (Posting amounts only; prices and periodic or auto rules are ignored, - currently.) - - o The built-in fallback style, which looks like this: $1000.00. (Sym- - bol on the left, period decimal mark, two decimal places.) - - A style is inferred from journal amounts as follows: - - o Use the general style (decimal mark, symbol placement) of the first - amount - - o Use the first-seen digit group style (digit group mark, digit group - sizes), if any - - o Use the maximum number of decimal places of all. - - Transaction price amounts don't affect the commodity display style - directly, but occasionally they can do so indirectly (eg when a post- - ing's amount is inferred using a transaction price). 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. - - 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"). (Guaranteed since hledger 1.17.1; in older versions - this could vary if hledger was built with Decimal < 0.5.1.) - - Transaction prices - Within a transaction, you can note an amount's price in another commod- - ity. This can be used to document the cost (in a purchase) or selling - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are - fixed at the time of the transaction, and do not change over time. See - also market prices, which represent prevailing exchange rates on a cer- - tain date. - - There are several ways to record a transaction price: - - 1. Write the price per unit, as @ UNITPRICE after the amount: - - 2009/1/1 - assets:euros EUR100 @ $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 EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, and - let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros EUR100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati- - bility with Ledger journals (Virtual posting costs), and is equiva- - lent to 1 in hledger. - - 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger, - this is equivalent to 2. - - Use the -B/--cost flag to convert amounts to their transaction price's - commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). - Eg here is how -B affects the balance report for the example above: - - $ hledger bal -N --flat - $-135 assets:dollars - EUR100 assets:euros - $ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last - amount. So if example 3's postings are reversed, while the transaction - is equivalent, -B shows something different: - - 2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros EUR100 ; for 100 euros - - $ hledger bal -N --flat -B - EUR-100 assets:dollars # <- the dollars' selling price - EUR100 assets:euros - - Lot prices, lot dates - Ledger allows another kind of price, lot price (four variants: {UNIT- - PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), - and/or a lot date ([DATE]) to be specified. These are normally used to - select a lot when selling investments. hledger will parse these, for - compatibility with Ledger journals, but currently ignores them. A - transaction price, lot price and/or lot date may appear in any order, - after the posting amount and before the balance assertion if any. - - 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 pro- - tect 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, below). - - Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- - ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- - ings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder 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. - - 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. - - 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 bal- - ance from earlier files. This can be useful when you do not want prob- - lems 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. - - 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 1EUR - b $-1 - c -1EUR - - 2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1EUR - b 0 == $-1 - c 0 == -1EUR - - 2013/1/3 ; This assertion fails as 'a' also contains 1EUR - 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 1EUR - b - - 2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1EUR - - Assertions and prices - Balance assertions ignore transaction prices, and should normally be - written without one: - - 2019/1/1 - (a) $1 @ EUR1 = $1 - - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- - ments do use them (see below). - - Assertions and subaccounts - 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 - - 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. - - 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: - - o assert the balance calculated with --auto, and always use --auto with - that file - - o or assert the balance calculated without --auto, and never use --auto - with that file - - o or avoid balance assertions on accounts affected by auto postings (or - avoid auto postings entirely). - - Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- - tions. Balance assertion failure messages show exact amounts. - - Balance assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when - setting opening balances: - - ; starting a new journal, set asset account balances - 2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - - ; no cash left; update balance, record any untracked spending as a generic expense - 2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- - ment). Note that using balance assignments makes your journal a little - less explicit; to know the exact amount posted, you have to run hledger - or do the calculations yourself, instead of just reading it. - - Balance assignments and prices - A transaction price in a balance assignment will cause the calculated - amount to have that price attached: - - 2019/1/1 - (a) = $1 @ EUR2 - - $ hledger print --explicit - 2019-01-01 - (a) $1 @ EUR2 = $1 @ EUR2 - - 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: - - o subdirective - Some directives support subdirectives, written - indented below the parent directive. - - o decimal mark - The character to interpret as a decimal mark (period - or comma) when parsing amounts of a commodity. - - o display style - How to display amounts of a commodity in output: sym- - bol side and spacing, digit groups, decimal mark, and number of deci- - mal places. - - Directives are not required when starting out with hledger, but you - will probably add some as your needs grow. Here is an overview of - directives by purpose: - - - purpose directives command line - options with sim- - ilar effect - ----------------------------------------------------------------------------- - READING/GENERATING DATA: - Declare a commodity's or file's commodity, D, decimal- - decimal mark to help parse mark - amounts accurately - Apply changes to the data while alias, apply account, --alias - parsing comment, D, Y - Inline extra data files include multiple - -f/--file's - Generate extra transactions or ~ - budget goals - Generate extra postings = - CHECKING FOR ERRORS: - Define valid entities to allow account, commodity, - stricter error checking payee - DISPLAYING REPORTS: - Declare accounts' display order account - and accounting type - Declare commodity display commodity, D -c/--commodity- - styles style - - And here are all the directives and their precise effects: - - - direc- effects ends - tive at - file - end? - ---------------------------------------------------------------------------------- - account Declares an account, for checking all entries in all files; - and its display order and type, for reports. Subdirectives: - any text, ignored. - alias Rewrites account names, in following entries until end of Y - current file or end aliases. - apply Prepends a common parent account to all account names, in Y - account following entries until end of current file or end apply - account. - comment Ignores part of the journal file, until end of current file Y - or end comment. - commod- Declares a commodity, for checking all entries in all files; N, Y - ity the decimal mark for parsing amounts of this commodity, for - following entries until end of current file; and its display - style, for reports. Takes precedence over D. Subdirectives: - format (alternate syntax). - - - - - D Sets a default commodity to use for no-symbol amounts, and Y - its decimal mark for parsing amounts of this commodity in - following entries until end of current file; and its display - style, for reports. - deci- Declares the decimal mark, for parsing amounts of all com- Y - mal- modities in following entries until next decimal-mark or end - mark of current file. Included files can override. Takes prece- - dence over commodity and D. - include Includes entries and directives from another file, as if they - were written inline. - payee Declares a payee name, for checking all entries in all files. - P Declares a market price for a commodity on some date, for - valuation reports. - Y Declares a year for yearless dates, for following entries Y - until end of current file. - ~ Declares a periodic transaction rule that generates future - (tilde) transactions with --forecast and budget goals with balance - --budget. - = Declares an auto posting rule that generates extra postings partly - (equals) on matched transactions with --auto, in current, parent, and - child files (but not sibling files, see #1212). - - 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 sta- - ble 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 direc- - tives do not affect parent or sibling files (see below). - - Comment blocks - A line containing just comment starts a commented region of the file, - and a line containing just end comment (or the end of the current file) - ends it. See also comments. - - Including other files - You can pull in the content of additional files by writing an include - 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, overrid- - ing the file extension (as described in hledger.1 -> Input files): - include timedot:~/notes/2020*.md. - - Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. - Eg: - - Y2009 ; set default year to 2009 - - 12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - - Y2010 ; change default year to 2010 - - 2009/1/30 ; specifies the year, not affected - expenses 1 - assets - - 1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Declaring payees - The payee 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 - - Declaring the decimal mark - 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). - - Declaring commodities - 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 Com- - modity 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 dec- - imal 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 subdirec- - tive, 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 - - 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. - - 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 cur- - rently 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. - - Default commodity - The D directive sets a default commodity, to be used for any subsequent - commodityless amounts (ie, plain numbers) seen while parsing the jour- - nal. 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). - - The syntax is D AMOUNT. As with commodity, 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 - - If both commodity and D directives are found for a commodity, commodity - takes precedence for setting decimal mark and display style. - - If you are using D and also checking commodities, you will need to add - a commodity directive similar to the D. (The hledger check commodities - command expects commodity directives, and ignores D). - - Declaring market prices - The P directive declares a market price, which is an exchange rate - between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, - cryptocurrency exchange, or the 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 EUR $1.35 - - # and $1.40 from 2010-01-01 onward: - P 2010-01-01 EUR $1.40 - - The -V, -X and --value flags use these market prices to show amount - values in another commodity. See Valuation. - - Declaring accounts - account directives can be used to declare accounts (ie, the places that - amounts are transferred from and to). Though not required, these dec- - larations can provide several benefits: - - o They can document your intended chart of accounts, providing a refer- - ence. - - o They control account display order in reports, allowing non-alpha- - betic sorting (eg Revenues to appear above Expenses). - - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and - incomestatement. - - o They can store other account information, as comments or as tags - which can be used to filter reports. - - o They help with account name completion (in hledger add, hledger-web, - hledger-iadd, ledger-mode, etc.) - - o In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - - The simplest form is just the word account followed by a hledger-style - account name, eg this account directive declares the assets:bank:check- - ing account: - - account assets:bank:checking - - Account error checking - By default, accounts come into existence when a transaction references - them by name. 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 - the error later, as an extra account in balance reports, or an incor- - rect 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: - - o The declaration is case-sensitive; transactions must use the correct - account name capitalisation. - - o The account directive's scope is "whole file and below" (see direc- - tives). 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. - - o Accounts can only be declared in journal files (but will affect - included files in other formats). - - o It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - Account comments - Comments, beginning with a semicolon, can be added: - - o on the same line, after two or more spaces (because ; is allowed in - account names) - - o on the next lines, indented - - An example of both: - - account assets:bank:checking ; same-line comment, note 2+ spaces required before ; - ; next-line comment - ; some tags, type:A, acctnum:12345 - - Compatibility note: same-line comments are not supported by Ledger or - hledger <1.13. - - Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just - for compatibility.: - - account assets:bank:checking - format blah blah ; <- subdirective, ignored - - Here is the full syntax of account directives: - - account ACCTNAME [;type:ACCTTYPE] [COMMENT] - [;COMMENTS] - [LEDGER-STYLE SUBDIRECTIVES, IGNORED] - - 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: - - o A or Asset (things you own) - - o L or Liability (things you owe) - - o E or Equity (investment/ownership; balanced counterpart of assets & - liabilities) - - o R or Revenue (what you received money from, AKA income; technically - part of Equity) - - o X or Expense (what you spend money on; technically part of Equity) - - or, it can be (these are used less often): - - o C or Cash (a subtype of Asset, indicating liquid assets for the cash- - flow report) - - o V or Conversion (a subtype of Equity, for conversions (see CONVERSION - & COST).) - - 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. - - o 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. Note the Cash regexp changed - in hledger 1.24.99.2. - - 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 - - o If you declare any account types, it's a good idea to declare an - account for each of them, because a mixture of declared and name- - inferred types can disrupt certain reports. - - o Certain uses of account aliases can disrupt account types. See - Rewriting accounts > Aliases and account types. - - o 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. - - o For troubleshooting, you can list accounts and their types with: - - $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] - - Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web - sidebar. By default accounts are listed in alphabetical order. But if - you have these account directives in the journal: - - account assets - account liabilities - account equity - account revenues - account expenses - - you'll see those accounts displayed in declaration order, not alphabet- - ically: - - $ hledger accounts -1 - assets - liabilities - equity - revenues - expenses - - Undeclared accounts, if any, are displayed last, in alphabetical order. - - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, - 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: - - o you will sometimes declare parent accounts (eg account other above) - that you don't intend to post to, just to customize their display - order - - o sibling accounts stay together (you couldn't display x:y in between - a:b and a:c). - - Rewriting accounts - You can define account alias rules which rewrite your account names, or - parts of them, before generating reports. This can be useful for: - - o expanding shorthand account names to their full form, allowing easier - data entry and a less verbose journal - - o adapting old journals to your current chart of accounts - - o experimenting with new account organisations, like a new hierarchy - - o combining two accounts into one, eg to see their sum or difference on - one line - - o 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 cor- - rectly, but you can also generate invalid account names with them; more - on this below. - - See also Rewrite account names. - - Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its - included files (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. Sub- - accounts are also affected. Eg: - - alias checking = assets:bank:wells fargo:checking - ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - Regex aliases - There is also a more powerful variant that uses a regular expression, - 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. - - 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: - - o the nearest alias declaration before/above the entry is applied first - - o the next alias before/above that will be be applied next, and so on - - o aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- - pendent 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. - - 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 - - end aliases - You can clear (forget) all currently defined aliases (seen in the jour- - nal so far, or defined on the command line) with this directive: - - end aliases - - 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 exam- - ple, 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 - - 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, renam- - ing 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 - - Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and - end apply account directives like so: - - apply account home - - 2010/1/1 - food $10 - cash - - end apply account - - which is equivalent to: - - 2010/01/01 - home:food $10 - home:cash $-10 - - If end apply account is omitted, the effect lasts to the end of the - file. Included files are also affected, eg: - - apply account business - include biz.journal - end apply account - apply account personal - include personal.journal - - Prior to hledger 1.0, legacy account and end spellings were also sup- - ported. - - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent - account. - - Periodic transactions - Periodic transaction rules describe transactions that recur. They - allow hledger to generate temporary future transactions to help with - forecasting, so you don't have to write out each one in the journal, - and it's easy to try out different forecasts. - - 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-fore- - casted 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. - - Periodic transaction rules also have a second meaning: they are used to - define budget goals, shown in budget reports. - - 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.): - - ~ monthly - expenses:rent $2000 - assets:bank:checking - - There is an additional constraint on the period expression: the start - date must fall on a natural boundary of the interval. Eg monthly from - 2018/1/1 is valid, but monthly from 2018/1/15 is not. - - 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. - - 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 acciden- - tally 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, - - o Do write two spaces between your period expression and your transac- - tion description, if any. - - o Don't accidentally write two spaces in the middle of your period - expression. - - Forecasting with periodic transactions - The --forecast flag activates any periodic transaction rules in the - journal. These will generate temporary additional transactions, usu- - ally 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-transac- - tion:, which you can use to reliably match transactions generated "just - now" (rather than printed 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: - - o the start date provided within --forecast's argument, if any - - o otherwise, the later of - - o the report start date, if specified (with -b/-p/date:) - - o the day after the latest ordinary transaction in the journal, if - any - - o otherwise today. - - It ends on: - - o the end date provided within --forecast's argument, if any - - o otherwise, the report end date, if specified (with -e/-p/date:) - - o 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: - - o 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. - - o 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: - - o You must use = between flag and argument; a space won't work. - - o The period expression can specify the forecast period's start date, - end date, or both. See also Report start & end date. - - o The period expression should not specify a report interval. (Each - periodic transaction rule specifies its own interval.) - - Some examples: --forecast=202001-202004, --forecast=jan-, --fore- - cast=2021. - - Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- - pared in budget reports. - - See also: Budgeting and Forecasting. - - - Auto postings - "Automated postings" or "auto postings" are extra postings which get - added automatically to transactions which match certain queries, - defined by "auto posting rules", when you use the --auto flag. - - 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 match- - ing), followed by a query (which matches existing postings), and each - "posting" line describes a posting to be generated, and the posting - amounts can be: - - o a normal amount with a commodity symbol, eg $2. This will be used - as-is. - - o a number, eg 2. The commodity symbol (if any) from the matched post- - ing will be added to this. - - o 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. - - o 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 - - 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). - - 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. - - Auto postings and transaction balancing / inferred amounts / balance asser- - tions - Currently, auto postings are added: - - o after missing amounts are inferred, and transactions are checked for - balancedness, - - o but before balance assertions are checked. - - Note this means that journal entries must be balanced both before and - after auto postings are added. This changed in hledger 1.12+; see #893 - for background. - - 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. - - Auto posting tags - Automated postings will have some extra tags: - - o generated-posting:= QUERY - shows this was generated by an auto post- - ing rule, and the query - - o _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: - - o modified: - this transaction was modified - - o _modified: - a hidden tag not appearing in the comment; this transac- - tion was modified "just now". - -CSV FORMAT - How hledger reads CSV data, and the CSV rules file format. - - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records as if they were journal - files, automatically converting each CSV record into a transaction. - - (To learn about writing CSV, see CSV output.) - - We describe each CSV file's format with a corresponding rules file. By - default this is named like the CSV file with a .rules extension added. - Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the - same directory as FILE.csv. You can specify a different rules file - with the --rules-file option. If a rules file is not found, hledger - will create a sample rules file, which you'll need to adjust. - - This file contains rules describing the CSV data (header line, fields - layout, date format etc.), and how to construct hledger journal entries - (transactions) from it. Often there will also be a list of conditional - rules for categorising transactions based on their descriptions. - Here's an overview of the CSV rules; these are described more fully - below, after the examples: - - - skip skip one or more header lines or matched CSV - records - fields list name CSV fields, assign them to hledger - fields - field assignment assign a value to one hledger field, with - interpolation - Field names hledger field names, used in the fields list - and field assignments - separator a custom field separator - if block apply some rules to CSV records matched by - patterns - if table apply some rules to CSV records matched by - patterns, alternate syntax - end skip the remaining CSV records - date-format how to parse dates in CSV records - decimal-mark the decimal mark used in CSV amounts, if - ambiguous - newest-first disambiguate record order when there's only - one date - include inline another CSV rules file - balance-type choose which type of balance assignments to - use - - Note, for best error messages when reading CSV files, use a .csv, .tsv - or .ssv file extension or file prefix - see File Extension below. - - There's an introductory Convert CSV files tutorial on hledger.org. - - Examples - Here are some sample hledger CSV rules files. See also the full col- - lection at: - https://github.com/simonmichael/hledger/tree/master/examples/csv - - Basic - 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 - - Default account names are chosen, since we didn't set them. - - 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 neces- - sary 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 read- - ing directly from CSV, but they will be checked if these entries are - imported into a journal file. - - Amazon - Here we convert amazon.com order history, and use an if block to gener- - ate 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 - - 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: - - CSV rules - The following kinds of rule can appear in the rules file, in any order. - Blank lines and lines beginning with # or ; are ignored. - - skip - skip N - - The word "skip" followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines preceding the CSV data. - (Empty/blank lines are skipped automatically.) You'll need this when- - ever your CSV data contains header lines. - - It also has a second purpose: it can be used inside if blocks to ignore - certain CSV records (described below). - - fields list - fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word "fields" followed by comma-separated field - names) is the quick way to assign CSV field values to hledger fields. - (The other way is field assignments, see below.) A fields list does - does two things: - - 1. It names the CSV fields. This is optional, but can be convenient - later for interpolating them. - - 2. Whenever you use a standard hledger field name (defined below), the - CSV value is assigned to that part of the hledger 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 - - Tips: - - o The fields list always use commas, even if your CSV data uses another - separator character. - - o Currently there must be least two items in the list (at least one - comma). - - o Field names may not contain spaces. Spaces before/after field names - are optional. - - o Field names may contain _ (underscore) or - (hyphen). - - o If the CSV contains column headings, it's a good idea to use these, - suitably modified, as the basis for your field names (eg lower-cased, - with underscores instead of spaces). - - o If some heading names match standard hledger fields, but you don't - want to set the hledger fields directly, alter those names, eg by - appending an underscore. - - o Fields you don't care about can be given a dummy name (eg: _ ), or no - name. - - field assignment - HLEDGERFIELDNAME 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 inter- - polate CSV fields, referenced by their 1-based position in the CSV - record (%N), or by the name they were given in the fields list (%CSV- - FIELDNAME). - - 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: - - o Interpolation strips outer whitespace (so a CSV value like " 1 " - becomes 1 when interpolated) (#1051). - - o Interpolations always refer to a CSV field - you can't interpolate a - hledger field. (See Referencing other fields below). - - Field names - Here are the standard hledger field (and pseudo-field) names, which you - can use in a fields list and in field assignments. For more about the - transaction parts they refer to, see Transactions. - - date field - Assigning to date sets the transaction date. - - date2 field - date2 sets the transaction's secondary date, if any. - - status field - status sets the transaction's status, if any. - - code field - code sets the transaction's code, if any. - - description field - description sets the transaction's description, if any. - - comment field - comment sets the transaction's comment, if any. - - commentN, where N is a number, sets the Nth posting's comment. - - Tips: - - o You can assign multi-line comments by writing literal \n in the code. - A comment starting with \n will begin on a new line. - - o Comments can contain tags, as usual. - - 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, and in conditional blocks. - - 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"). - - amount field - 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. - - amountN-in and amountN-out can be used instead, if the CSV uses sepa- - rate fields for debits and credits (inflows and outflows). hledger - assumes both of these CSV fields are unsigned, and will automatically - negate the "-out" value. If they are signed, see "Setting amounts" - below. - - amount, or amount-in and amount-out are a legacy mode, to keep pre- - hledger-1.17 CSV rules files working (and for occasional convenience). - They are suitable only for two-posting transactions; they set both - posting 1's and posting 2's amount. Posting 2's amount will be - negated, and also converted to cost if there's a transaction price. - - If you have an existing rules file using the unnumbered form, you might - want to use the numbered form in certain conditional blocks, without - having to update and retest all the old rules. To facilitate this, - posting 1 ignores amount/amount-in/amount-out if any of - amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them - if any of amount2/amount2-in/amount2-out are assigned, avoiding con- - flicts. - - 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. - - 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. - - separator - You can use the separator rule to read other kinds of character-sepa- - rated 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 automat- - ically, and you won't need this rule. - - if block - if MATCHER - RULE - - if - MATCHER - MATCHER - MATCHER - RULE - RULE - - Conditional blocks ("if blocks") are a block of rules that are applied - only to CSV records which match certain patterns. They are often used - for customising account names based on transaction descriptions. - - Matching the whole record - Each MATCHER can be a record matcher, which looks like this: - - REGEX - - REGEX is a case-insensitive regular expression that tries to match any- - where within the CSV record. It is a POSIX ERE (extended regular - expression) that also supports GNU word boundaries (\b, \B, \<, \>), - and nothing else. If you have trouble, be sure to check our doc: - https://hledger.org/hledger.html#regular-expressions - - Important note: the record that is matched is not the original record, - but a synthetic one, with any enclosing double quotes (but not enclos- - ing whitespace) removed, and always comma-separated (which means that a - field containing a comma will appear like two fields). Eg, if the - original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will - actually see 2020-01-01,Acme, Inc., 1,000). - - Matching individual fields - Or, MATCHER can be a field matcher, like this: - - %CSVFIELD REGEX - - which matches just the content of a particular CSV field. CSVFIELD is - a percent sign followed by the field's name or column number, like - %date or %1. - - Combining matchers - A single matcher can be written on the same line as the "if"; or multi- - ple matchers can be written on the following lines, non-indented. Mul- - tiple matchers are OR'd (any one of them can match), unless one begins - with an & symbol, in which case it is AND'ed with the previous matcher. - - if - MATCHER - & MATCHER - RULE - - Rules applied on successful match - After the patterns there should be one or more rules to apply, all - indented by at least one space. Three kinds of rule are allowed in - conditional blocks: - - o field assignments (to set a hledger field) - - o skip (to skip the matched CSV record) - - o end (to skip all remaining CSV records). - - Examples: - - # if the CSV record contains "groceries", set account2 to "expenses:groceries" - if groceries - account2 expenses:groceries - - # if the CSV record contains any of these patterns, set account2 and comment as shown - if - monthly service fee - atm transaction fee - banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - if table - if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn - MATCHER1,VALUE11,VALUE12,...,VALUE1n - MATCHER2,VALUE21,VALUE22,...,VALUE2n - MATCHER3,VALUE31,VALUE32,...,VALUE3n - - - Conditional tables ("if tables") are a different syntax to specify - field assignments that will be applied only to CSV records which match - certain patterns. - - MATCHER could be either field or record matcher, as described above. - When MATCHER matches, values from that row would be assigned to the CSV - fields named on the if line, in the same order. - - Therefore if table is exactly equivalent to a sequence of of if blocks: - - if MATCHER1 - CSVFIELDNAME1 VALUE11 - CSVFIELDNAME2 VALUE12 - ... - CSVFIELDNAMEn VALUE1n - - if MATCHER2 - CSVFIELDNAME1 VALUE21 - CSVFIELDNAME2 VALUE22 - ... - CSVFIELDNAMEn VALUE2n - - if MATCHER3 - CSVFIELDNAME1 VALUE31 - CSVFIELDNAME2 VALUE32 - ... - CSVFIELDNAMEn VALUE3n - - Each line starting with MATCHER should contain enough (possibly empty) - values for all the listed fields. - - Rules would be checked and applied in the order they are listed in the - table and, like with if blocks, later rules (in the same or another ta- - ble) or if blocks could override the effect of any rule. - - Instead of ',' you can use a variety of other non-alphanumeric charac- - ters as a separator. First character after if is taken to be the sepa- - rator for the rest of the table. It is the responsibility of the user - to ensure that separator does not occur inside MATCHERs and values - - there is no way to escape separator. - - 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 - - end - This rule can be used inside if blocks (only), to make hledger stop - reading this CSV file and move on to the next input file, or to command - execution. Eg: - - # ignore everything following the first empty record - if ,,,, - end - - 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 date - parsing pattern, which 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 - - For the supported strptime syntax, see: - https://hackage.haskell.org/package/time/docs/Data-Time-For- - mat.html#v:formatTime - - Note that although you can parse date-times which include a time zone, - that time zone is ignored; it will not change the date that is parsed. - This means when reading CSV data with times not in your local time - zone, dates can be "off by one". - - 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. - - newest-first - hledger always sorts the generated transactions by date. Transactions - on the same date should appear in the same order as their CSV records, - as hledger can usually auto-detect whether the CSV's normal order is - oldest first or newest first. But if all of the following are true: - - o the CSV might sometimes contain just one day of data (all records - having the same date) - - o the CSV records are normally in reverse chronological order (newest - at the top) - - o and you care about preserving the order of same-day transactions - - then, you should add the newest-first rule as a hint. Eg: - - # tell hledger explicitly that the CSV is normally newest first - newest-first - - 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 - - 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 - - Tips - 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. - - Valid CSV - hledger accepts CSV conforming to RFC 4180. When CSV values are - enclosed in quotes, note: - - o they must be double quotes (not single quotes) - - o spaces outside the quotes are not allowed - - File Extension - To help hledger identify the format and show the right error messages, - CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv - filename extension. Or, the file path should be prefixed with csv:, - ssv: or tsv:. Eg: - - $ hledger -f foo.ssv print - - or: - - $ cat foo | hledger -f ssv:- foo - - You can override the file extension with a separator rule if needed. - See also: Input files in the hledger manual. - - 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. - - Valid transactions - After reading a CSV file, hledger post-processes and validates the gen- - erated 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 - - 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: - - o https://hledger.org/cookbook.html#setups-and-workflows - - o https://plaintextaccounting.org -> data import/conversion - - Setting amounts - Some tips on using the amount-setting rules discussed above. - - Here are the ways to set a posting's amount: - - 1. If the CSV has a single amount field: - Assign (via a fields list or a field assignment) to amountN. This sets - the Nth posting's amount. N is usually 1 or 2 but can go up to 99. - - 2. If the CSV has separate amount fields for debit & credit (in & out): - - a. If both fields are unsigned: - Assign to amountN-in and amountN-out. This sets posting N's amount - to whichever of these has a non-zero value, and negates the "-out" - value. - - b. If either field is signed (can contain a minus sign): - Use a conditional rule to flip the sign (of non-empty values). - Since hledger always negates amountN-out, if it was already nega- - tive, we must undo that by negating once more (but only if the - field is non-empty): - - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. If both fields, or neither field, can contain a non-zero value: - hledger normally expects exactly one of the fields to have a non- - zero value. Eg, the amountN-in/amountN-out rules would reject - value pairs like these: - - "", "" - "0", "0" - "1", "none" - - So, use smarter conditional rules to set the amount from the appro- - priate field. Eg, these rules would make it use only the value - containing non-zero digits, handling the above: - - 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: - Assign to amount (or to amount-in and amount-out). (This is the legacy - numberless syntax, which sets amount1 and amount2 and converts amount2 - to cost.) - - 4. If the CSV has the balance instead of the transaction amount: - Assign to balanceN, which sets posting N's amount indirectly via a bal- - ance assignment. (Old syntax: balance, equivalent to balance1.) - - o If hledger guesses the wrong default account name: - When setting the amount via balance assertion, hledger may guess - the wrong default account name. So, set the account name explic- - itly, eg: - - fields date, description, balance1 - account1 assets:checking - - Amount signs - There is some special handling for amount signs, to simplify parsing - and sign-flipping: - - o If an amount value begins with a plus sign: - that will be removed: +AMT becomes AMT - - o If an amount value is parenthesised: - it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - - o 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 - - o If an amount value contains just a sign (or just a set of parenthe- - ses): - that is removed, making it an empty value. "+" or "-" or "()" becomes - "". - - 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. - - 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 deci- - mal 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). - - 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 lit- - eral "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 - - How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need - to). First, - - o 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: - - o skip (at top level) - - o date-format - - o newest-first - - o fields - names the CSV fields, optionally sets up initial assignments - to hledger fields - - Then for each CSV record in turn: - - o 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. - - o 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. - - o compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELDNAME references), or a - default - - o generate a synthetic hledger transaction 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. - -TIMECLOCK FORMAT - 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). - - i 2015/03/30 09:00:00 some:account name optional description after two spaces - o 2015/03/30 09:20:00 - i 2015/03/31 22:21:45 another account - o 2015/04/01 02:00:34 - - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For - the above time log, hledger print generates these journal entries: - - $ hledger -f t.timeclock print - 2015-03-30 * optional description after two spaces - (some:account name) 0.33h - - 2015-03-31 * 22:21-23:59 - (another account) 1.64h - - 2015-04-01 * 00:00-02:00 - (another account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - - $ hledger -f sample.timeclock balance # current time balances - $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 - $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - o use emacs and the built-in timeclock.el, or the extended timeclock- - x.el and perhaps the extras in ledgerutils.el - - o at the command line, use these bash aliases: shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" - - o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 - executable renamed. - -TIMEDOT FORMAT - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is - - o convenient for quick, approximate, and retroactive time logging - - o 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: - - o 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 - - o a common transaction description for this day - - o a common transaction comment for this day, after a semicolon (;). - - After the date line are zero or more optionally-indented time transac- - tion lines, consisting of: - - o an account name - any word or phrase, usually a hledger-style account - name. - - o two or more spaces - a field separator, required if there is an - amount (as in journal format). - - o a timedot amount - dots representing quarter hours, or a number rep- - resenting hours. - - o an optional comment beginning with semicolon. This is ignored. - - In more detail, timedot amounts can be: - - o dots: zero or more period characters, each representing one quarter- - hour. Spaces are ignored and can be used for grouping. Eg: .... .. - - o a number, representing hours. Eg: 1.5 - - o 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.: - - o Lines beginning with # or ;, and blank lines, are ignored. - - o Lines not ending with a double-space and amount are parsed as trans- - actions with zero amount. (Most hledger reports hide these by - default; add -E to see them.) - - o One or more stars (*) followed by a space, at the start of a line, is - ignored. So date lines or time transaction lines can also be Org- - mode headlines. - - o All Org-mode headlines before the first date line are ignored. - - 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. - -COMMON TASKS - Here are some quick examples of how to do some basic tasks with - hledger. For more details, see the reference section below, the - hledger_journal(5) manual, or the more extensive docs at - https://hledger.org. - - Getting help - $ hledger # show available commands - $ hledger --help # show common options - $ hledger CMD --help # show common and command options, and command help - $ hledger help # show available manuals/topics - $ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) - $ hledger help journal -m # show the journal topic, as a man page scrolled to that section - $ hledger help --help # show more detailed help for the help command - - Find more docs, chat, mail list, reddit, issue tracker: - https://hledger.org/support.html-feedback - - Constructing command lines - hledger has an extensive and powerful command line interface. We - strive to keep it simple and ergonomic, but you may run into one of the - confusing real world details described in OPTIONS, below. If that hap- - pens, here are some tips that may help: - - o command-specific options must go after the command (it's fine to put - all options there) (hledger CMD OPTS ARGS) - - o running add-on executables directly simplifies command line parsing - (hledger-ui OPTS ARGS) - - o enclose "problematic" args in single quotes - - o if needed, also add a backslash to hide regular expression metachar- - acters from the shell - - o to see how a misbehaving command is being parsed, add --debug=2. - - 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 () - - 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 bal- - ances on this date. Here are two ways to do it: - - o 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. - - o 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 - - 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 - - Reconciling - Periodically you should reconcile - compare your hledger-reported bal- - ances 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 dis- - crepancies. - - 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 check- - ing -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 trans- - action 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 --reg- - ister 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 com- - mit: - - $ git commit -m 'txns' 2020.journal - - 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 --flat -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 --flat -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 **** - - 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. - -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 file format - differences. - - On large data files, hledger is slower and uses more memory than - Ledger. - -TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug - tracker): - - Successfully installed, but "No command 'hledger' found" - stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, - that is ~/.local/bin and ~/.cabal/bin respectively. - - I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may - need to use export. Here's an explanation. - - Getting errors like "Illegal byte sequence" or "Invalid or incomplete - multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- - ment (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 sup- - ports 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 differ- - ence 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 - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2020 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), ledger(1) - - - -hledger-1.26 June 2022 HLEDGER(1) + manual is for hledger 1.26.1. + +SYNOPSIS + hledger + + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + +DESCRIPTION + hledger is a reliable, cross-platform set of programs for tracking + money, time, or any other commodity, using double-entry accounting and + a simple, editable file format. hledger is inspired by and largely + compatible with ledger(1). + + The basic function of the hledger CLI is to read a plain text file + describing financial transactions (in accounting terms, a general jour- + nal) and print useful reports on standard output, or export them as + CSV. hledger can also read some other file formats such as CSV files, + translating them to journal format. Additionally, hledger lists other + hledger-* executables found in the user's $PATH and can invoke them as + subcommands. + + hledger reads data from one or more files in hledger journal, time- + clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must + be a real environment variable, not a shell variable. You can specify + standard input with -f-. + + Transactions are dated movements of money between two (or more) named + accounts, and are recorded with journal entries like this: + + 2015/10/16 bought food + expenses:food $10 + assets:cash + + Most users use a text editor to edit the journal, usually with an edi- + tor mode such as ledger-mode for added convenience. hledger's interac- + tive add command is another way to record new transactions. hledger + never changes existing transactions. + + To get started, you can either save some entries like the above in + ~/.hledger.journal, or run hledger add and follow the prompts. Then + try some commands like hledger print or hledger balance. Run hledger + with no arguments for a list of commands. + +OPTIONS + General options + To see general usage help, including general options which are sup- + ported by most hledger commands, run hledger -h. + + General help options: + + -h --help + show general 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 fol- + lowing 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 com- + modities + + -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 charac- + ters. 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. + + 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. + + 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 noth- + ing). 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. + + Special characters + 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 dou- + ble 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. + + 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:\\$ + + 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 argu- + ments 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:\\$ + + 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: + + o an @argumentfile + + o hledger-ui's filter field + + o hledger-web's search form + + o GHCI's prompt (used by developers). + + Unicode characters + hledger is expected to handle non-ascii characters correctly: + + o 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.) + + o 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: + + o 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 Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- + grams). + + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode + + o the terminal must be using a font which includes the required unicode + glyphs + + o the terminal should be configured to display wide characters as dou- + ble width (for report alignment) + + o 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 stan- + dard 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). + + Regular expressions + hledger uses regular expressions in a number of places: + + o query terms, on the command line and in the hledger-web search form: + REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX + + o CSV rules conditional blocks: if REGEX ... + + o account alias directives and options: alias /REGEX/ = REPLACEMENT, + --alias /REGEX/=REPLACEMENT + + hledger's regular expressions come from the regex-tdfa library. 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: + + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + these are not required. + + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write cur:\$. + + o On the command line, some metacharacters like $ have a special mean- + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. + +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\MyUser- + Name\.hledger.journal. You can change this by running a command like + this in a powershell window: + + > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" + + (Let us know if you need to be an Administrator, and if this persists + across a reboot.) + + 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. + +DATA FILES + hledger reads transactions from one or more data files. The default + data file is $HOME/.hledger.journal (or on Windows, something like + C:/Users/USER/.hledger.journal). + + You can override this with the $LEDGER_FILE environment variable: + + $ setenv LEDGER_FILE ~/finance/2016.journal + $ hledger stats + + or with 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- + + 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 exten- + sions: + ----------------------------------------------------------------------------- + journal hledger journal files and some Ledger .journal .j .hledger + journals, for transactions .ledger + time- timeclock files, for precise time log- .timeclock + clock ging + 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 their own sections, 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:- + + Multiple files + You can specify multiple -f options, to read multiple files as one big + journal. There are some limitations with this: + + o most directives do not affect sibling files + + o balance assertions will not see any account balances from previous + files + + If you need either of those things, you can + + o use a single parent file which includes the others + + o or concatenate the files into one before reading, eg: cat a.journal + b.journal | hledger -f- CMD. + + Strict mode + hledger checks input files for valid data. By default, the most impor- + tant errors are detected, while still accepting easy journal files + without a lot of declarations: + + o Are the input files parseable, with valid syntax ? + + o Are all transactions balanced ? + + o Do all balance assertions pass ? + + With the -s/--strict flag, additional checks are performed: + + o Are all accounts posted to, declared with an account directive ? + (Account error checking) + + o Are all commodities declared with a commodity directive ? (Commodity + error checking) + + o Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks -- the ones + listed above and some more. + +TIME PERIODS + Smart dates + hledger's user interfaces accept a flexible "smart date" syntax. Smart + dates allow some english words, can be relative to today's date, and + can have less-significant date parts omitted (defaulting to 1). + + Examples: + + + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 + 2004 start of year + 2004/10 start of month + 10/1 month and day in current year + 21 day in current month + october, oct start of month in current year + yesterday, today, tomor- -1, 0, 1 days from today + row + last/this/next -1, 0, 1 periods from the current period + day/week/month/quar- + ter/year + in n n periods from the current period + days/weeks/months/quar- + ters/years + n n periods from the current period + days/weeks/months/quar- + ters/years ahead + n -n periods from the current period + days/weeks/months/quar- + ters/years ago + 20181201 8 digit YYYYMMDD with valid year month and day + 201812 6 digit YYYYMM with valid year and month + + Counterexamples - malformed digit sequences might give surprising + results: + + + 201813 6 digits with an invalid month is parsed as start of + 6-digit year + 20181301 8 digits with an invalid month is parsed as start of + 8-digit year + 20181232 8 digits with an invalid day gives an error + 201801012 9+ digits beginning with a valid YYYYMMDD gives an error + + Note "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; those are not affected by --today.) + + + Report start & end date + By default, most hledger reports will show the full span of time repre- + sented by the journal data. 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. + + Some notes: + + o End dates are exclusive, as in Ledger, so you should write the date + after the last day you want to see in the report. + + o As noted in reporting options: among start/end dates specified with + options, the last (i.e. right-most) option takes precedence. + + o 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. + + o A report interval (see below) will adjust start/end dates, when + needed, so that they fall on subperiod boundaries. + + Examples: + + + -b 2016/3/17 begin on St. Patrick's day 2016 + -e 12/1 end at the start of december 1st of the current year + (11/30 will be the last date included) + -b thismonth all transactions on or after the 1st of the current month + -p thismonth all transactions in the current month + date:2016/3/17.. the above written as queries instead (.. can also be + replaced with -) + date:..12/1 + date:thismonth.. + date:thismonth + + Report intervals + A report interval can be specified so that commands like register, bal- + ance and activity become multi-period, showing each subperiod as a sep- + arate row or column. + + The following "standard" report intervals can be enabled by using their + corresponding flag: + + o -D/--daily + + o -W/--weekly + + o -M/--monthly + + o -Q/--quarterly + + o -Y/--yearly + + These standard intervals always start on natural interval boundaries: + eg --weekly starts on mondays, --monthly starts on the first of the + month, --yearly always starts on January 1st, etc. + + Certain more complex intervals, and more flexible boundary dates, can + be specified by -p/--period. These are described in period expres- + sions, below. + + Report intervals can only be specified by the flags above, and not by + query arguments, currently. + + Report intervals have another effect: multi-period reports are always + expanded to fill a whole number of subperiods. So if you use a report + interval (other than --daily), and you have specified a start or end + date, you may notice those dates being overridden (ie, the report + starts earlier than your requested start date, or ends later than your + requested end date). This is done to ensure "full" first and last sub- + periods, so that all subperiods' numbers are comparable. + + To summarise: + + o In multiperiod reports, all subperiods are forced to be the same + length, to simplify reporting. + + o Reports with the standard --weekly/--monthly/--quarterly/--yearly + intervals are required to start on the first day of a + week/month/quarter/year. We'd like more flexibility here but it + isn't supported yet. + + o --period (below) can specify more complex intervals, starting on any + date. + + Period expressions + The -p/--period option accepts period expressions, a shorthand way of + expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as + exclusive: + + + -p "from 2009/1/1 to 2009/4/1" + + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as + ".." or "-". These are equivalent to the above: + + + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1..2009/4/1 + + Dates are smart dates, so if the current year is 2009, the above can + also be written as: + + + -p "1/1 4/1" + -p "january-apr" + -p "this year to 4/1" + + If you specify only one date, the missing start or end date will be the + earliest or latest transaction in your journal: + + + -p "from 2009/1/1" everything after january + 1, 2009 + -p "from 2009/1" the same + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 + + A single date with no "from" or "to" defines both the start and end + date like so: + + + -p "2009" the year 2009; equivalent + to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of jan; equiva- + lent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" just that day; equivalent + to "2009/1/1 to 2009/1/2" + + Or you can specify a single quarter like so: + + + -p "2009Q1" first quarter of 2009, + equivalent to "2009/1/1 to + 2009/4/1" + -p "q4" fourth quarter of the cur- + rent year + + Period expressions with a report interval + -p/--period's argument can also begin with, or entirely consist of, a + report interval. This should be separated from the start/end dates (if + any) by a space, or the word in. The basic intervals (which can also + be written as command line flags) are daily, weekly, monthly, quar- + terly, and yearly. Some examples: + + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "quarterly" + + As mentioned above, the weekly, monthly, quarterly and yearly intervals + require a report start date that is the first day of a week, month, + quarter or year. And, report start/end dates will be expanded if + needed to span a whole number of intervals. + + For example: + + + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + to 2009/4/1" day + -p "monthly in starts on 2018/11/01 + 2008/11/25" + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 + -p "yearly from starts on 2009/01/01, first day of 2009 + 2009-12-29" + + More complex report intervals + Some more complex kinds of interval are also supported in period + expressions: + + o biweekly + + o fortnightly + + o bimonthly + + o every day|week|month|quarter|year + + o every N days|weeks|months|quarters|years + + These too will cause report start/end dates to be expanded, if needed, + to span a whole number of intervals. Examples: + + + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + 2008/03/01, ... + -p "every 2 weeks" starts on closest preceding Monday + -p "every 5 months from periods will have boundaries on 2009/03/01, + 2009/03" 2009/08/01, ... + + Intervals with custom start date + All intervals mentioned above are required to start on their natural + calendar boundaries, but the following intervals can start on any date: + + Weekly on custom day: + + o every Nth day of week (th, nd, rd, or st are all accepted after the + number) + + o every WEEKDAYNAME (full or three-letter english weekday name, case + insensitive) + + Monthly on custom day: + + o every Nth day [of month] + + o every Nth WEEKDAYNAME [of month] + + Yearly on custom day: + + o every MM/DD [of year] (month number and day of month number) + + o every MONTHNAME DDth [of year] (full or three-letter english month + name, case insensitive, and day of month number) + + o every DDth MONTHNAME [of year] (equivalent to the above) + + Examples: + + + + + -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" + + Periods or dates ? + Report intervals like the above are most often used with -p|--period, + to divide reports into multiple subperiods - each generated date marks + a subperiod boundary. Here, the periods between the dates are what's + important. + + But report intervals can also be used with --forecast to generate + future transactions, or with balance --budget to generate budget goal- + setting transactions. For these, the dates themselves are what mat- + ters. + + Events on multiple weekdays + The every WEEKDAYNAME form has a special variant with multiple day + names, comma-separated. Eg: every mon,thu,sat. Also, weekday and + weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec- + tively. + + This form is mainly intended for use with --forecast, to generate peri- + odic transactions on arbitrary days of the week. It may be less useful + with -p, since it divides each week into subperiods of unequal length. + (Because gaps between periods are not allowed; if you'd like to change + this, see #1632.) + + Examples: + + + -p "every dates will be Mon, Wed, Fri; periods will be Mon- + mon,wed,fri" Tue, Wed-Thu, Fri-Sun + -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + be Mon, Tue, Wed, Thu, Fri-Sun + -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri + day" + +DEPTH + With the --depth NUM option (short form: -NUM), commands like account, + balance and register will show only the uppermost accounts in the + account tree, down to level NUM. 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. + +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 argu- + ments to restrict their scope. The syntax is as follows: + + o Zero or more space-separated query terms. These are most often + account name substrings: + + utilities food:groceries + + o Terms with spaces or other special characters should be enclosed in + quotes: + + "personal care" + + o Regular expressions are also supported: + + "^expenses\b" "accounts (payable|receivable)" + + o Add a query type prefix to match other parts of the data: + + date:202012- desc:amazon cur:USD amt:">100" status: + + o Add a not: prefix to negate a term: + + not:cur:USD + + 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 expres- + sion. This is the default query type when there is no prefix, and reg- + ular 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. Oth- + erwise, the absolute magnitudes are compared, ignoring sign. + + code:REGEX + Match by transaction code (eg check number). + + cur:REGEX + Match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a 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). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, + case insensitive. Note type:A and type:E will also match their respec- + tive 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: + + o Accounts also inherit the tags of their parent accounts + + o Postings also inherit the tags of their account and their transaction + + o 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.) + + Combining query terms + Most commands select things which match: + + o any of the description terms AND + + o any of the account terms AND + + o any of the status terms AND + + o all the other terms. + + while the print command shows transactions which: + + o match any of the description terms AND + + o have any postings matching any of the positive account terms AND + + o have no postings matching any of the negative account terms AND + + o match all the other terms. + + You can do more powerful queries (such as AND-ing two like terms) by + running a first query with print, and piping the result into a second + hledger command. Eg: how much of food expenses was paid with cash ? + + $ hledger print assets:cash | hledger -f- -I balance expenses:food + + If you are interested in full boolean expressions for queries, see + #203. + + 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. + + Queries and account aliases + When account names are rewritten with --alias or alias, acct: will + match either the old or the new account name. + + 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). + + 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. + + 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. + +CONVERSION & COST + This section is about converting between commodities. Some defini- + tions: + + o A "commodity conversion" is an exchange of one currency or commodity + for another. Eg a foreign currency exchange, or a purchase or sale + of stock or cryptocurrency. + + o A "conversion transaction" is a transaction involving one or more + such conversions. + + o "Conversion rate" is the exchange rate in a conversion - the cost per + unit of one commodity in the other. + + o "Cost" is how much of one commodity was paid to acquire the other + (when buying), or how much was received in exchange for the other + (when selling). We call both of these "cost" for convenience (after + all, it is cost for one party or the other). + + Recording conversions + As a concrete example, let's assume 100 EUR was converted to 120 USD. + There are several ways to record this in the journal, each with pros + and cons which will be explained in more detail below. (Also, these + examples use journal format which is properly explained much further + below; sorry about that, you may want to read some of that first.) + + Implicit conversion + 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: + + o Easy, concise + + o hledger can do cost reporting + + Con: + + o Less error checking - typos in amounts or commodity symbols may not + be detected + + o conversion rate is not clear + + o disturbs the accounting equation + + You can prevent accidental implicit conversions due to a mistyped com- + modity symbol, by using hledger check commodities. You can prevent + implicit conversions entirely, by using hledger check balancednoauto- + conversion, or -s/--strict. + + Priced conversion + 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: + + o Still concise + + o makes the conversion rate clear + + o provides some error checking + + o hledger can do cost reporting + + Con: + + o Disturbs the accounting equation + + Equity conversion + In strict double entry bookkeeping, the above transaction is not bal- + anced 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: + + o Preserves the accounting equation + + o keeps track of conversions and related gains/losses in one place + + o works in any double entry accounting system + + Con: + + o More verbose + + o conversion rate is not clear + + o hledger can not do cost reporting + + Priced equity conversion + Another possible notation would be to record both the conversion rate + and the equity postings: + + 2021-01-01 + assets:cash -100 EUR @ 1.20 USD + equity:conversion 100 EUR + equity:conversion -120 USD + assets:cash 120 USD + + hledger currently does not allow this; instead, you can record the con- + version rate as a comment. + + Inferring missing conversion rates + hledger will do this automatically for implicit conversions. Currently + it can not do this for equity conversions. + + Inferring missing equity postings + With the --infer-equity flag, hledger will add equity postings to + priced and implicit conversions (and move the conversion rate into a + comment). + + Cost reporting + With the -B/--cost flag, hledger will convert the amounts in priced and + implicit conversions to their cost in the other commodity. This is + useful to see a report of what you paid for things (or how much you + sold things for). Currently -B/--cost does not work on equity conver- + sions, and it disables --infer-equity. + + These operations are transient, only affecting reports. If you want to + change the journal file permanently, you could pipe each entry through + hledger -f- -I print [-x] [--infer-equity] [-B] + + Conversion summary + o Recording the conversion rate is good because it makes that clear and + allows cost reporting. + + o Recording equity postings is good because it balances the accounting + equation and is correct bookkeeping. + + o Combining these is not yet supported, so you have to choose. For + now, priced conversions are a good compromise, so that: + + o When you want to see the cost (or sale proceeds) of things, use + -B/--cost. + + o When you want to see a balanced balance sheet or correct journal + entries, use --infer-equity. + + o Combining these is not yet supported; -B/--cost will take prece- + dence. + + o Conversion/cost operations are performed before valuation. + +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: + + -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. + + -X: Value in specified commodity + The -X/--exchange=COMM option is like -V, except you tell it which cur- + rency you want to convert to, and it tries to convert everything to + that. + + 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. + + Market prices + 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 direc- + tive, or (with the --infer-market-prices flag) inferred from trans- + action prices. + + 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 com- + bining 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 con- + verted. + + --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 transaction prices as additional market + prices (as Ledger does) ? We could produce value reports without need- + ing P directives at all. + + 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. (And if + both occur on the same day, the P directive takes precedence). + + There is a downside: value reports can sometimes be affected in confus- + ing/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: + + o multicommodity transactions with explicit prices (@/@@) + + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. + hledger print -x can be useful for troubleshooting.) + + o but not, currently, from "more correct" multicommodity transactions + (no @, multiple commodities, balanced). + + There is another 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 con- + version might not happen because no valuation commodity was detected + (--debug=2 will show this). To be safe, specify the valuation commmod- + ity, eg: + + o -X EUR --infer-market-prices, not -V --infer-market-prices + + o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- + ket-prices + + 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 suit- + able 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: + + o If you have P directives, they determine which commodities -V will + convert, and to what. + + o If you have no P directives, and use the --infer-market-prices flag, + transaction prices determine it. + + Amounts for which no valuation commodity can be found are not con- + verted. + + Simple valuation examples + Here are some quick examples of -V: + + ; one euro is worth this many dollars from nov 1 + P 2016/11/01 EUR $1.10 + + ; purchase some euros on nov 3 + 2016/11/3 + assets:euros EUR100 + assets:checking + + ; the euro is worth fewer dollars by dec 21 + P 2016/12/21 EUR $1.03 + + How many euros do I have ? + + $ hledger -f t.j bal -N euros + EUR100 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 + + --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 commod- + ity, using market prices on each posting's date. + + --value=end + Convert amounts to their value in the default valuation commod- + ity, 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 commod- + ity using current market prices (as of when report is gener- + ated). + + --value=YYYY-MM-DD + Convert amounts to their value in the default valuation commod- + ity 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. + + 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 specify- + ing a display style for A, 0.5A gets the default style, which shows no + decimal digits. Because the displayed amount looks like zero, the com- + modity symbol and minus sign are not displayed either. Adding a com- + modity 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 + + 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 + + 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, --cost -V, -X --value=then --value=end --value=DATE, + type --value=now + ----------------------------------------------------------------------------------------------- + print + posting cost value at value at posting value at value at + amounts report end date report or DATE/today + or today journal end + balance unchanged unchanged unchanged unchanged unchanged + asser- + tions/assign- + ments + + register + starting bal- cost value at valued at day value at value at + ance (-H) report or each historical report or DATE/today + journal end posting was made journal end + starting bal- cost value at day valued at day value at day value at + ance (-H) before each historical before DATE/today + with report report or posting was made report or + interval journal journal + start start + posting cost value at value at posting value at value at + amounts report or date report or DATE/today + journal end journal end + summary post- summarised value at sum of postings value at value at + ing amounts cost period ends in interval, val- period ends DATE/today + with report ued at interval + interval start + running sum/average sum/average sum/average of sum/average sum/average + total/average of displayed of displayed displayed values of displayed of displayed + values values values values + + balance (bs, + bse, cf, is) + balance sums of value at value at posting value at value at + changes costs report end date report or DATE/today of + or today of journal end sums of post- + sums of of sums of ings + postings postings + budget like balance like balance like balance like bal- like balance + amounts changes changes changes ances changes + (--budget) + grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + played val- played val- valued played val- played values + ues ues ues + + + + balance (bs, + bse, cf, is) + with report + interval + starting bal- sums of value at sums of values of value at sums of post- + ances (-H) costs of report start postings before report start ings before + postings of sums of report start at of sums of report start + before all postings respective post- all postings + report start before ing dates before + report start report start + balance sums of same as sums of values of balance value at + changes (bal, costs of --value=end postings in change in DATE/today of + is, bs postings in period at respec- each period, sums of post- + --change, cf period tive posting valued at ings + --change) dates period ends + end balances sums of same as sums of values of period end value at + (bal -H, is costs of --value=end postings from balances, DATE/today of + --H, bs, cf) postings before period valued at sums of post- + from before start to period period ends ings + report start end at respective + to period posting dates + end + budget like balance like balance like balance like bal- like balance + amounts changes/end changes/end changes/end bal- ances changes/end + (--budget) balances balances ances balances + row totals, sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- + row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- + (-T, -A) played val- played val- played val- played values + ues ues ues + column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + played val- played val- values played val- played values + ues ues ues + grand total, sum, average sum, average sum, average of sum, average sum, average + grand average of column of column column totals of column of column + totals totals totals 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 subperi- + ods). + +PIVOTING + Normally hledger sums amounts, and organizes them in a hierarchy, based + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD + can be: status, code, description, payee, note, or the full name (case + insensitive) of any tag. As with account names, values containing + colon:separated:parts will be displayed hierarchically in reports. + + --pivot is a general option affecting all reports; you can think of + hledger transforming the journal before any other processing, replacing + every posting's account name with the value of the specified field on + that posting, inheriting it from the transaction or using a blank value + if it's not present. + + An example: + + 2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query, + described below): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + +OUTPUT + 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 pro- + vide 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) + + hledger can optionally produce debug output (if enabled with + --debug=N); this goes to stderr, and is not affected by -o/--output- + file. If you need to capture it, use shell redirects, eg: hledger bal + --debug=3 >file 2>&1. + + Output styling + hledger commands can produce colour output when the terminal supports + it. This is controlled by the --color/--colour option: - 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. + + hledger commands can also use unicode box-drawing characters to produce + prettier tables and output. This is controlled by the --pretty option: + - 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. + + Output format + Some commands offer additional output formats, other than the usual + plain text terminal output. Here are those commands and the formats + currently supported: + + + - txt csv html json sql + --------------------------------------------- + aregister Y Y Y + balance Y 1 Y 1 Y 1,2 Y + bal- Y 1 Y 1 Y 1 Y + ancesheet + bal- Y 1 Y 1 Y 1 Y + ancesheete- + quity + cashflow Y 1 Y 1 Y 1 Y + incomes- Y 1 Y 1 Y 1 Y + tatement + print Y Y Y Y + register Y Y Y + + o 1 Also affected by the balance commands' --layout option. + + o 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 + + CSV output + o In CSV output, digit group marks (such as thousands separators) are + disabled automatically. + + HTML output + o HTML output can be styled by an optional hledger.css file in the same + directory. + + JSON output + o Not yet much used; real-world feedback is welcome. + + o Our JSON is rather large and verbose, as it is quite a faithful rep- + resentation 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. + + o 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) + + SQL output + o Not yet much used; real-world feedback is welcome. + + o SQL output is expected to work with sqlite, MySQL and PostgreSQL + + o SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables cre- + ated 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. + + Commodity styles + The display style of a commodity/currency is inferred according to the + rules described in Commodity display style. The inferred display style + can be overridden by an optional -c/--commodity-style option (Excep- + tions: as is the case for inferred styles, price amounts, and all + amounts displayed by the print command, will be displayed with all of + their decimal digits visible, regardless of the specified precision). + For example, the following will override the display style for dollars. + + $ hledger print -c '$1.000,0' + + The format specification of the style is identical to the commodity + display style specification for the commodity directive. The command + line option can be supplied repeatedly to override the display style + for multiple commodity/currency symbols. + +COMMANDS + hledger provides a number of commands for producing reports and manag- + ing your data. Run hledger with no arguments to list the commands + available, and hledger CMD to run a command. CMD can be the full com- + mand name, or its standard abbreviation shown in the commands list, or + any unambiguous prefix of the name. Eg: hledger bal. + + Here are the built-in commands, with the most often-used in bold: + + Data entry: + + These data entry commands are the only ones which can modify your jour- + nal file. + + o add - add transactions using guided prompts + + o import - add any new transactions from other files (eg csv) + + Data management: + + o check - check for various kinds of issue in the data + + o close (equity) - generate balance-resetting transactions + + o diff - compare account transactions in two journal files + + o rewrite - generate extra postings, similar to print --auto + + Financial statements: + + o aregister (areg) - show transactions in a particular account + + o balancesheet (bs) - show assets, liabilities and net worth + + o balancesheetequity (bse) - show assets, liabilities and equity + + o cashflow (cf) - show changes in liquid assets + + o incomestatement (is) - show revenues and expenses + + o roi - show return on investments + + Miscellaneous reports: + + o accounts - show account names + + o activity - show postings-per-interval bar charts + + o balance (bal) - show balance changes/end balances/budgets in any + accounts + + o codes - show transaction codes + + o commodities - show commodity/currency symbols + + o descriptions - show unique transaction descriptions + + o files - show input file paths + + o help - show hledger user manuals in several formats + + o notes - show unique note segments of transaction descriptions + + o payees - show unique payee segments of transaction descriptions + + o prices - show market price records + + o print - show transactions (journal entries) + + o print-unique - show only transactions with unique descriptions + + o register (reg) - show postings in one or more accounts & running + total + + o register-match - show a recent posting that best matches a descrip- + tion + + o stats - show journal statistics + + o tags - show tag names + + o test - run self tests + + Add-on commands: + + Programs or scripts named hledger-SOMETHING in your PATH are add-on + commands; these appear in the commands list with a + mark. Two of + these are maintained and released with hledger: + + o ui - an efficient terminal interface (TUI) for hledger + + o web - a simple web interface (WUI) for hledger + + And these add-ons are maintained separately: + + o iadd - a more interactive alternative for the add command + + o interest - generates interest transactions according to various + schemes + + o stockquotes - downloads market prices for your commodities from + AlphaVantage (experimental) + + Next, the detailed command docs, in alphabetical order. + + accounts + accounts + Show account names. + + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N + or -N. + + With --types, it also shows each account's type, if it's known. (See + Declaring accounts > Account types.) + + Examples: + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + activity + activity + Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the + default). With query arguments, it counts only matched transactions. + + Examples: + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + + add + add + Prompt for transactions and add them to the journal. 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 trans- + actions, 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: + + o add tries to provide useful defaults, using the most similar (by + description) recent transaction (filtered by the query, if any) as a + template. + + o You can also set the initial defaults with command line arguments. + + o Readline-style edit keys can be used during data entry. + + o The tab key will auto-complete whenever possible - accounts, descrip- + tions, dates (yesterday, today, tomorrow). If the input area is + empty, it will insert the default value. + + o If the journal defines a default commodity, it will be added to any + bare numbers entered. + + o A parenthesised transaction code may be entered following a date. + + o Comments and tags may be entered following a description or amount. + + o If you make a mistake, enter < at any prompt to go one step backward. + + o Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see the tutorial for a detailed explanation): + + $ hledger add + Adding transactions to journal file /src/hledger/examples/sample.journal + Any command line arguments will be used as defaults. + Use tab key to complete, readline keys to edit, enter to accept defaults. + An optional (CODE) may follow transaction dates. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to 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). + + aregister + 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 areg- + ister 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. + (Eg if you have assets:aaa:checking and assets:bbb:checking accounts, + hledger areg checking would select assets:aaa:checking.) + + 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 transac- + tions shown. Note some queries will disturb the running balance, caus- + ing 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: + + o the transaction's date (or the relevant posting's date if different, + see below) + + o the names of all the other account(s) involved in this transaction + (probably abbreviated) + + o the total change to this account's balance from this transaction + + o 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. + + 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. + + balance + 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, bal- + ancesheetequity, cashflow and incomestatement. When you need more con- + trol, then use balance. + + 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.. + + o accounts as a list (-l) or a tree (-t) + + o optionally depth-limited (-[1-9]) + + o sorted by declaration order and name, or by amount + + ..and their.. + + o balance changes (the default) + + o or actual and planned balance changes (--budget) + + o or value of balance changes (-V) + + o or change of balance values (--valuechange) + + o or unrealised capital gain/loss (--gain) + + ..in.. + + o one time period (the whole journal period by default) + + o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) + + ..either.. + + o per period (the default) + + o or accumulated since report start date (--cumulative) + + o or accumulated since account creation (--historical/-H) + + ..possibly converted to.. + + o cost (--value=cost[,COMM]/--cost/-B) + + o or market value, as of transaction dates (--value=then[,COMM]) + + o or at period ends (--value=end[,COMM]) + + o or now (--value=now) + + o or at some other date (--value=YYYY-MM-DD) + + ..with.. + + o totals (-T), averages (-A), percentages (-%), inverted sign + (--invert) + + o rows and columns swapped (--transpose) + + o another field used as account name (--pivot) + + o custom-formatted line items (single-period reports only) (--format) + + o 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. + + 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. For real-world + accounts, this should also match their end balance at the end of the + journal period (more on this below). + + Accounts are sorted by declaration order if any, and then alphabeti- + cally 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. + + 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 + + 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: + + o "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). + + o 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-plaintextac- + counting-users. A tree mode report's final total is the sum of the + top-level balances shown, not of all the balances shown. + + o Each group of sibling accounts (ie, under a common parent) is sorted + separately. + + 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 + + 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 + + + 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), bal- + ance 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: + + o The report's start/end dates will be expanded, if necessary, to fully + encompass the displayed subperiods (so that the first and last subpe- + riods have the same duration as the others). + + o Leading and trailing periods (columns) containing all zeroes are not + shown, unless -E/--empty is used. + + o Accounts (rows) containing all zeroes are not shown, unless + -E/--empty is used. + + o Amounts with many commodities are shown in abbreviated form, unless + --no-elide is used. (experimental) + + o Average and/or total columns can be added with the -A/--average and + -T/--row-total flags. + + o The --transpose flag can be used to exchange rows and columns. + + o 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: + + o Hide the totals row with -N/--no-total + + o Convert to a single currency with -V + + o Maximize the terminal window + + o Reduce the terminal's font size + + o View with a pager like less, eg: hledger bal -D --color=yes | less + -RS + + o 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) + + o Output as HTML and view with a browser: hledger bal -D -o a.html && + open a.html + + 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. + + Data layout + The --layout option affects how multi-commodity amounts are displayed, + and some other things, influencing the overall layout of the report + data: + + o --layout=wide[,WIDTH]: commodities are shown on a single line, possi- + bly elided to the specified width + + o --layout=tall: each commodity is shown on a separate line + + o --layout=bare: amounts are shown as bare numbers, with commodity sym- + bols in a separate column + + o --layout=tidy: data is normalised to tidy form, with one row per data + value. We currently support this with CSV output only. In tidy + mode, totals and row averages are disabled (-N/--no-total is implied + and -T/--row-total and -A/--average will be ignored). + + These --layout modes are supported with some but not all of the output + formats: + + + - txt csv html json sql + ------------------------------------- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y + + Examples: + + o 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 + + o Limited wide layout. A width limit reduces the width, but some com- + modities 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.. + + o 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 + + o Bare layout. Commodity symbols are kept in one column, each commod- + ity 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 + + o Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg when 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" + + o Tidy layout produces normalised "tidy data", where every variable is + a column and each row represents a single data point (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- + data.html). This kind of data is the easiest to process with other + software: + + $ 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" + + Sorting by amount + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. Eg: hledger bal expenses -MAS shows your big- + gest 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). + + + Percentages + With -%/--percent, balance reports show each account's value expressed + as a percentage of the (column) total: + + $ hledger -f examples/sample.journal bal expenses -Q -% + Balance changes in 2008: + + || 2008Q1 2008Q2 2008Q3 2008Q4 + ===================++================================= + expenses:food || 0 50.0 % 0 0 + expenses:supplies || 0 50.0 % 0 0 + -------------------++--------------------------------- + || 0 100.0 % 0 0 + + Note it is not useful to calculate percentages if the amounts in a col- + umn 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:EUR + + Balance change, end balance + It's important to be clear on the meaning of the numbers shown in bal- + ance 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 post- + ings.) + + Balance report types + For more flexible reporting, there are three important option groups: + + hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] + ... + + The first two are the most important: calculation type selects the + basic calculation to perform for each table cell, while accumulation + type says which postings should be included in each cell's calculation. + Typically one or both of these are selected by default, so you don't + need to write them explicitly. A valuation type can be added if you + want to convert the basic report to value or cost. + + Calculation type: + The basic calculation to perform for each table cell. It is one of: + + o --sum : sum the posting amounts (default) + + o --budget : like --sum but also show a goal amount + + o --valuechange : show the change in period-end historical balance val- + ues (caused by deposits, withdrawals, and/or market price fluctua- + tions) + + o --gain : show the unrealised capital gain/loss, (the current valued + balance minus each amount's original cost) + + Accumulation type: + Which postings should be included in each cell's calculation. It is + one of: + + o --change : postings from column start to column end, ie within the + cell's period. Typically used to see revenues/expenses. (default + for balance, incomestatement) + + o --cumulative : postings from report start to column end, eg to show + changes accumulated since the report's start date. Rarely used. + + o --historical/-H : postings from journal start to column end, ie all + postings from account creation to the end of the cell's period. Typ- + ically used to see historical end balances of assets/liabili- + ties/equity. (default for balancesheet, balancesheetequity, cash- + flow) + + Valuation type: + Which kind of valuation, valuation date(s) and optionally a target val- + uation commodity to use. It is one of: + + o no valuation, show amounts in their original commodities (default) + + o --value=cost[,COMM] : no valuation, show amounts converted to cost + + o --value=then[,COMM] : show value at transaction dates + + o --value=end[,COMM] : show value at period end date(s) (default with + --valuechange, --gain) + + o --value=now[,COMM] : show value at today's date + + o --value=YYYY-MM-DD[,COMM] : show value at another date + + or one of their aliases: --cost/-B, --market/-V or --exchange/-X. + + 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: + + o --valuechange implies --value=end + + o --valuechange makes --change the default when used with the bal- + ancesheet/balancesheetequity commands + + o --cumulative or --historical disables --row-total/-T + + For reference, here is what the combinations of accumulation and valua- + tion show: + + + + Valua- no valuation --value= then --value= end --value= YYYY- + tion: MM-DD /now + >Accumu- + lation: + v + ------------------------------------------------------------------------------------ + --change change in period sum of posting- period-end DATE-value of + date market val- value of change change in + ues in period in period period + --cumu- change from sum of posting- period-end DATE-value of + lative report start to date market val- value of change change from + period end ues from report from report report start + start to period start to period to period end + end end + --his- change from sum of posting- period-end DATE-value of + torical journal start to date market val- value of change change from + /-H period end (his- ues from journal from journal journal start + torical end bal- start to period start to period to period end + ance) end end + + Useful balance reports + Some frequently used balance options/reports are: + + o bal -M revenues expenses + Show revenues/expenses in each month. Also available as the incomes- + tatement command. + + o bal -M -H assets liabilities + Show historical asset/liability balances at each month end. Also + available as the balancesheet command. + + o bal -M -H assets liabilities equity + Show historical asset/liability/equity balances at each month end. + Also available as the balancesheetequity command. + + o bal -M assets not:receivable + Show changes to liquid assets in each month. Also available as the + cashflow command. + + Also: + + o bal -M expenses -2 -SA + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + o bal -M --budget expenses + Show monthly expenses and budget goals. + + o bal -M --valuechange investments + Show monthly change in market value of investment assets. + + o bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert] + Show top gainers [or losers] last week + + 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 very 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: + + o Only accounts with budget goals during the report period are shown, + by default. + + o In each column, in square brackets after the actual amount, budget + goal amounts are shown, and the actual/goal percentage. (Note: bud- + get goals should be in the same commodity as the actual amount.) + + o All parent accounts are always shown, even in list mode. Eg assets, + assets:bank, and expenses above. + + o 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 transac- + tions, 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] + + For more examples and notes, see Budgeting. + + 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] + + 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 bud- + get(s) of the child account(s) would be added to the budget of their + parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any + account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which 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 transac- + tions in any other subaccount of expenses:personal would be counted + towards only towards the budget of expenses:personal. + + For example, let's consider these transactions: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + 2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + + 2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + + 2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + + 2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- + tions would be counted towards budgets of expenses:personal:electronics + and expenses:personal accordingly: + + $ hledger balance --budget -M + Budget performance in 2019/01: + + || Jan + ===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] + -------------------------------++------------------------------- + || 0 [ 0] + + And with --empty, we can get a better picture of budget allocation and + consumption: + + $ hledger balance --budget -M --empty + Budget performance in 2019/01: + + || Jan + ========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] + ----------------------------------------++------------------------------- + || 0 [ 0] + + Selecting budget goals + The budget report evaluates periodic transaction rules to generate spe- + cial "goal transactions", which generate the goal amounts for each + account in each report subperiod. When troubleshooting, you can use + the print command 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. + + Customising single-period balance reports + 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 (plus a newline) specifies the formatting applied + to each account/balance pair. It may contain any suitable text, with + data fields interpolated like so: + + %[MIN][.MAX](FIELDNAME) + + o MIN pads with spaces to at least this width (optional) + + o MAX truncates at this width (optional) + + o FIELDNAME must be enclosed in parentheses, and can be one of: + + o depth_spacer - a number of spaces equal to the account's depth, or + if MIN is specified, MIN * depth spaces. + + o account - the account's name + + o total - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how multi-com- + modity amounts are rendered: + + o %_ - render on multiple lines, bottom-aligned (the default) + + o %^ - render on multiple lines, top-aligned + + o %, - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, %(depth_spacer) has no + effect, instead %(account) has indentation built in. Experimentation + may be needed to get pleasing results. + + Some example formats: + + o %(total) - the account's total + + o %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters + + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line + + o %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + + balancesheet + balancesheet, bs + This command displays a balance sheet, showing historical ending bal- + ances 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 sup- + ports 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 (experi- + mental) json. + + balancesheetequity + balancesheetequity, bse + This command displays a balance sheet, showing historical ending bal- + ances 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 sup- + ports 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 (experi- + mental) json. + + cashflow + 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 finan- + cial statements. + + This report shows accounts declared with the Cash type (see account + types). Or if no such accounts are declared, it shows accounts + + o under a top-level account named asset (case insensitive, plural + allowed) + + o 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 sup- + ports 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 (experi- + mental) json. + + check + 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 + + Here are the checks currently available: + + Basic checks + These checks are always run automatically, by (almost) all hledger com- + mands, including check: + + o parseable - data files are well-formed and can be successfully parsed + + o balancedwithautoconversion - all transactions are balanced, inferring + missing amounts where necessary, and possibly converting commodities + using transaction prices or automatically-inferred transaction prices + + o assertions - all balance assertions in the journal are passing. + (This check can be disabled with -I/--ignore-assertions.) + + 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: + + o accounts - all account names used by transactions have been declared + + o commodities - all commodity symbols used have been declared + + o balancednoautoconversion - transactions are balanced, possibly using + explicit transaction prices but not inferred ones + + 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: + + o ordereddates - transactions are ordered by date within each file + + o payees - all payees used by transactions have been declared + + o uniqueleafnames - all account leaf names are unique + + Custom checks + A few more checks are are available as separate add-on commands, in + https://github.com/simonmichael/hledger/tree/master/bin: + + o hledger-check-tagfiles - all tag values containing / (a forward + slash) exist as file paths + + o hledger-check-fancyassertions - more complex balance assertions are + passing + + You could make similar scripts to perform your own custom checks. See: + Cookbook -> Scripting. + + close + close, equity + Prints a sample "closing" transaction bringing specified account bal- + ances to zero, and an inverse "opening" transaction restoring the same + account balances. + + If like most people you split your journal files by time, eg by year: + at the end of the year you can use this command to "close out" your + asset and liability (and perhaps equity) balances in the old file, and + reinitialise them in the new file. This helps ensure that report bal- + ances remain correct whether you are including old files or not. + (Because all closing/opening transactions except the very first will + cancel out - see example below.) + + Some people also use this command to close out revenue and expense bal- + ances at the end of an accounting period. This properly records the + period's profit/loss as "retained earnings" (part of equity), and + allows the accounting equation (A-L=E) to balance, which you could then + check by the bse report's zero total. + + You can print just the closing transaction by using the --close flag, + or just the opening transaction with the --open flag. + + Their descriptions are closing balances and opening balances by + default; you can customise these with the --close-desc and --open-desc + options. + + Just one balancing equity posting is used by default, with the amount + left implicit. The default account name is equity:opening/closing bal- + ances. You can customise the account name(s) with --close-acct and + --open-acct. (If you specify only one of these, it will be used for + both.) + + With --x/--explicit, the equity posting's amount will be shown explic- + itly, and if it involves multiple commodities, there will be a separate + equity posting for each commodity (as in the print command). + + With --interleaved, each equity posting is shown next to the posting it + balances (good for troubleshooting). + + close and prices + Transaction prices are ignored (and discarded) by closing/opening + transactions, by default. With --show-costs, they are preserved; there + will be a separate equity posting for each cost in each commodity. + This means balance -B reports will look the same after the transition. + Note if you have many foreign currency or investment transactions, this + will generate very large journal entries. + + close date + The default closing date is yesterday, or the journal's end date, + whichever is later. + + Unless you are running close on exactly the first day of the new + period, you'll want to override the closing date. This is done by + specifying a report end date, where "last day of the report period" + will be the closing date. The opening date is always the following + day. So to close on (end of) 2020-12-31 and open on (start of) + 2021-01-01, any of these will work: + + + end date argument explanation + ----------------------------------------------- + -e 2021-01-01 end dates are exclusive + -e 2021 equivalent, per smart + dates + -p 2020 equivalent, the period's + begin date is ignored + date:2020 equivalent query + + Example: close asset/liability accounts for file transition + Carrying asset/liability balances from 2020.journal into a new file for + 2021: + + $ hledger close -f 2020.journal -p 2020 assets liabilities + # copy/paste the closing transaction to the end of 2020.journal + # copy/paste the opening transaction to the start of 2021.journal + + Or: + + $ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction + $ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction + + Now, + + $ hledger bs -f 2021.journal # just new file - balances correct + $ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct + $ hledger bs -f 2020.journal # just old files - balances are zero ? + # (exclude final closing txn, see below) + + Hiding opening/closing transactions + Although the closing/opening transactions cancel out, they will be vis- + ible in reports like print and register, creating some visual clutter. + You can exclude them all with a query, like: + + $ hledger print not:desc:'opening|closing' # less typing + $ hledger print not:'equity:opening/closing balances' # more precise + + But when reporting on multiple files, this can get a bit tricky; you + may need to keep the earliest opening balances, for a historical regis- + ter report; or you may need to suppress a closing transaction, to see + year-end balances. If you find yourself needing more precise queries, + here's one solution: add more easily-matched tags to opening/closing + transactions, like this: + + ; 2019.journal + 2019-01-01 opening balances ; earliest opening txn, no tag here + ... + 2019-12-31 closing balances ; clopen:2020 + ... + + ; 2020.journal + 2020-01-01 opening balances ; clopen:2020 + ... + 2020-12-31 closing balances ; clopen:2021 + ... + + ; 2021.journal + 2021-01-01 opening balances ; clopen:2021 + ... + + Now with + + ; all.journal + include 2019.journal + include 2020.journal + include 2021.journal + + you could do eg: + + $ hledger -f all.journal reg -H checking not:tag:clopen + # all years checking register, hiding non-essential opening/closing txns + + $ hledger -f all.journal bs -p 2020 not:tag:clopen=2020 + # 2020 year end balances, suppressing 2020 closing txn + + close and balance assertions + The closing and opening transactions will include balance assertions, + verifying that the accounts have first been reset to zero and then + restored to their previous balance. These provide valuable error + checking, alerting you when things get out of line, but you can ignore + them temporarily with -I or just remove them if you prefer. + + You probably shouldn't use status or realness filters (like -C or -R or + status:) with close, or the generated balance assertions will depend on + these flags. Likewise, if you run this command with --auto, the bal- + ance assertions would probably always require --auto. + + Multi-day transactions (where some postings have a different date) + break the balance assertions, because the money is temporarily "invisi- + ble" while in transit: + + 2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + assets:bank:checking -5 ; date: 2021/1/2 + + To fix the assertions, you can add a temporary account to track such + in-transit money (splitting the multi-day transaction into two single- + day transactions): + + ; in 2020.journal: + 2020/12/30 a purchase made in december, cleared in the next year + expenses:food 5 + liabilities:pending + + ; in 2021.journal: + 2021/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:bank:checking + + Example: close revenue/expense accounts to retained earnings + For this, use --close to suppress the opening transaction, as it's not + needed. Also you'll want to change the equity account name to your + equivalent of "equity:retained earnings". + + Closing 2021's first quarter revenues/expenses: + + $ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \ + --close-acct='equity:retained earnings' >> 2021.journal + + The same, using the default journal and current year: + + $ hledger close --close revenues expenses -p Q1 \ + --close-acct='equity:retained earnings' >> $LEDGER_FILE + + Now, the first quarter's balance sheet should show a zero (unless you + are using @/@@ notation without equity postings): + + $ hledger bse -p Q1 + + And we must suppress the closing transaction to see the first quarter's + income statement (using the description; not:'retained earnings' won't + work here): + + $ hledger is -p Q1 not:desc:'closing balances' + + codes + 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: + + 1/1 (123) + (a) 1 + + 1/1 () + (a) 1 + + 1/1 + (a) 1 + + 1/1 (126) + (a) 1 + + $ hledger codes + 123 + 124 + 126 + + $ hledger codes -E + 123 + 124 + + + 126 + + commodities + commodities + List all commodity/currency symbols used or declared in the journal. + + descriptions + 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 trans- + actions. + + Example: + + $ hledger descriptions + Store Name + Gas Station | Petrol + Person A + + diff + 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 mul- + tiple 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: + + files + files + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + help + help + Show the hledger user manual in one of several formats, optionally + positioned at a given TOPIC (if possible). + + TOPIC is any heading in the manual, or the start of any heading (but + not the middle). It is case insensitive. + + Some examples: commands, print, forecast, "auto postings", "commodity + column". + + This command shows the user manual built in to this hledger version. + It can be useful if the correct version of the hledger manual, or the + usual viewing tools, are not installed on your system. + + By default it uses the best viewer it can find in $PATH, in this order: + info, man, $PAGER (unless a topic is specified), less, or stdout. When + run non-interactively, it always uses stdout. Or you can select a par- + ticular viewer with the -i (info), -m (man), or -p (pager) flags. + + import + 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' trans- + actions 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 out- + put 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. + + 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 idem- + potent.) + + 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 sav- + ing a hidden ".latest" state file in the same directory. Eg when read- + ing finance/bank.csv, it will look for and update the finance/.lat- + est.bank.csv state file. The format is simple: one or more lines con- + taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- + cessed 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 cer- + tain date. + + Note deduplication (and updating of state files) can also be done by + print --new, but this is less often used. + + 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' + + 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.) + + Commodity display styles + Imported amounts will be formatted according to the canonical commodity + styles (declared or inferred) in the main journal file. + + incomestatement + 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 insensi- + tive, 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 sup- + ports 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 (experi- + mental) json. + + notes + 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 transac- + tions. 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 + + payees + 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 + + prices + prices + Print market price directives from the journal. With --infer-market- + prices, generate additional market prices from transaction prices. + With --infer-reverse-prices, also generate market prices by inverting + transaction prices. Prices (and postings providing transaction prices) + can be filtered by a query. Price amounts are displayed with their + full precision. + + print + 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 deci- + mal places are shown, as in the original journal entry (with one alter- + ation: 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: + + o Valuation affects posting amounts but not balance assertion or bal- + ance assignment amounts, potentially causing those to fail. + + o Auto postings can generate postings with too many missing amounts. + + o Account aliases can generate bad account names. + + Normally, the journal entry's explicit or implicit amount style is pre- + served. For example, when an amount is omitted in the journal, it will + not appear in the output. Similarly, when a transaction price is + implied but not written, it will not appear in the output. You can use + the -x/--explicit flag to make all amounts and transaction prices + 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 transaction prices are converted to cost + using that price. This can be used for troubleshooting. + + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is + no similar-enough match, no transaction will be shown. + + With --new, hledger prints only transactions it has not seen on a pre- + vious run. This uses the same deduplication system as the import com- + mand. (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","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o The "txnidx" (transaction index) field shows which postings belong to + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different + order, etc.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + print-unique + print-unique + Print transactions which do not reuse an already-seen description. + + Example: + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + + register + register, reg + 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 num- + bers. 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. + + 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. + + register-match + register-match + Print the one posting whose transaction description is closest to DESC, + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger- + autosync detect already-seen transactions when importing. + + rewrite + rewrite + Print all transactions, rewriting the postings of matched transactions. + For now the only rewrite available is adding new postings, like print + --auto. + + This is a start at a generic rewriter of transaction entries. It reads + the default journal and prints the transactions, like print, but adds + one or more specified postings to any transactions matching QUERY. The + posting amounts can be fixed, or a multiplier of the existing transac- + tion's first posting amount. + + Examples: + + $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' + $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' + $ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + + = ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the + two spaces between account and amount. + + More: + + $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... + $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' + $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' + $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can + use '*' (star symbol) before the amount to indicate that that this is a + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- + modity. + + Re-write rules in a file + During the run this tool will execute so called "Automated Transac- + tions" found in any journal it process. I.e instead of specifying this + operations in command line you can put them in a journal file. + + $ rewrite-rules.journal + + Make contents look like this: + + = ^income + (liabilities:tax) *.33 + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that '=' (equality symbol) that is used instead of date in trans- + actions you usually write. It indicates the query by which you want to + match the posting to add new ones. + + $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + + $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- + ings. + + Diff output format + To use this tool for batch modification of your journal files you may + find useful output in form of unified diff. + + $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + + --- /tmp/examples/sample.journal + +++ /tmp/examples/sample.journal + @@ -18,3 +18,4 @@ + 2008/01/01 income + - assets:bank:checking $1 + + assets:bank:checking $1 + income:salary + + (liabilities:tax) 0 + @@ -22,3 +23,4 @@ + 2008/06/01 gift + - assets:bank:checking $1 + + assets:bank:checking $1 + income:gifts + + (liabilities:tax) 0 + + If you'll pass this through patch tool you'll get transactions contain- + ing the posting that matches your query be updated. Note that multiple + files might be update according to list of input files specified via + --file options and include directives inside of these files. + + Be careful. Whole transaction being re-formatted in a style of output + from hledger print. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + rewrite vs. print --auto + This command predates print --auto, and currently does much the same + thing, but with these differences: + + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + + o rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + + o rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. + + roi + roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + on your investments. + + 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: + + o 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. + + o Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or con- + verges too slowly. + + Examples: + + o Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/invest- + ing/roi-unrealised.ledger + + o Cookbook > Return on Investment: https://hledger.org/roi.html + + 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'" + + 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. + + o "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 + + o "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 + + IRR and TWR explained + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- + tial value, expressed in percentage of the initial value. + + However, this approach is only practical in simple cases, where invest- + ments receives no in-flows or out-flows of money, and where rate of + growth is fixed over time. For more complex scenarios you need differ- + ent 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 percent- + age of your initial investment, and if you are adding to your invest- + ment, 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 "unreal- + ized 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: + + o Explanation of rate of return + + o Explanation of IRR + + o Explanation of TWR + + o Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + stats + 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 also supports output destination and output format selec- + tion. + + tags + tags + List the tags used in the journal, or their values. + + This command lists the tag names used in the journal, whether on trans- + actions, postings, or account declarations. + + With a TAGREGEX argument, only tag names matching this regular expres- + sion (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. + + test + 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). + + About add-on commands + Add-on commands are programs or scripts in your PATH + + o whose name starts with hledger- + + o whose name ends with a recognised file extension: .bat,.com,.exe, + .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none + + o and (on unix, mac) which are executable by the current user. + + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger library + functions that built-in commands use for command-line options, parsing + and reporting. Some experimental/example add-on scripts can be found + in the hledger repo's bin/ directory. + + 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 + +JOURNAL FORMAT + hledger's default file format, representing a General Journal. + + hledger's usual data source is a plain text file containing journal + entries in hledger journal format. This file represents a standard + accounting general journal. I use file names ending in .journal, but + that's not required. The journal file contains a number of transaction + entries, each describing a transfer of money (or any commodity) between + two or more named accounts, in a simple format readable by both hledger + and humans. + + hledger's journal format is a compatible subset, mostly, of ledger's + journal format, so hledger can work with compatible ledger journal + files as well. It's safe, and encouraged, to run both hledger and + ledger on the same journal file, eg to validate the results you're get- + ting. + + You can use hledger without learning any more about this file; just use + the add or web 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 configura- + tion at hledger.org for the full list. + + Here's a description of each part of the file format (and hledger's + data model). These are mostly in the order you'll use them, but in + some cases related concepts have been grouped together for easy refer- + ence, or linked before they are introduced, so feel free to skip over + anything that looks unnecessary right now. + + 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 sim- + ple date in column 0. This can be followed by any of the following + optional fields, separated by spaces: + + o a status character (empty, !, or *) + + o a code (any short number or text, enclosed in parentheses) + + o a description (any remaining text until end of line or a semicolon) + + o a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + + o 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 + + Dates + 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 cur- + rent transaction, the default year set with a default year 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.) + + Secondary dates + Real-life transactions sometimes involve more than one date - eg the + date you write a cheque, and the date it clears in your bank. When you + want to model this, for more accurate daily balances, you can specify + individual posting dates. + + Or, you can use the older secondary date feature (Ledger calls it aux- + iliary date or effective date). Note: we support this for compatibil- + ity, but I usually recommend avoiding this feature; posting dates are + almost always clearer and simpler. + + 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", as shown here: + + 2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + + $ hledger register checking + 2010-02-23 movie ticket assets:checking $-10 $-10 + + $ hledger register checking --date2 + 2010-02-19 movie ticket assets:checking $-10 $-10 + + Posting dates + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) + like date:DATE. This is probably the best way to control posting dates + precisely. Eg in this example the expense should appear in May + reports, and the deduction from checking should be reported on 6/1 for + easy bank reconciliation: + + 2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + + $ hledger -f t.j register food + 2015-05-30 expenses:food $10 $10 + + $ hledger -f t.j register checking + 2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. You can set the secondary date + similarly, with date2:DATE2. The date: or date2: tags must have a + valid simple date value if they are present, eg a date: tag with no + value is not allowed. + + Ledger's earlier, more compact bracketed date syntax is also supported: + [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any + square-bracketed sequence of the 0123456789/-.= characters in this way. + With this syntax, DATE infers its year from the transaction and DATE2 + infers its year from DATE. + + Status + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction + description or posting account name, separated from it by a space, + indicating one of three statuses: + + + + + mark status + ------------------ + unmarked + ! pending + * cleared + + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags; or the status:, status:!, and + status:* queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" state + is called "uncleared". As of hledger 1.3 we have renamed it to + unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching pend- + ing, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with + real-world accounts. Some editor modes provide highlighting and short- + cuts for working with status. Eg in Emacs ledger-mode, you can toggle + transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to you. + Here's one suggestion: + + + status meaning + -------------------------------------------------------------------------- + uncleared recorded but not yet reconciled; needs review + pending tentatively reconciled (if needed, eg during a big reconcil- + iation) + cleared complete, reconciled as far as possible, and considered cor- + rect + + With this scheme, you would use -PC to see the current balance at your + bank, -U to see things which will probably hit your bank soon (like + uncashed checks), and no flags to see the most up-to-date state of your + finances. + + 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. + + Description + A transaction's description is the rest of the line following the date + and status mark (or until a comment begins). Sometimes called the + "narration" in traditional bookkeeping, it can be used for whatever you + wish, or left blank. Transaction descriptions can be queried, unlike + comments. + + Payee and note + You can optionally include a | (pipe) character in descriptions to sub- + divide 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. + + Comments + Lines in the journal beginning with a semicolon (;) or hash (#) or star + (*) are comments, and will be ignored. (Star comments cause org-mode + nodes to be ignored, allowing emacs users to fold and navigate their + journals with org-mode or orgstruct-mode.) + + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. + Transaction and posting comments must begin with a semicolon (;). + + Some examples: + + # a file comment + ; another file comment + * also a file comment, useful in org/orgstruct mode + + comment + A multiline file comment, which continues + until a line containing just "end comment" + (or end of file). + end comment + + 2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 + ; a file comment (because not indented) + + You can also comment larger regions of a file using comment and end + comment directives. + + Tags + Tags are a way to add extra labels or labelled data to postings and + transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full + colon, written inside a transaction or posting comment line: + + 2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the + next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or new- + lines. Ending at commas means you can write multiple short tags on one + line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + o "a comment containing" is just comment text, not a tag + + o "tag1" is a tag with no value + + o "tag2" is another tag, whose value is "some value ..." + + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, third- + tag) and the posting has four (those plus posting-tag): + + 1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values + are simple strings. + + Postings + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or + tab (2 or 4 spaces is common), followed by: + + o (optional) a status character (empty, !, or *), followed by a space + + o (required) an account name (any text, optionally containing single + spaces, until end of line or a double space) + + o (optional) two or more spaces or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are + being removed. + + The amounts within a transaction must always sum up to zero. As a con- + venience, one amount may be left blank; it will be inferred so as to + balance the transaction. + + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the + amount, the amount will be considered part of the account name. + + Virtual postings + A posting with a parenthesised 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 accounting, 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: + + 1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with a bracketed 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: + + 1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance + + Ordinary non-parenthesised, non-bracketed postings are called real + postings. You can exclude virtual postings from reports with the + -R/--real flag or real:1 query. + + Account names + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five top- + level accounts: assets, liabilities, revenue, expenses, and equity. + + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more + spaces (or newline). + + Account names can be aliased. + + Amounts + After the account name, there is usually an amount. (Important: + between account name and amount, there must be two or more spaces.) + + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- + tity"): + + 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 com- + modity 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 + + 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 jour- + nal 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 detail below. + + 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 punctu- + ation), 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.) + + 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, in JOURNAL FORMAT -> Declaring commodities. + 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 + + + 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: + + o The commodity directive for that commodity (including the no-symbol + commodity), if any. + + o The amounts in that commodity seen in the journal's transactions. + (Posting amounts only; prices and periodic or auto rules are ignored, + currently.) + + o The built-in fallback style, which looks like this: $1000.00. (Sym- + bol on the left, period decimal mark, two decimal places.) + + A style is inferred from journal amounts as follows: + + o Use the general style (decimal mark, symbol placement) of the first + amount + + o Use the first-seen digit group style (digit group mark, digit group + sizes), if any + + o Use the maximum number of decimal places of all. + + Transaction price amounts don't affect the commodity display style + directly, but occasionally they can do so indirectly (eg when a post- + ing's amount is inferred using a transaction price). 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. + + 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"). (Guaranteed since hledger 1.17.1; in older versions + this could vary if hledger was built with Decimal < 0.5.1.) + + Transaction prices + Within a transaction, you can note an amount's price in another commod- + ity. This can be used to document the cost (in a purchase) or selling + price (in a sale). For example, transaction prices are useful to + record purchases of a foreign currency. Note transaction prices are + fixed at the time of the transaction, and do not change over time. See + also market prices, which represent prevailing exchange rates on a cer- + tain date. + + There are several ways to record a transaction price: + + 1. Write the price per unit, as @ UNITPRICE after the amount: + + 2009/1/1 + assets:euros EUR100 @ $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 EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros EUR100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati- + bility with Ledger journals (Virtual posting costs), and is equiva- + lent to 1 in hledger. + + 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger, + this is equivalent to 2. + + Use the -B/--cost flag to convert amounts to their transaction price's + commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). + Eg here is how -B affects the balance report for the example above: + + $ hledger bal -N --flat + $-135 assets:dollars + EUR100 assets:euros + $ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last + amount. So if example 3's postings are reversed, while the transaction + is equivalent, -B shows something different: + + 2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros EUR100 ; for 100 euros + + $ hledger bal -N --flat -B + EUR-100 assets:dollars # <- the dollars' selling price + EUR100 assets:euros + + Lot prices, lot dates + Ledger allows another kind of price, lot price (four variants: {UNIT- + PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), + and/or a lot date ([DATE]) to be specified. These are normally used to + select a lot when selling investments. hledger will parse these, for + compatibility with Ledger journals, but currently ignores them. A + transaction price, lot price and/or lot date may appear in any order, + after the posting amount and before the balance assertion if any. + + 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 pro- + tect 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, below). + + Assertions and ordering + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- + ferent from Ledger, which sorts assertions only by parse order. (Also, + Ledger assertions do not see the accumulated effect of repeated post- + ings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder 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. + + 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. + + 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 bal- + ance from earlier files. This can be useful when you do not want prob- + lems 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. + + 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 1EUR + b $-1 + c -1EUR + + 2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1EUR + b 0 == $-1 + c 0 == -1EUR + + 2013/1/3 ; This assertion fails as 'a' also contains 1EUR + 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 1EUR + b + + 2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1EUR + + Assertions and prices + Balance assertions ignore transaction prices, and should normally be + written without one: + + 2019/1/1 + (a) $1 @ EUR1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- + ments do use them (see below). + + Assertions and subaccounts + 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 + + 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. + + 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: + + o assert the balance calculated with --auto, and always use --auto with + that file + + o or assert the balance calculated without --auto, and never use --auto + with that file + + o or avoid balance assertions on accounts affected by auto postings (or + avoid auto postings entirely). + + Assertions and precision + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- + tions. Balance assertion failure messages show exact amounts. + + Balance assignments + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when + setting opening balances: + + ; starting a new journal, set asset account balances + 2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + + ; no cash left; update balance, record any untracked spending as a generic expense + 2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the commodity + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- + ment). Note that using balance assignments makes your journal a little + less explicit; to know the exact amount posted, you have to run hledger + or do the calculations yourself, instead of just reading it. + + Balance assignments and prices + A transaction price in a balance assignment will cause the calculated + amount to have that price attached: + + 2019/1/1 + (a) = $1 @ EUR2 + + $ hledger print --explicit + 2019-01-01 + (a) $1 @ EUR2 = $1 @ EUR2 + + 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: + + o subdirective - Some directives support subdirectives, written + indented below the parent directive. + + o decimal mark - The character to interpret as a decimal mark (period + or comma) when parsing amounts of a commodity. + + o display style - How to display amounts of a commodity in output: sym- + bol side and spacing, digit groups, decimal mark, and number of deci- + mal places. + + Directives are not required when starting out with hledger, but you + will probably add some as your needs grow. Here is an overview of + directives by purpose: + + + purpose directives command line + options with sim- + ilar effect + ----------------------------------------------------------------------------- + READING/GENERATING DATA: + Declare a commodity's or file's commodity, D, decimal- + decimal mark to help parse mark + amounts accurately + Apply changes to the data while alias, apply account, --alias + parsing comment, D, Y + Inline extra data files include multiple + -f/--file's + Generate extra transactions or ~ + budget goals + Generate extra postings = + CHECKING FOR ERRORS: + Define valid entities to allow account, commodity, + stricter error checking payee + DISPLAYING REPORTS: + Declare accounts' display order account + and accounting type + Declare commodity display commodity, D -c/--commodity- + styles style + + And here are all the directives and their precise effects: + + + direc- effects ends + tive at + file + end? + ---------------------------------------------------------------------------------- + account Declares an account, for checking all entries in all files; + and its display order and type, for reports. Subdirectives: + any text, ignored. + alias Rewrites account names, in following entries until end of Y + current file or end aliases. + apply Prepends a common parent account to all account names, in Y + account following entries until end of current file or end apply + account. + comment Ignores part of the journal file, until end of current file Y + or end comment. + commod- Declares a commodity, for checking all entries in all files; N, Y + ity the decimal mark for parsing amounts of this commodity, for + following entries until end of current file; and its display + style, for reports. Takes precedence over D. Subdirectives: + format (alternate syntax). + D Sets a default commodity to use for no-symbol amounts, and Y + its decimal mark for parsing amounts of this commodity in + following entries until end of current file; and its display + style, for reports. + deci- Declares the decimal mark, for parsing amounts of all com- Y + mal- modities in following entries until next decimal-mark or end + mark of current file. Included files can override. Takes prece- + dence over commodity and D. + include Includes entries and directives from another file, as if they + were written inline. + payee Declares a payee name, for checking all entries in all files. + P Declares a market price for a commodity on some date, for + valuation reports. + Y Declares a year for yearless dates, for following entries Y + until end of current file. + ~ Declares a periodic transaction rule that generates future + (tilde) transactions with --forecast and budget goals with balance + --budget. + = Declares an auto posting rule that generates extra postings partly + (equals) on matched transactions with --auto, in current, parent, and + child files (but not sibling files, see #1212). + + 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 sta- + ble 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 direc- + tives do not affect parent or sibling files (see below). + + Comment blocks + A line containing just comment starts a commented region of the file, + and a line containing just end comment (or the end of the current file) + ends it. See also comments. + + Including other files + You can pull in the content of additional files by writing an include + 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, overrid- + ing the file extension (as described in hledger.1 -> Input files): + include timedot:~/notes/2020*.md. + + Default year + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. + Eg: + + Y2009 ; set default year to 2009 + + 12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + + Y2010 ; change default year to 2010 + + 2009/1/30 ; specifies the year, not affected + expenses 1 + assets + + 1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Declaring payees + The payee 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 + + Declaring the decimal mark + 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). + + Declaring commodities + 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 Com- + modity 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 dec- + imal 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 subdirec- + tive, 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 + + 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. + + 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 cur- + rently 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. + + Default commodity + The D directive sets a default commodity, to be used for any subsequent + commodityless amounts (ie, plain numbers) seen while parsing the jour- + nal. 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). + + The syntax is D AMOUNT. As with commodity, 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 + + If both commodity and D directives are found for a commodity, commodity + takes precedence for setting decimal mark and display style. + + If you are using D and also checking commodities, you will need to add + a commodity directive similar to the D. (The hledger check commodities + command expects commodity directives, and ignores D). + + Declaring market prices + The P directive declares a market price, which is an exchange rate + between two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, + cryptocurrency exchange, or the 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 EUR $1.35 + + # and $1.40 from 2010-01-01 onward: + P 2010-01-01 EUR $1.40 + + The -V, -X and --value flags use these market prices to show amount + values in another commodity. See Valuation. + + Declaring accounts + account directives can be used to declare accounts (ie, the places that + amounts are transferred from and to). Though not required, these dec- + larations can provide several benefits: + + o They can document your intended chart of accounts, providing a refer- + ence. + + o They control account display order in reports, allowing non-alpha- + betic sorting (eg Revenues to appear above Expenses). + + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and + incomestatement. + + o They can store other account information, as comments or as tags + which can be used to filter reports. + + o They help with account name completion (in hledger add, hledger-web, + hledger-iadd, ledger-mode, etc.) + + o In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + + The simplest form is just the word account followed by a hledger-style + account name, eg this account directive declares the assets:bank:check- + ing account: + + account assets:bank:checking + + Account error checking + By default, accounts come into existence when a transaction references + them by name. 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 + the error later, as an extra account in balance reports, or an incor- + rect 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: + + o The declaration is case-sensitive; transactions must use the correct + account name capitalisation. + + o The account directive's scope is "whole file and below" (see direc- + tives). 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. + + o Accounts can only be declared in journal files (but will affect + included files in other formats). + + o It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + Account comments + Comments, beginning with a semicolon, can be added: + + o on the same line, after two or more spaces (because ; is allowed in + account names) + + o on the next lines, indented + + An example of both: + + account assets:bank:checking ; same-line comment, note 2+ spaces required before ; + ; next-line comment + ; some tags, type:A, acctnum:12345 + + Compatibility note: same-line comments are not supported by Ledger or + hledger <1.13. + + Account subdirectives + We also allow (and ignore) Ledger-style indented subdirectives, just + for compatibility.: + + account assets:bank:checking + format blah blah ; <- subdirective, ignored + + Here is the full syntax of account directives: + + account ACCTNAME [;type:ACCTTYPE] [COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] + + 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: + + o A or Asset (things you own) + + o L or Liability (things you owe) + + o E or Equity (investment/ownership; balanced counterpart of assets & + liabilities) + + o R or Revenue (what you received money from, AKA income; technically + part of Equity) + + o X or Expense (what you spend money on; technically part of Equity) + + or, it can be (these are used less often): + + o C or Cash (a subtype of Asset, indicating liquid assets for the cash- + flow report) + + o V or Conversion (a subtype of Equity, for conversions (see CONVERSION + & COST).) + + 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. + + o 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. Note the Cash regexp changed + in hledger 1.24.99.2. + + 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 + + o If you declare any account types, it's a good idea to declare an + account for each of them, because a mixture of declared and name- + inferred types can disrupt certain reports. + + o Certain uses of account aliases can disrupt account types. See + Rewriting accounts > Aliases and account types. + + o 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. + + o For troubleshooting, you can list accounts and their types with: + + $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] + + Account display order + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web + sidebar. By default accounts are listed in alphabetical order. But if + you have these account directives in the journal: + + account assets + account liabilities + account equity + account revenues + account expenses + + you'll see those accounts displayed in declaration order, not alphabet- + ically: + + $ hledger accounts -1 + assets + liabilities + equity + revenues + expenses + + Undeclared accounts, if any, are displayed last, in alphabetical order. + + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, + 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: + + o you will sometimes declare parent accounts (eg account other above) + that you don't intend to post to, just to customize their display + order + + o sibling accounts stay together (you couldn't display x:y in between + a:b and a:c). + + Rewriting accounts + You can define account alias rules which rewrite your account names, or + parts of them, before generating reports. This can be useful for: + + o expanding shorthand account names to their full form, allowing easier + data entry and a less verbose journal + + o adapting old journals to your current chart of accounts + + o experimenting with new account organisations, like a new hierarchy + + o combining two accounts into one, eg to see their sum or difference on + one line + + o 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 cor- + rectly, but you can also generate invalid account names with them; more + on this below. + + See also Rewrite account names. + + Basic aliases + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its + included files (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. Sub- + accounts are also affected. Eg: + + alias checking = assets:bank:wells fargo:checking + ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + Regex aliases + There is also a more powerful variant that uses a regular expression, + 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. + + 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: + + o the nearest alias declaration before/above the entry is applied first + + o the next alias before/above that will be be applied next, and so on + + o aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- + pendent 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. + + 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 + + end aliases + You can clear (forget) all currently defined aliases (seen in the jour- + nal so far, or defined on the command line) with this directive: + + end aliases + + 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 exam- + ple, 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 + + 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, renam- + ing 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 + + Default parent account + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and + end apply account directives like so: + + apply account home + + 2010/1/1 + food $10 + cash + + end apply account + + which is equivalent to: + + 2010/01/01 + home:food $10 + home:cash $-10 + + If end apply account is omitted, the effect lasts to the end of the + file. Included files are also affected, eg: + + apply account business + include biz.journal + end apply account + apply account personal + include personal.journal + + Prior to hledger 1.0, legacy account and end spellings were also sup- + ported. + + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent + account. + + Periodic transactions + Periodic transaction rules describe transactions that recur. They + allow hledger to generate temporary future transactions to help with + forecasting, so you don't have to write out each one in the journal, + and it's easy to try out different forecasts. + + 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-fore- + casted 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. + + Periodic transaction rules also have a second meaning: they are used to + define budget goals, shown in budget reports. + + 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.): + + ~ monthly + expenses:rent $2000 + assets:bank:checking + + There is an additional constraint on the period expression: the start + date must fall on a natural boundary of the interval. Eg monthly from + 2018/1/1 is valid, but monthly from 2018/1/15 is not. + + 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. + + 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 acciden- + tally 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, + + o Do write two spaces between your period expression and your transac- + tion description, if any. + + o Don't accidentally write two spaces in the middle of your period + expression. + + Forecasting with periodic transactions + The --forecast flag activates any periodic transaction rules in the + journal. These will generate temporary additional transactions, usu- + ally 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-transac- + tion:, which you can use to reliably match transactions generated "just + now" (rather than printed 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: + + o the start date provided within --forecast's argument, if any + + o otherwise, the later of + + o the report start date, if specified (with -b/-p/date:) + + o the day after the latest ordinary transaction in the journal, if + any + + o otherwise today. + + It ends on: + + o the end date provided within --forecast's argument, if any + + o otherwise, the report end date, if specified (with -e/-p/date:) + + o 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: + + o 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. + + o 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: + + o You must use = between flag and argument; a space won't work. + + o The period expression can specify the forecast period's start date, + end date, or both. See also Report start & end date. + + o The period expression should not specify a report interval. (Each + periodic transaction rule specifies its own interval.) + + Some examples: --forecast=202001-202004, --forecast=jan-, --fore- + cast=2021. + + Budgeting with periodic transactions + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- + pared in budget reports. + + See also: Budgeting and Forecasting. + + + Auto postings + "Automated postings" or "auto postings" are extra postings which get + added automatically to transactions which match certain queries, + defined by "auto posting rules", when you use the --auto flag. + + 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 match- + ing), followed by a query (which matches existing postings), and each + "posting" line describes a posting to be generated, and the posting + amounts can be: + + o a normal amount with a commodity symbol, eg $2. This will be used + as-is. + + o a number, eg 2. The commodity symbol (if any) from the matched post- + ing will be added to this. + + o 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. + + o 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 + + 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). + + 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. + + Auto postings and transaction balancing / inferred amounts / balance asser- + tions + Currently, auto postings are added: + + o after missing amounts are inferred, and transactions are checked for + balancedness, + + o but before balance assertions are checked. + + Note this means that journal entries must be balanced both before and + after auto postings are added. This changed in hledger 1.12+; see #893 + for background. + + 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. + + Auto posting tags + Automated postings will have some extra tags: + + o generated-posting:= QUERY - shows this was generated by an auto post- + ing rule, and the query + + o _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: + + o modified: - this transaction was modified + + o _modified: - a hidden tag not appearing in the comment; this transac- + tion was modified "just now". + +CSV FORMAT + How hledger reads CSV data, and the CSV rules file format. + + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records as if they were journal + files, automatically converting each CSV record into a transaction. + + (To learn about writing CSV, see CSV output.) + + We describe each CSV file's format with a corresponding rules file. By + default this is named like the CSV file with a .rules extension added. + Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the + same directory as FILE.csv. You can specify a different rules file + with the --rules-file option. If a rules file is not found, hledger + will create a sample rules file, which you'll need to adjust. + + This file contains rules describing the CSV data (header line, fields + layout, date format etc.), and how to construct hledger journal entries + (transactions) from it. Often there will also be a list of conditional + rules for categorising transactions based on their descriptions. + Here's an overview of the CSV rules; these are described more fully + below, after the examples: + + + skip skip one or more header lines or matched CSV + records + fields list name CSV fields, assign them to hledger + fields + field assignment assign a value to one hledger field, with + interpolation + Field names hledger field names, used in the fields list + and field assignments + separator a custom field separator + if block apply some rules to CSV records matched by + patterns + if table apply some rules to CSV records matched by + patterns, alternate syntax + end skip the remaining CSV records + date-format how to parse dates in CSV records + decimal-mark the decimal mark used in CSV amounts, if + ambiguous + newest-first disambiguate record order when there's only + one date + include inline another CSV rules file + balance-type choose which type of balance assignments to + use + + Note, for best error messages when reading CSV files, use a .csv, .tsv + or .ssv file extension or file prefix - see File Extension below. + + There's an introductory Convert CSV files tutorial on hledger.org. + + Examples + Here are some sample hledger CSV rules files. See also the full col- + lection at: + https://github.com/simonmichael/hledger/tree/master/examples/csv + + Basic + 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 + + Default account names are chosen, since we didn't set them. + + 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 neces- + sary 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 read- + ing directly from CSV, but they will be checked if these entries are + imported into a journal file. + + Amazon + Here we convert amazon.com order history, and use an if block to gener- + ate 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 + + 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: + + CSV rules + The following kinds of rule can appear in the rules file, in any order. + Blank lines and lines beginning with # or ; are ignored. + + skip + skip N + + The word "skip" followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines preceding the CSV data. + (Empty/blank lines are skipped automatically.) You'll need this when- + ever your CSV data contains header lines. + + It also has a second purpose: it can be used inside if blocks to ignore + certain CSV records (described below). + + fields list + fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word "fields" followed by comma-separated field + names) is the quick way to assign CSV field values to hledger fields. + (The other way is field assignments, see below.) A fields list does + does two things: + + 1. It names the CSV fields. This is optional, but can be convenient + later for interpolating them. + + 2. Whenever you use a standard hledger field name (defined below), the + CSV value is assigned to that part of the hledger 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 + + Tips: + + o The fields list always use commas, even if your CSV data uses another + separator character. + + o Currently there must be least two items in the list (at least one + comma). + + o Field names may not contain spaces. Spaces before/after field names + are optional. + + o Field names may contain _ (underscore) or - (hyphen). + + o If the CSV contains column headings, it's a good idea to use these, + suitably modified, as the basis for your field names (eg lower-cased, + with underscores instead of spaces). + + o If some heading names match standard hledger fields, but you don't + want to set the hledger fields directly, alter those names, eg by + appending an underscore. + + o Fields you don't care about can be given a dummy name (eg: _ ), or no + name. + + field assignment + HLEDGERFIELDNAME 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 inter- + polate CSV fields, referenced by their 1-based position in the CSV + record (%N), or by the name they were given in the fields list (%CSV- + FIELDNAME). + + 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: + + o Interpolation strips outer whitespace (so a CSV value like " 1 " + becomes 1 when interpolated) (#1051). + + o Interpolations always refer to a CSV field - you can't interpolate a + hledger field. (See Referencing other fields below). + + Field names + Here are the standard hledger field (and pseudo-field) names, which you + can use in a fields list and in field assignments. For more about the + transaction parts they refer to, see Transactions. + + date field + Assigning to date sets the transaction date. + + date2 field + date2 sets the transaction's secondary date, if any. + + status field + status sets the transaction's status, if any. + + code field + code sets the transaction's code, if any. + + description field + description sets the transaction's description, if any. + + comment field + comment sets the transaction's comment, if any. + + commentN, where N is a number, sets the Nth posting's comment. + + Tips: + + o You can assign multi-line comments by writing literal \n in the code. + A comment starting with \n will begin on a new line. + + o Comments can contain tags, as usual. + + 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, and in conditional blocks. + + 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"). + + amount field + 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. + + amountN-in and amountN-out can be used instead, if the CSV uses sepa- + rate fields for debits and credits (inflows and outflows). hledger + assumes both of these CSV fields are unsigned, and will automatically + negate the "-out" value. If they are signed, see "Setting amounts" + below. + + amount, or amount-in and amount-out are a legacy mode, to keep pre- + hledger-1.17 CSV rules files working (and for occasional convenience). + They are suitable only for two-posting transactions; they set both + posting 1's and posting 2's amount. Posting 2's amount will be + negated, and also converted to cost if there's a transaction price. + + If you have an existing rules file using the unnumbered form, you might + want to use the numbered form in certain conditional blocks, without + having to update and retest all the old rules. To facilitate this, + posting 1 ignores amount/amount-in/amount-out if any of + amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them + if any of amount2/amount2-in/amount2-out are assigned, avoiding con- + flicts. + + 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. + + 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. + + separator + You can use the separator rule to read other kinds of character-sepa- + rated 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 automat- + ically, and you won't need this rule. + + if block + if MATCHER + RULE + + if + MATCHER + MATCHER + MATCHER + RULE + RULE + + Conditional blocks ("if blocks") are a block of rules that are applied + only to CSV records which match certain patterns. They are often used + for customising account names based on transaction descriptions. + + Matching the whole record + Each MATCHER can be a record matcher, which looks like this: + + REGEX + + REGEX is a case-insensitive regular expression that tries to match any- + where within the CSV record. It is a POSIX ERE (extended regular + expression) that also supports GNU word boundaries (\b, \B, \<, \>), + and nothing else. If you have trouble, be sure to check our doc: + https://hledger.org/hledger.html#regular-expressions + + Important note: the record that is matched is not the original record, + but a synthetic one, with any enclosing double quotes (but not enclos- + ing whitespace) removed, and always comma-separated (which means that a + field containing a comma will appear like two fields). Eg, if the + original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will + actually see 2020-01-01,Acme, Inc., 1,000). + + Matching individual fields + Or, MATCHER can be a field matcher, like this: + + %CSVFIELD REGEX + + which matches just the content of a particular CSV field. CSVFIELD is + a percent sign followed by the field's name or column number, like + %date or %1. + + Combining matchers + A single matcher can be written on the same line as the "if"; or multi- + ple matchers can be written on the following lines, non-indented. Mul- + tiple matchers are OR'd (any one of them can match), unless one begins + with an & symbol, in which case it is AND'ed with the previous matcher. + + if + MATCHER + & MATCHER + RULE + + Rules applied on successful match + After the patterns there should be one or more rules to apply, all + indented by at least one space. Three kinds of rule are allowed in + conditional blocks: + + o field assignments (to set a hledger field) + + o skip (to skip the matched CSV record) + + o end (to skip all remaining CSV records). + + Examples: + + # if the CSV record contains "groceries", set account2 to "expenses:groceries" + if groceries + account2 expenses:groceries + + # if the CSV record contains any of these patterns, set account2 and comment as shown + if + monthly service fee + atm transaction fee + banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + if table + if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn + MATCHER1,VALUE11,VALUE12,...,VALUE1n + MATCHER2,VALUE21,VALUE22,...,VALUE2n + MATCHER3,VALUE31,VALUE32,...,VALUE3n + + + Conditional tables ("if tables") are a different syntax to specify + field assignments that will be applied only to CSV records which match + certain patterns. + + MATCHER could be either field or record matcher, as described above. + When MATCHER matches, values from that row would be assigned to the CSV + fields named on the if line, in the same order. + + Therefore if table is exactly equivalent to a sequence of of if blocks: + + if MATCHER1 + CSVFIELDNAME1 VALUE11 + CSVFIELDNAME2 VALUE12 + ... + CSVFIELDNAMEn VALUE1n + + if MATCHER2 + CSVFIELDNAME1 VALUE21 + CSVFIELDNAME2 VALUE22 + ... + CSVFIELDNAMEn VALUE2n + + if MATCHER3 + CSVFIELDNAME1 VALUE31 + CSVFIELDNAME2 VALUE32 + ... + CSVFIELDNAMEn VALUE3n + + Each line starting with MATCHER should contain enough (possibly empty) + values for all the listed fields. + + Rules would be checked and applied in the order they are listed in the + table and, like with if blocks, later rules (in the same or another ta- + ble) or if blocks could override the effect of any rule. + + Instead of ',' you can use a variety of other non-alphanumeric charac- + ters as a separator. First character after if is taken to be the sepa- + rator for the rest of the table. It is the responsibility of the user + to ensure that separator does not occur inside MATCHERs and values - + there is no way to escape separator. + + 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 + + end + This rule can be used inside if blocks (only), to make hledger stop + reading this CSV file and move on to the next input file, or to command + execution. Eg: + + # ignore everything following the first empty record + if ,,,, + end + + 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 date + parsing pattern, which 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 + + For the supported strptime syntax, see: + https://hackage.haskell.org/package/time/docs/Data-Time-For- + mat.html#v:formatTime + + Note that although you can parse date-times which include a time zone, + that time zone is ignored; it will not change the date that is parsed. + This means when reading CSV data with times not in your local time + zone, dates can be "off by one". + + 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. + + newest-first + hledger always sorts the generated transactions by date. Transactions + on the same date should appear in the same order as their CSV records, + as hledger can usually auto-detect whether the CSV's normal order is + oldest first or newest first. But if all of the following are true: + + o the CSV might sometimes contain just one day of data (all records + having the same date) + + o the CSV records are normally in reverse chronological order (newest + at the top) + + o and you care about preserving the order of same-day transactions + + then, you should add the newest-first rule as a hint. Eg: + + # tell hledger explicitly that the CSV is normally newest first + newest-first + + 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 + + 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 + + Tips + 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. + + Valid CSV + hledger accepts CSV conforming to RFC 4180. When CSV values are + enclosed in quotes, note: + + o they must be double quotes (not single quotes) + + o spaces outside the quotes are not allowed + + File Extension + To help hledger identify the format and show the right error messages, + CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv + filename extension. Or, the file path should be prefixed with csv:, + ssv: or tsv:. Eg: + + $ hledger -f foo.ssv print + + or: + + $ cat foo | hledger -f ssv:- foo + + You can override the file extension with a separator rule if needed. + See also: Input files in the hledger manual. + + 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. + + Valid transactions + After reading a CSV file, hledger post-processes and validates the gen- + erated 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 + + 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: + + o https://hledger.org/cookbook.html#setups-and-workflows + + o https://plaintextaccounting.org -> data import/conversion + + Setting amounts + Some tips on using the amount-setting rules discussed above. + + Here are the ways to set a posting's amount: + + 1. If the CSV has a single amount field: + Assign (via a fields list or a field assignment) to amountN. This sets + the Nth posting's amount. N is usually 1 or 2 but can go up to 99. + + 2. If the CSV has separate amount fields for debit & credit (in & out): + + a. If both fields are unsigned: + Assign to amountN-in and amountN-out. This sets posting N's amount + to whichever of these has a non-zero value, and negates the "-out" + value. + + b. If either field is signed (can contain a minus sign): + Use a conditional rule to flip the sign (of non-empty values). + Since hledger always negates amountN-out, if it was already nega- + tive, we must undo that by negating once more (but only if the + field is non-empty): + + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. If both fields, or neither field, can contain a non-zero value: + hledger normally expects exactly one of the fields to have a non- + zero value. Eg, the amountN-in/amountN-out rules would reject + value pairs like these: + + "", "" + "0", "0" + "1", "none" + + So, use smarter conditional rules to set the amount from the appro- + priate field. Eg, these rules would make it use only the value + containing non-zero digits, handling the above: + + 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: + Assign to amount (or to amount-in and amount-out). (This is the legacy + numberless syntax, which sets amount1 and amount2 and converts amount2 + to cost.) + + 4. If the CSV has the balance instead of the transaction amount: + Assign to balanceN, which sets posting N's amount indirectly via a bal- + ance assignment. (Old syntax: balance, equivalent to balance1.) + + o If hledger guesses the wrong default account name: + When setting the amount via balance assertion, hledger may guess + the wrong default account name. So, set the account name explic- + itly, eg: + + fields date, description, balance1 + account1 assets:checking + + Amount signs + There is some special handling for amount signs, to simplify parsing + and sign-flipping: + + o If an amount value begins with a plus sign: + that will be removed: +AMT becomes AMT + + o If an amount value is parenthesised: + it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT + + o 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 + + o If an amount value contains just a sign (or just a set of parenthe- + ses): + that is removed, making it an empty value. "+" or "-" or "()" becomes + "". + + 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. + + 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 deci- + mal 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). + + 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 lit- + eral "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 + + How CSV rules are evaluated + Here's how to think of CSV rules being evaluated (if you really need + to). First, + + o 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: + + o skip (at top level) + + o date-format + + o newest-first + + o fields - names the CSV fields, optionally sets up initial assignments + to hledger fields + + Then for each CSV record in turn: + + o 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. + + o 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. + + o compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELDNAME references), or a + default + + o generate a synthetic hledger transaction 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. + +TIMECLOCK FORMAT + 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). + + i 2015/03/30 09:00:00 some:account name optional description after two spaces + o 2015/03/30 09:20:00 + i 2015/03/31 22:21:45 another account + o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For + the above time log, hledger print generates these journal entries: + + $ hledger -f t.timeclock print + 2015-03-30 * optional description after two spaces + (some:account name) 0.33h + + 2015-03-31 * 22:21-23:59 + (another account) 1.64h + + 2015-04-01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + + $ hledger -f sample.timeclock balance # current time balances + $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 + $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + o use emacs and the built-in timeclock.el, or the extended timeclock- + x.el and perhaps the extras in ledgerutils.el + + o at the command line, use these bash aliases: shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" + + o or use the old ti and to scripts in the ledger 2.x repository. These + rely on a "timeclock" executable which I think is just the ledger 2 + executable renamed. + +TIMEDOT FORMAT + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is + + o convenient for quick, approximate, and retroactive time logging + + o 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: + + o 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 + + o a common transaction description for this day + + o a common transaction comment for this day, after a semicolon (;). + + After the date line are zero or more optionally-indented time transac- + tion lines, consisting of: + + o an account name - any word or phrase, usually a hledger-style account + name. + + o two or more spaces - a field separator, required if there is an + amount (as in journal format). + + o a timedot amount - dots representing quarter hours, or a number rep- + resenting hours. + + o an optional comment beginning with semicolon. This is ignored. + + In more detail, timedot amounts can be: + + o dots: zero or more period characters, each representing one quarter- + hour. Spaces are ignored and can be used for grouping. Eg: .... .. + + o a number, representing hours. Eg: 1.5 + + o 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.: + + o Lines beginning with # or ;, and blank lines, are ignored. + + o Lines not ending with a double-space and amount are parsed as trans- + actions with zero amount. (Most hledger reports hide these by + default; add -E to see them.) + + o One or more stars (*) followed by a space, at the start of a line, is + ignored. So date lines or time transaction lines can also be Org- + mode headlines. + + o All Org-mode headlines before the first date line are ignored. + + 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. + +COMMON TASKS + Here are some quick examples of how to do some basic tasks with + hledger. For more details, see the reference section below, the + hledger_journal(5) manual, or the more extensive docs at + https://hledger.org. + + Getting help + $ hledger # show available commands + $ hledger --help # show common options + $ hledger CMD --help # show common and command options, and command help + $ hledger help # show available manuals/topics + $ hledger help hledger # show hledger manual, as info/man/text (auto-chosen) + $ hledger help journal -m # show the journal topic, as a man page scrolled to that section + $ hledger help --help # show more detailed help for the help command + + Find more docs, chat, mail list, reddit, issue tracker: + https://hledger.org/support.html-feedback + + Constructing command lines + hledger has an extensive and powerful command line interface. We + strive to keep it simple and ergonomic, but you may run into one of the + confusing real world details described in OPTIONS, below. If that hap- + pens, here are some tips that may help: + + o command-specific options must go after the command (it's fine to put + all options there) (hledger CMD OPTS ARGS) + + o running add-on executables directly simplifies command line parsing + (hledger-ui OPTS ARGS) + + o enclose "problematic" args in single quotes + + o if needed, also add a backslash to hide regular expression metachar- + acters from the shell + + o to see how a misbehaving command is being parsed, add --debug=2. + + 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 () + + 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 bal- + ances on this date. Here are two ways to do it: + + o 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. + + o 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 + + 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 + + Reconciling + Periodically you should reconcile - compare your hledger-reported bal- + ances 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 dis- + crepancies. + + 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 check- + ing -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 trans- + action 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 --reg- + ister 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 com- + mit: + + $ git commit -m 'txns' 2020.journal + + 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 --flat -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 --flat -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 **** + + 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. + +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 file format + differences. + + On large data files, hledger is slower and uses more memory than + Ledger. + +TROUBLESHOOTING + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug + tracker): + + Successfully installed, but "No command 'hledger' found" + stack and cabal install binaries into a special directory, which should + be added to your PATH environment variable. Eg on unix-like systems, + that is ~/.local/bin and ~/.cabal/bin respectively. + + I set a custom LEDGER_FILE, but hledger is still using the default file + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may + need to use export. Here's an explanation. + + Getting errors like "Illegal byte sequence" or "Invalid or incomplete + multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- + ment (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 sup- + ports 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 differ- + ence 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 + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2020 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + + +hledger-1.26.1 July 2022 HLEDGER(1)