diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -21,6 +21,26 @@ User-visible changes in the hledger command line tool and library. +# 1.32.1 2023-12-07 + +- Fixed: `import` with multiple files now updates .latest files correctly. (#2125) + +- Fixed: `print --round=hard` now properly pads/rounds amounts with inferred costs. (#2123) + +- CSV matcher syntax: mention that ! and & can't be used in the same line yet. (#2088) + +- Drop the "a difference of ..." line from balance assertion failure output. + I feel it made the message harder to read and isn't really necessary. + +- Declaring the empty payee name with `payee ""` now works, + to let `hledger check payees` accept payee-less transactions. + (#2119) + +- Built-in tags with special meaning like `type:` and `t:` are now implicitly declared, + so using type: in account declarations or generating t: with timedot letters + won't cause `hledger check tags` to fail. + (#2119) + # 1.32 2023-12-01 Breaking changes diff --git a/Hledger/Cli/Commands/Import.hs b/Hledger/Cli/Commands/Import.hs --- a/Hledger/Cli/Commands/Import.hs +++ b/Hledger/Cli/Commands/Import.hs @@ -54,10 +54,10 @@ case inputfiles of [] -> error' "please provide one or more input files as arguments" -- PARTIAL: fs -> do - enewjandlatestdates <- runExceptT $ readJournalFilesAndLatestDates iopts' fs - case enewjandlatestdates of + enewjandlatestdatesforfiles <- runExceptT $ readJournalFilesAndLatestDates iopts' fs + case enewjandlatestdatesforfiles of Left err -> error' err - Right (newj, latestdates) -> + Right (newj, latestdatesforfiles) -> case sortOn tdate $ jtxns newj of -- with --dry-run the output should be valid journal format, so messages have ; prepended [] -> do @@ -71,23 +71,27 @@ newts -> do if dryrun then do - -- first show imported txns + -- show txns to be imported printf "; would import %d new transactions from %s:\n\n" (length newts) inputstr mapM_ (T.putStr . showTransaction) newts + -- then check the whole journal with them added, if in strict mode when (strict_ iopts) $ strictChecks else do -- first check the whole journal with them added, if in strict mode when (strict_ iopts) $ strictChecks - -- then add (append) the transactions to the main journal file + + -- then append the transactions to the main journal file. -- XXX This writes unix line endings (\n), some at least, -- even if the file uses dos line endings (\r\n), which could leave -- mixed line endings in the file. See also writeFileWithBackupIfChanged. foldM_ (`journalAddTransaction` opts) j newts -- gets forced somehow.. (how ?) + printf "imported %d new transactions from %s to %s\n" (length newts) inputstr (journalFilePath j) - -- and finally update the .latest files - mapM_ (saveLatestDates latestdates . snd . splitReaderPrefix) fs + + -- and if we got this far, update each file's .latest file + saveLatestDatesForFiles latestdatesforfiles where -- add the new transactions to the journal in memory and check the whole thing diff --git a/Hledger/Cli/Commands/Print.hs b/Hledger/Cli/Commands/Print.hs --- a/Hledger/Cli/Commands/Print.hs +++ b/Hledger/Cli/Commands/Print.hs @@ -113,55 +113,52 @@ where styles0 = journalCommodityStyles j fmt = outputFormatFromOpts opts - render | fmt=="txt" = entriesReportAsText opts . styleAmounts styles - | fmt=="beancount" = entriesReportAsBeancount opts . styleAmounts styles - | fmt=="csv" = printCSV . entriesReportAsCsv . styleAmounts styles - | fmt=="tsv" = printTSV . entriesReportAsCsv . styleAmounts styles - | fmt=="json" = toJsonText . styleAmounts styles - | fmt=="sql" = entriesReportAsSql . styleAmounts styles - | otherwise = error' $ unsupportedOutputFormatError fmt -- PARTIAL: - -entriesReportAsText :: CliOpts -> EntriesReport -> TL.Text -entriesReportAsText = entriesReportAsTextHelper showTransaction - -entriesReportAsTextHelper :: (Transaction -> T.Text) -> CliOpts -> EntriesReport -> TL.Text -entriesReportAsTextHelper showtxn opts = - TB.toLazyText . foldMap (TB.fromText . showtxn . txntransform) - where - txntransform - -- Use the fully inferred and amount-styled/rounded transaction in the following situations: - -- with -x/--explicit: - | boolopt "explicit" (rawopts_ opts) = id - -- with --show-costs: - | opts ^. infer_costs = id - -- with -B/-V/-X/--value ("because of #551, and because of print -V valuing only one posting when there's an implicit txn price.") - | has (value . _Just) opts = id - -- Otherwise, keep the transaction's amounts close to how they were written in the journal. - | otherwise = transactionWithMostlyOriginalPostings + render | fmt=="txt" = entriesReportAsText . styleAmounts styles . map maybeoriginalamounts + | fmt=="beancount" = entriesReportAsBeancount . styleAmounts styles . map maybeoriginalamounts + | fmt=="csv" = printCSV . entriesReportAsCsv . styleAmounts styles + | fmt=="tsv" = printTSV . entriesReportAsCsv . styleAmounts styles + | fmt=="json" = toJsonText . styleAmounts styles + | fmt=="sql" = entriesReportAsSql . styleAmounts styles + | otherwise = error' $ unsupportedOutputFormatError fmt -- PARTIAL: + where + maybeoriginalamounts + -- Use the fully inferred and amount-styled/rounded transaction in the following situations: + -- with -x/--explicit: + | boolopt "explicit" (rawopts_ opts) = id + -- with --show-costs: + | opts ^. infer_costs = id + -- with -B/-V/-X/--value ("because of #551, and because of print -V valuing only one posting when there's an implicit txn price.") + | has (value . _Just) opts = id + -- Otherwise, keep the transaction's amounts close to how they were written in the journal. + | otherwise = transactionWithMostlyOriginalPostings -- | Replace this transaction's postings with the original postings if any, but keep the -- current possibly rewritten account names, and the inferred values of any auto postings. -- This is mainly for showing transactions with the amounts in their original journal format. transactionWithMostlyOriginalPostings :: Transaction -> Transaction transactionWithMostlyOriginalPostings = transactionMapPostings postingMostlyOriginal - --- Get the original posting if any, but keep the current (possibly rewritten) account name, --- and the amounts of any auto postings. -postingMostlyOriginal p = orig - { paccount = paccount p - , pamount = pamount $ if isGenerated then p else orig } where - orig = originalPosting p - isGenerated = "_generated-posting" `elem` map fst (ptags p) + postingMostlyOriginal p = orig + { paccount = paccount p + , pamount = pamount $ if isGenerated then p else orig } + where + orig = originalPosting p + isGenerated = "_generated-posting" `elem` map fst (ptags p) +entriesReportAsText :: EntriesReport -> TL.Text +entriesReportAsText = entriesReportAsTextHelper showTransaction + +entriesReportAsTextHelper :: (Transaction -> T.Text) -> EntriesReport -> TL.Text +entriesReportAsTextHelper showtxn = TB.toLazyText . foldMap (TB.fromText . showtxn) + -- In addition to rendering the transactions in (best effort) Beancount format, -- this generates an account open directive for each account name used -- (using the earliest transaction date). -entriesReportAsBeancount :: CliOpts -> EntriesReport -> TL.Text -entriesReportAsBeancount opts ts = +entriesReportAsBeancount :: EntriesReport -> TL.Text +entriesReportAsBeancount ts = -- PERF: gathers and converts all account names, then repeats that work when showing each transaction opendirectives <> "\n" <> - entriesReportAsTextHelper showTransactionBeancount opts ts + entriesReportAsTextHelper showTransactionBeancount ts where opendirectives | null ts = "" diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs --- a/Hledger/Cli/Utils.hs +++ b/Hledger/Cli/Utils.hs @@ -20,7 +20,6 @@ openBrowserOn, writeFileWithBackup, writeFileWithBackupIfChanged, - readFileStrictly, pivotByOpts, anonymiseByOpts, journalSimilarTransaction, @@ -29,7 +28,6 @@ ) where -import Control.Exception as C import Control.Monad.Except (ExceptT) import Control.Monad.IO.Class (liftIO) import Data.List @@ -222,9 +220,6 @@ -- overwrite it with this new text, or give an error. writeFileWithBackup :: FilePath -> String -> IO () writeFileWithBackup f t = backUpFile f >> writeFile f t - -readFileStrictly :: FilePath -> IO T.Text -readFileStrictly f = readFilePortably f >>= \s -> C.evaluate (T.length s) >> return s -- | Back up this file with a (incrementing) numbered suffix, or give an error. backUpFile :: FilePath -> IO () diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1 --- a/embeddedfiles/hledger-ui.1 +++ b/embeddedfiles/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "December 2023" "hledger-ui-1.32 " "hledger User Manuals" +.TH "HLEDGER-UI" "1" "December 2023" "hledger-ui-1.32.1 " "hledger User Manuals" @@ -12,7 +12,7 @@ .PD \f[CR]hledger ui -- [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s terminal interface, version 1.32. +This manual is for hledger\[aq]s terminal interface, version 1.32.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info --- a/embeddedfiles/hledger-ui.info +++ b/embeddedfiles/hledger-ui.info @@ -16,7 +16,7 @@ 'hledger-ui [OPTS] [QUERYARGS]' 'hledger ui -- [OPTS] [QUERYARGS]' - This manual is for hledger's terminal interface, version 1.32. See + This manual is for hledger's terminal interface, version 1.32.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -674,46 +674,46 @@  Tag Table: Node: Top223 -Node: OPTIONS1830 -Ref: #options1928 -Node: General help options2951 -Ref: #general-help-options3100 -Node: General input options3382 -Ref: #general-input-options3567 -Node: General reporting options4269 -Ref: #general-reporting-options4433 -Node: MOUSE7823 -Ref: #mouse7918 -Node: KEYS8155 -Ref: #keys8248 -Node: SCREENS12903 -Ref: #screens13001 -Node: Menu13581 -Ref: #menu13674 -Node: Cash accounts13869 -Ref: #cash-accounts14011 -Node: Balance sheet accounts14195 -Ref: #balance-sheet-accounts14376 -Node: Income statement accounts14496 -Ref: #income-statement-accounts14682 -Node: All accounts14846 -Ref: #all-accounts14992 -Node: Register15174 -Ref: #register15298 -Node: Transaction17582 -Ref: #transaction17705 -Node: Error19122 -Ref: #error19216 -Node: TIPS19460 -Ref: #tips19559 -Node: Watch mode19601 -Ref: #watch-mode19708 -Node: Debug output21167 -Ref: #debug-output21278 -Node: ENVIRONMENT21490 -Ref: #environment21600 -Node: BUGS21791 -Ref: #bugs21874 +Node: OPTIONS1832 +Ref: #options1930 +Node: General help options2953 +Ref: #general-help-options3102 +Node: General input options3384 +Ref: #general-input-options3569 +Node: General reporting options4271 +Ref: #general-reporting-options4435 +Node: MOUSE7825 +Ref: #mouse7920 +Node: KEYS8157 +Ref: #keys8250 +Node: SCREENS12905 +Ref: #screens13003 +Node: Menu13583 +Ref: #menu13676 +Node: Cash accounts13871 +Ref: #cash-accounts14013 +Node: Balance sheet accounts14197 +Ref: #balance-sheet-accounts14378 +Node: Income statement accounts14498 +Ref: #income-statement-accounts14684 +Node: All accounts14848 +Ref: #all-accounts14994 +Node: Register15176 +Ref: #register15300 +Node: Transaction17584 +Ref: #transaction17707 +Node: Error19124 +Ref: #error19218 +Node: TIPS19462 +Ref: #tips19561 +Node: Watch mode19603 +Ref: #watch-mode19710 +Node: Debug output21169 +Ref: #debug-output21280 +Node: ENVIRONMENT21492 +Ref: #environment21602 +Node: BUGS21793 +Ref: #bugs21876  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 @@ -9,7 +9,7 @@ hledger ui -- [OPTS] [QUERYARGS] DESCRIPTION - This manual is for hledger's terminal interface, version 1.32. See + This manual is for hledger's terminal interface, version 1.32.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -537,4 +537,4 @@ SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.32 December 2023 HLEDGER-UI(1) +hledger-ui-1.32.1 December 2023 HLEDGER-UI(1) diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1 --- a/embeddedfiles/hledger-web.1 +++ b/embeddedfiles/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER-WEB" "1" "December 2023" "hledger-web-1.32 " "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "December 2023" "hledger-web-1.32.1 " "hledger User Manuals" @@ -12,7 +12,7 @@ .PD \f[CR]hledger web -- [--serve|--serve-api] [OPTS] [ARGS]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s web interface, version 1.32. +This manual is for hledger\[aq]s web interface, version 1.32.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info --- a/embeddedfiles/hledger-web.info +++ b/embeddedfiles/hledger-web.info @@ -16,7 +16,7 @@ 'hledger-web [--serve|--serve-api] [OPTS] [ARGS]' 'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]' - This manual is for hledger's web interface, version 1.32. See also + This manual is for hledger's web interface, version 1.32.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -643,30 +643,30 @@  Tag Table: Node: Top225 -Node: OPTIONS2577 -Ref: #options2682 -Node: General help options5970 -Ref: #general-help-options6120 -Node: General input options6402 -Ref: #general-input-options6588 -Node: General reporting options7290 -Ref: #general-reporting-options7455 -Node: PERMISSIONS10845 -Ref: #permissions10984 -Node: EDITING UPLOADING DOWNLOADING12196 -Ref: #editing-uploading-downloading12377 -Node: RELOADING13211 -Ref: #reloading13345 -Node: JSON API13778 -Ref: #json-api13893 -Node: DEBUG OUTPUT19381 -Ref: #debug-output19506 -Node: Debug output19533 -Ref: #debug-output-119634 -Node: ENVIRONMENT20051 -Ref: #environment20170 -Node: BUGS20287 -Ref: #bugs20371 +Node: OPTIONS2579 +Ref: #options2684 +Node: General help options5972 +Ref: #general-help-options6122 +Node: General input options6404 +Ref: #general-input-options6590 +Node: General reporting options7292 +Ref: #general-reporting-options7457 +Node: PERMISSIONS10847 +Ref: #permissions10986 +Node: EDITING UPLOADING DOWNLOADING12198 +Ref: #editing-uploading-downloading12379 +Node: RELOADING13213 +Ref: #reloading13347 +Node: JSON API13780 +Ref: #json-api13895 +Node: DEBUG OUTPUT19383 +Ref: #debug-output19508 +Node: Debug output19535 +Ref: #debug-output-119636 +Node: ENVIRONMENT20053 +Ref: #environment20172 +Node: BUGS20289 +Ref: #bugs20373  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 @@ -9,41 +9,41 @@ hledger web -- [--serve|--serve-api] [OPTS] [ARGS] DESCRIPTION - This manual is for hledger's web interface, version 1.32. See also the - hledger manual for common concepts and file formats. + This manual is for hledger's web interface, version 1.32.1. See also + the hledger manual for common concepts and file formats. - hledger is a robust, user-friendly, cross-platform set of programs for - tracking money, time, or any other commodity, using double-entry ac- - counting and a simple, editable file format. hledger is inspired by - and largely compatible with ledger(1), and largely interconvertible + hledger is a robust, user-friendly, cross-platform set of programs for + tracking money, time, or any other commodity, using double-entry ac- + counting and a simple, editable file format. hledger is inspired by + and largely compatible with ledger(1), and largely interconvertible with beancount(1). - hledger-web is a simple web application for browsing and adding trans- - actions. It provides a more user-friendly UI than the hledger CLI or - hledger-ui TUI, showing more at once (accounts, the current account + hledger-web is a simple web application for browsing and adding trans- + actions. It provides a more user-friendly UI than the hledger CLI or + hledger-ui TUI, showing more at once (accounts, the current account register, balance charts) and allowing history-aware data entry, inter- active searching, and bookmarking. - hledger-web also lets you share a journal with multiple users, or even - the public web. There is no access control, so if you need that you - should put it behind a suitable web proxy. As a small protection - against data loss when running an unprotected instance, it writes a + hledger-web also lets you share a journal with multiple users, or even + the public web. There is no access control, so if you need that you + should put it behind a suitable web proxy. As a small protection + against data loss when running an unprotected instance, it writes a numbered backup of the main journal file (only) on every edit. - Like hledger, it reads from (and appends to) a journal file specified - by the LEDGER_FILE environment variable (defaulting to - $HOME/.hledger.journal); or you can specify files with -f options. It - can also read timeclock files, timedot files, or any CSV/SSV/TSV file + Like hledger, it reads from (and appends to) a journal file specified + by the LEDGER_FILE environment variable (defaulting to + $HOME/.hledger.journal); or you can specify files with -f options. It + can also read timeclock files, timedot files, or any CSV/SSV/TSV file with a date field. (See hledger(1) -> Input for details.) hledger-web can be run in three modes: o Transient mode (the default): your default web browser will be opened - to show the app if possible, and the app exits automatically after - two minutes of inactivity (no requests received and no open browser + to show the app if possible, and the app exits automatically after + two minutes of inactivity (no requests received and no open browser windows viewing it). - o With --serve: the app runs without stopping, and without opening a + o With --serve: the app runs without stopping, and without opening a browser. o With --serve-api: only the JSON API is served. @@ -53,7 +53,7 @@ OPTIONS Command-line options and arguments may be used to set an initial filter - on the data. These filter options are not shown in the web UI, but it + on the data. These filter options are not shown in the web UI, but it will be applied in addition to any search query entered there. hledger-web provides the following options: @@ -62,7 +62,7 @@ serve and log requests, don't browse or auto-exit after timeout --serve-api - like --serve, but serve only the JSON web API, without the + like --serve, but serve only the JSON web API, without the server-side web UI --host=IPADDR @@ -72,58 +72,58 @@ listen on this TCP port (default: 5000) --socket=SOCKETFILE - use a unix domain socket file to listen for requests instead of - a TCP socket. Implies --serve. It can only be used if the op- + use a unix domain socket file to listen for requests instead of + a TCP socket. Implies --serve. It can only be used if the op- erating system can provide this type of socket. --base-url=URL - set the base url (default: http://IPADDR:PORT). Note: affects - url generation but not route parsing. Can be useful if running + set the base url (default: http://IPADDR:PORT). Note: affects + url generation but not route parsing. Can be useful if running behind a reverse web proxy that does path rewriting. --file-url=URL set the static files url (default: BASEURL/static). hledger-web - normally serves static files itself, but if you wanted to serve - them from another server for efficiency, you would set the url + normally serves static files itself, but if you wanted to serve + them from another server for efficiency, you would set the url with this. --allow=view|add|edit - set the user's access level for changing data (default: add). - It also accepts sandstorm for use on that platform (reads per- + set the user's access level for changing data (default: add). + It also accepts sandstorm for use on that platform (reads per- missions from the X-Sandstorm-Permissions request header). - --test run hledger-web's tests and exit. hspec test runner args may + --test run hledger-web's tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help - By default the server listens on IP address 127.0.0.1, accessible only - to local requests. You can use --host to change this, eg --host + By default the server listens on IP address 127.0.0.1, accessible only + to local requests. You can use --host to change this, eg --host 0.0.0.0 to listen on all configured addresses. - Similarly, use --port to set a TCP port other than 5000, eg if you are + Similarly, use --port to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. Both of these options are ignored when --socket is used. In this case, - it creates an AF_UNIX socket file at the supplied path and uses that - for communication. This is an alternative way of running multiple - hledger-web instances behind a reverse proxy that handles authentica- - tion for different users. The path can be derived in a predictable + it creates an AF_UNIX socket file at the supplied path and uses that + for communication. This is an alternative way of running multiple + hledger-web instances behind a reverse proxy that handles authentica- + tion for different users. The path can be derived in a predictable way, eg by using the username within the path. As an example, nginx as - reverse proxy can use the variable $remote_user to derive a path from - the username used in a HTTP basic authentication. The following - proxy_pass directive allows access to all hledger-web instances that + reverse proxy can use the variable $remote_user to derive a path from + the username used in a HTTP basic authentication. The following + proxy_pass directive allows access to all hledger-web instances that created a socket in /tmp/hledger/: proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; - You can use --base-url to change the protocol, hostname, port and path + You can use --base-url to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within - a larger website. The default is http://HOST:PORT/ using the server's + a larger website. The default is http://HOST:PORT/ using the server's configured host address and TCP port (or http://HOST if PORT is 80). - With --file-url you can set a different base url for static files, eg + With --file-url you can set a different base url for static files, eg for better caching or cookie-less serving on high performance websites. - hledger-web also supports many of hledger's general options (and the + hledger-web also supports many of hledger's general options (and the hledger manual's command line tips also apply here): General help options @@ -146,7 +146,7 @@ $LEDGER_FILE or $HOME/.hledger.journal) --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: + Conversion rules file to use when reading CSV (default: FILE.rules) --separator=CHAR @@ -165,7 +165,7 @@ assignments) -s --strict - do extra error checking (check that all posted accounts are de- + do extra error checking (check that all posted accounts are de- clared) General reporting options @@ -193,7 +193,7 @@ multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax --date2 @@ -201,7 +201,7 @@ fects) --today=DATE - override today's date (affects relative smart dates, for + override today's date (affects relative smart dates, for tests/examples) -U --unmarked @@ -220,21 +220,21 @@ hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost convert amounts to their cost/selling amount at transaction time -V --market - convert amounts to their market value in default valuation com- + 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 + convert amounts to cost or market value, more flexibly than -B/-V/-X --infer-equity @@ -244,38 +244,38 @@ infer costs from conversion equity postings --infer-market-prices - use costs as additional market prices, as if they were P direc- + use costs as additional market prices, as if they were P direc- tives --forecast - generate transactions from periodic rules, between the latest - recorded txn and 6 months from today, or during the specified - PERIOD (= is required). Auto posting rules will be applied to - these transactions as well. Also, in hledger-ui make future- + generate transactions from periodic rules, between the latest + recorded txn and 6 months from today, or during the specified + PERIOD (= is required). Auto posting rules will be applied to + these transactions as well. Also, in hledger-ui make future- dated transactions visible. - --auto generate extra postings by applying auto posting rules to all + --auto generate extra postings by applying auto posting rules to all txns (not just forecast txns) --verbose-tags - add visible tags indicating transactions or postings which have + add visible tags indicating transactions or postings which have been generated/modified --commodity-style - Override the commodity style in the output for the specified + 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 + 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 + 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 @@ -284,13 +284,13 @@ Some reporting options can also be written as query arguments. PERMISSIONS - By default, hledger-web allows anyone who can reach it to view the + By default, hledger-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. You can restrict who can reach it by - o setting the IP address it listens on (see --host above). By default - it listens on 127.0.0.1, accessible to all users on the local ma- + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local ma- chine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -300,44 +300,44 @@ You can restrict what the users who reach it can do, by o using the --capabilities=CAP[,CAP..] flag when you start it, enabling - one or more of the following capabilities. The default value is + one or more of the following capabilities. The default value is view,add: o view - allows viewing the journal file and all included files o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or in- + o manage - allows editing, uploading or downloading the main or in- cluded files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it in- + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it in- cludes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -345,8 +345,8 @@ that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web also serves a JSON API that can - be used to get data or add new transactions. If you want the JSON API + In addition to the web UI, hledger-web also serves a JSON API that can + be used to get data or add new transactions. If you want the JSON API only, you can use the --serve-api flag. Eg: $ hledger-web -f examples/sample.journal --serve-api @@ -363,7 +363,7 @@ /accounttransactions/ACCOUNTNAME Eg, all account names in the journal (similar to the accounts command). - (hledger-web's JSON does not include newlines, here we use python to + (hledger-web's JSON does not include newlines, here we use python to prettify it): $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool @@ -404,25 +404,25 @@ "aprice": null, ... - Most of the JSON corresponds to hledger's data types; for details of - what the fields mean, see the Hledger.Data.Json haddock docs and click - on the various data types, eg Transaction. And for a higher level un- + Most of the JSON corresponds to hledger's data types; for details of + what the fields mean, see the Hledger.Data.Json haddock docs and click + on the various data types, eg Transaction. And for a higher level un- derstanding, see the journal docs. In some cases there is outer JSON corresponding to a "Report" type. To - understand that, go to the Hledger.Web.Handler.MiscR haddock and look - at the source for the appropriate handler to see what it returns. Eg + understand that, go to the Hledger.Web.Handler.MiscR haddock and look + at the source for the appropriate handler to see what it returns. Eg for /accounttransactions it's getAccounttransactionsR, returning a "ac- - countTransactionsReport ...". Looking up the haddock for that we can - see that /accounttransactions returns an AccountTransactionsReport, - which consists of a report title and a list of AccountTransactionsRe- + countTransactionsReport ...". Looking up the haddock for that we can + see that /accounttransactions returns an AccountTransactionsReport, + which consists of a report title and a list of AccountTransactionsRe- portItem (etc). - You can add a new transaction to the journal with a PUT request to - /add, if hledger-web was started with the add capability (enabled by + You can add a new transaction to the journal with a PUT request to + /add, if hledger-web was started with the add capability (enabled by default). The payload must be the full, exact JSON representation of a - hledger transaction (partial data won't do). You can get sample JSON - from hledger-web's /transactions or /accounttransactions, or you can + hledger transaction (partial data won't do). You can get sample JSON + from hledger-web's /transactions or /accounttransactions, or you can export it with hledger-lib, eg like so: .../hledger$ stack ghci hledger-lib @@ -518,28 +518,28 @@ "tstatus": "Unmarked" } - And here's how to test adding it with curl. This should add a new en- + And here's how to test adding it with curl. This should add a new en- try to your journal: $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json DEBUG OUTPUT Debug output - You can add --debug[=N] to the command line to log debug output. N + You can add --debug[=N] to the command line to log debug output. N ranges from 1 (least output, the default) to 9 (maximum output). Typi- - cally you would start with 1 and increase until you are seeing enough. - Debug output goes to stderr, interleaved with the requests logged on + cally you would start with 1 and increase until you are seeing enough. + Debug output goes to stderr, interleaved with the requests logged on stdout. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger-web --debug=3 2>hledger-web.log. ENVIRONMENT - LEDGER_FILE The main journal file to use when not specified with + LEDGER_FILE The main journal file to use when not specified with -f/--file. Default: $HOME/.hledger.journal. BUGS We welcome bug reports in the hledger issue tracker (shortcut: - http://bugs.hledger.org), or on the #hledger chat or hledger mail list + http://bugs.hledger.org), or on the #hledger chat or hledger mail list (https://hledger.org/support). Some known issues: @@ -564,4 +564,4 @@ SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.32 December 2023 HLEDGER-WEB(1) +hledger-web-1.32.1 December 2023 HLEDGER-WEB(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 --- a/embeddedfiles/hledger.1 +++ b/embeddedfiles/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2023" "hledger-1.32 " "hledger User Manuals" +.TH "HLEDGER" "1" "December 2023" "hledger-1.32.1 " "hledger User Manuals" @@ -23,7 +23,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP -This manual is for hledger\[aq]s command line interface, version 1.32. +This manual is for hledger\[aq]s command line interface, version 1.32.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! @@ -2796,6 +2796,8 @@ commodity 1 000 000.0000 ; the no-symbol commodity .EE .PP +Commodities do not have tags (tags in the comment will be ignored). +.PP A commodity directive\[aq]s sample amount must always include a period or comma decimal mark (this rule helps disambiguate decimal marks and digit group marks). @@ -2931,10 +2933,18 @@ Eg: .IP .EX -payee Whole Foods +payee Whole Foods ; a comment .EE .PP -Any indented subdirectives are currently ignored. +Payees do not have tags (tags in the comment will be ignored). +.PP +To declare the empty payee name, use \f[CR]\[dq]\[dq]\f[R]. +.IP +.EX +payee \[dq]\[dq] +.EE +.PP +Ledger-style indented subdirectives, if any, are currently ignored. .SS \f[CR]tag\f[R] directive \f[CR]tag TAGNAME\f[R] .PP @@ -4153,7 +4163,7 @@ else. If you have trouble, see \[dq]Regular expressions\[dq] in the hledger manual (https://hledger.org/hledger.html#regular-expressions). -.PP +.SS What matchers match With record matchers, it\[aq]s important to know that the record matched is not the original CSV record, but a modified one: separators will be converted to commas, and enclosing double quotes (but not enclosing @@ -4169,16 +4179,19 @@ .EX 2023-01-01,Acme, Inc., 1,000 .EE -.PP +.SS Combining matchers When an if block has multiple matchers, they are combined as follows: .IP \[bu] 2 By default they are OR\[aq]d (any one of them can match) .IP \[bu] 2 When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be -AND\[aq]ed with the previous matcher (both of them must match). +AND\[aq]ed with the previous matcher (both of them must match) +.IP \[bu] 2 +When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the +matcher is negated (it may not match). .PP -When a matcher is preceded by an exclamation mark (!), the matcher will -be negated, ie it will exclude CSV records that match. +Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and +\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher). .SS Match groups Matchers can define match groups: parenthesised portions of the regular expression which are available for reference in field assignments. diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -23,11491 +23,11519 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.32. -It also describes the common options, file formats and concepts used by -all hledger programs. It might accidentally teach you some -bookkeeping/accounting as well! You don't need to know everything in -here to use hledger productively, but when you have a question about -functionality, this doc should answer it. It is detailed, so do skip -ahead or skim when needed. You can read it on hledger.org, or as an -info manual or man page on your system. You can also get it from -hledger itself with -'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'. - - The main function of the hledger CLI is to read plain text files -describing financial transactions, crunch the numbers, and print a -useful report on the terminal (or save it as HTML, CSV, JSON or SQL). -Many reports are available, as subcommands. hledger will also detect -other 'hledger-*' executables as extra subcommands. - - hledger usually reads from (and appends to) a journal file specified -by the 'LEDGER_FILE' environment variable (defaulting to -'$HOME/.hledger.journal'); or you can specify files with '-f' options. -It can also read timeclock files, timedot files, or any CSV/SSV/TSV file -with a date field. - - Here is a small journal file describing one transaction: - -2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more -_accounts_: bank accounts, your wallet, revenue/expense categories, -people, etc. You can choose any account names you wish, using ':' to -indicate subaccounts. There must be at least two spaces between account -name and amount. Positive amounts are inflow to that account (_debit_), -negatives are outflow from it (_credit_). (Some reports show revenue, -liability and equity account balances as negative numbers as a result; -this is normal.) - - hledger's add command can help you add transactions, or you can -install other data entry UIs like hledger-web or hledger-iadd. For more -extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM -+ vim-ledger, or VS Code + hledger-vscode are some good choices (see -https://hledger.org/editors.html). - - To get started, run 'hledger add' and follow the prompts, or save -some entries like the above in '$HOME/.hledger.journal', then try -commands like: -'hledger print -x' -'hledger aregister assets' -'hledger balance' -'hledger balancesheet' -'hledger incomestatement'. -Run 'hledger' to list the commands. See also the "Starting a journal -file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -* Menu: - -* PART 1 USER INTERFACE:: -* Input:: -* Commands:: -* Options:: -* Command line tips:: -* Output:: -* Environment:: -* PART 2 DATA FORMATS:: -* Journal:: -* CSV:: -* Timeclock:: -* Timedot:: -* PART 3 REPORTING CONCEPTS:: -* Amount formatting parseability:: -* Time periods:: -* Depth:: -* Queries:: -* Pivoting:: -* Generating data:: -* Forecasting:: -* Budgeting:: -* Cost reporting:: -* Value reporting:: -* PART 4 COMMANDS:: -* PART 5 COMMON TASKS:: -* BUGS:: - - -File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: Top - -1 PART 1: USER INTERFACE -************************ - - -File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top - -2 Input -******* - -hledger reads one or more data files, each time you run it. You can -specify a file with '-f', like so - -$ hledger -f FILE print - - Files are most often in hledger's journal format, with the '.journal' -file extension ('.hledger' or '.j' also work); these files describe -transactions, like an accounting general journal. - - When no file is specified, hledger looks for '.hledger.journal' in -your home directory. - - But most people prefer to keep financial files in a dedicated folder, -perhaps with version control. Also, starting a new journal file each -year is common (it's not required, but helps keep things fast and -organised). So we usually configure a different journal file, by -setting the 'LEDGER_FILE' environment variable, to something like -'~/finance/2023.journal'. For more about how to do that on your system, -see Common tasks > Setting LEDGER_FILE. - -* Menu: - -* Data formats:: -* Standard input:: -* Multiple files:: -* Strict mode:: - - -File: hledger.info, Node: Data formats, Next: Standard input, Up: Input - -2.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 '.journal' '.j' '.hledger' - some Ledger journals, for '.ledger' - transactions -'timeclock' timeclock files, for precise '.timeclock' - time logging -'timedot' timedot files, for '.timedot' - approximate time logging -'csv' CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv' - values, for data import '.csv.rules' '.ssv.rules' - '.tsv.rules' - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions -shown above. If it can't recognise the file extension, it assumes -'journal' format. So for non-journal files, it's important to use a -recognised file extension, so as to either read successfully or to show -relevant error messages. - - You can also force a specific reader/format by prefixing the file -path with the format and a colon. Eg, to read a .dat file as csv -format: - -$ hledger -f csv:/some/csv-file.dat stats - - -File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input - -2.2 Standard input -================== - -The file name '-' means standard input: - -$ cat FILE | hledger -f- print - - If reading non-journal data in this way, you'll need to add a file -format prefix, like: - -$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- - - -File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input - -2.3 Multiple files -================== - -You can specify multiple '-f' options, to read multiple files as one big -journal. When doing this, note that certain features (described below) -will be affected: - - * Balance assertions will not see the effect of transactions in - previous files. (Usually this doesn't matter as each file will set - the corresponding opening balances.) - * Some directives will not affect previous or subsequent files. - - If needed, you can work around these by using a single parent file -which includes the others, or concatenating the files into one, eg: 'cat -a.journal b.journal | hledger -f- CMD'. - - -File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input - -2.4 Strict mode -=============== - -hledger checks input files for valid data. By default, the most -important errors are detected, while still accepting easy journal files -without a lot of declarations: - - * Are the input files parseable, with valid syntax ? - * Are all transactions balanced ? - * Do all balance assertions pass ? - - With the '-s'/'--strict' flag, additional checks are performed: - - * Are all accounts posted to, declared with an 'account' directive ? - (Account error checking) - * Are all commodities declared with a 'commodity' directive ? - (Commodity error checking) - * Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks - the ones -listed above and some more. - - -File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top - -3 Commands -********** - -hledger provides various subcommands for getting things done. Most of -these commands do not change the journal file; they just read it and -output a report. A few commands assist with adding data and file -management. - - To show the commands list, run 'hledger' with no arguments. The -commands are described in detail in PART 4: COMMANDS, below. - - To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', - - * CMD is the full command name, or its standard abbreviation shown in - the commands list, or any unambiguous prefix of the name. - - * CMDOPTS are command-specific options, if any. Command-specific - options must be written after the command name. Eg: 'hledger print - -x'. - - * CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit - the data in some way. Eg: 'hledger reg assets:checking'. - - To list a command's options, arguments, and documentation in the -terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. - -* Menu: - -* Add-on commands:: - - -File: hledger.info, Node: Add-on commands, Up: Commands - -3.1 Add-on commands -=================== - -In addition to the built-in commands, you can install _add-on commands_: -programs or scripts named "hledger-SOMETHING", which will also appear in -hledger's commands list. If you used the hledger-install script, you -will have several add-ons installed already. Some more can be found in -hledger's bin/ directory, documented at -https://hledger.org/scripts.html. - - More precisely, add-on commands are programs or scripts in your -shell's PATH, whose name starts with "hledger-" and ends with no -extension or a recognised extension (".bat", ".com", ".exe", ".hs", -".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), -and (on unix and mac) which has executable permission for the current -user. - - You can run add-on commands using hledger, much like built-in -commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'. But note -the double hyphen argument, required before add-on-specific options. -Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'. If this causes -difficulty, you can always run the add-on directly, without using -'hledger': 'hledger-ui --watch' or 'hledger-web --serve'. - - -File: hledger.info, Node: Options, Next: Command line tips, Prev: Commands, Up: Top - -4 Options -********* - -Run 'hledger -h' to see general command line help, and general options -which are common to most hledger commands. These options can be written -anywhere on the command line. They can be grouped into help, input, and -reporting options: - -* Menu: - -* General help options:: -* General input options:: -* General reporting options:: - - -File: hledger.info, Node: General help options, Next: General input options, Up: Options - -4.1 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) - - -File: hledger.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: Options - -4.2 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) - - -File: hledger.info, Node: General reporting options, Prev: General input options, Up: Options - -4.3 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-equity' - - infer conversion equity postings from costs -'--infer-costs' - - infer costs from conversion equity postings -'--infer-market-prices' - - use costs as additional market prices, as if they were P directives -'--forecast' - - generate transactions from periodic rules, between the latest - recorded txn and 6 months from today, or during the specified - PERIOD (= is required). Auto posting rules will be applied to - these transactions as well. Also, in hledger-ui make future-dated - transactions visible. -'--auto' - - generate extra postings by applying auto posting rules to all txns - (not just forecast txns) -'--verbose-tags' - - add visible tags indicating transactions or postings which have - been generated/modified -'--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 line tips, Next: Output, Prev: Options, Up: Top - -5 Command line tips -******************* - -Here are some details useful to know about for hledger command lines -(and elsewhere). Feel free to skip this section until you need it. - -* Menu: - -* Option repetition:: -* Special characters:: -* Unicode characters:: -* Regular expressions:: -* Argument files:: - - -File: hledger.info, Node: Option repetition, Next: Special characters, Up: Command line tips - -5.1 Option repetition -===================== - -If options are repeated in a command line, hledger will generally use -the last (right-most) occurence. - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Option repetition, Up: Command line tips - -5.2 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 - -5.2.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 - -5.2.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 - -5.2.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 - -5.2.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: Command line tips - -5.3 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, Next: Argument files, Prev: Unicode characters, Up: Command line tips - -5.4 Regular expressions -======================= - -A regular expression (regexp) is a small piece of text where certain -characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have -special meanings, forming a tiny language for matching text precisely - -very useful in hledger and elsewhere. To learn all about them, visit -regular-expressions.info. - - hledger supports regexps whenever you are entering a pattern to match -something, eg in query arguments, account aliases, CSV if rules, -hledger-web's search form, hledger-ui's '/' search, etc. You may need -to wrap them in quotes, especially at the command line (see Special -characters above). Here are some examples: - - Account name queries (quoted for command line use): - -Regular expression: Matches: -------------------- ------------------------------------------------------------ -bank assets:bank, assets:bank:savings, expenses:art:banksy, ... -:bank assets:bank:savings, expenses:art:banksy -:bank: assets:bank:savings -'^bank' none of those ( ^ matches beginning of text ) -'bank$' assets:bank ( $ matches end of text ) -'big \$ bank' big $ bank ( \ disables following character's special meaning ) -'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) -'(sav|check)ing' saving or checking ( (|) matches either alternative ) -'saving|checking' saving or checking ( outer parentheses are not needed ) -'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) -'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) -'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) -'b.nk' bank, bonk, b nk, ... ( . matches any character ) - - Some other queries: - -desc:'amazon|amzn|audible' Amazon transactions -cur:EUR amounts with commodity symbol containing EUR -cur:'\$' amounts with commodity symbol containing $ -cur:'^\$$' only $ amounts, not eg AU$ or CA$ -cur:....? amounts with 4-or-more-character symbols -tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 - - Account name aliases: accept '.' instead of ':' as account separator: - -alias /\./=: replaces all periods in account names with colons - - Show multiple top-level accounts combined as one: - ---alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) - - Show accounts with the second-level part removed: - ---alias '/^([^:]+):[^:]+/ = \1' - match a top-level account and a second-level account - and replace those with just the top-level account - ( \1 in the replacement text means "whatever was matched - by the first parenthesised part of the regexp" - - CSV rules: match CSV records containing dining-related MCC codes: - -if \?MCC581[124] - - Match CSV records with a specific amount around the end/start of -month: - -if %amount \b3\.99 -& %date (29|30|31|01|02|03)$ - -* Menu: - -* hledger's regular expressions:: - - -File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions - -5.4.1 hledger's regular expressions ------------------------------------ - -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. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the - replacement string to reference capturing groups in the search - regexp. Otherwise, if you write '\1', it will match the digit '1'. - 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: Argument files, Prev: Regular expressions, Up: Command line tips - -5.5 Argument files -================== - -You can save a set of command line options and arguments in a file, and -then reuse them by writing '@FILENAME' as a command line argument. Eg: -'hledger bal @foo.args'. - - Inside the argument file, each line should contain just one option or -argument. Don't use spaces except inside quotes (or you'll see a -confusing error); write '=' (or nothing) between a flag and its -argument. For the special characters mentioned above, use one less -level of quoting than you would at the command prompt. - - -File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips, Up: Top - -6 Output -******** - -* Menu: - -* Output destination:: -* Output format:: -* Commodity styles:: -* Colour:: -* Box-drawing:: -* Paging:: -* Debug output:: - - -File: hledger.info, Node: Output destination, Next: Output format, Up: Output - -6.1 Output destination -====================== - -hledger commands send their output to the terminal by default. You can -of course redirect this, eg into a file, using standard shell syntax: - -$ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also -provide the '-o/--output-file' option, which does the same thing without -needing the shell. Eg: - -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) - - -File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output - -6.2 Output format -================= - -Some commands offer other kinds of output, not just text on the -terminal. Here are those commands and the formats currently supported: - -- txt csv/tsv html json sql -------------------------------------------------------------------------------- -aregister Y Y Y Y -balance Y _1_ Y _1_ Y _1,2_ Y -balancesheet Y _1_ Y _1_ Y _1_ Y -balancesheetequityY _1_ Y _1_ Y _1_ Y -cashflow Y _1_ Y _1_ Y _1_ Y -incomestatement Y _1_ Y _1_ Y _1_ Y -print Y Y Y Y -register Y Y Y - - * _1 Also affected by the balance commands' '--layout' option._ - * _2 'balance' does not support html output without a report interval - or with '--budget'._ - - The output format is selected by the '-O/--output-format=FMT' option: - -$ hledger print -O csv # print CSV on stdout - - or by the filename extension of an output file specified with the -'-o/--output-file=FILE.FMT' option: - -$ hledger balancesheet -o foo.csv # write CSV to foo.csv - - The '-O' option can be combined with '-o' to override the file -extension, if needed: - -$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - - Some notes about the various output formats: - -* Menu: - -* CSV output:: -* HTML output:: -* JSON output:: -* SQL output:: - - -File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format - -6.2.1 CSV output ----------------- - - * In CSV output, digit group marks (such as thousands separators) are - disabled automatically. - - -File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format - -6.2.2 HTML output ------------------ - - * HTML output can be styled by an optional 'hledger.css' file in the - same directory. - - -File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format - -6.2.3 JSON output ------------------ - - * This is not yet much used; real-world feedback is welcome. - - * Our JSON is rather large and verbose, since it is a faithful - representation of hledger's internal data types. To understand the - JSON, read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. - - * hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can - arise in practice (from automatically-calculated transaction - prices), and would break most JSON consumers. So in JSON, we show - quantities as simple Numbers with at most 10 decimal places. We - don't limit the number of integer digits, but that part is under - your control. We hope this approach will not cause problems in - practice; if you find otherwise, please let us know. (Cf #1195) - - -File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format - -6.2.4 SQL output ----------------- - - * This is not yet much used; real-world feedback is welcome. - - * SQL output is expected to work at least with SQLite, MySQL and - Postgres. - - * For SQLite, it will be more useful if you modify the generated 'id' - field to be a PRIMARY KEY. Eg: - - $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - - * SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables - created via SQL output of hledger, you would probably want to - either clear tables of existing data (via 'delete' or 'truncate' - SQL statements) or drop tables completely as otherwise your - postings will be duped. - - -File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output - -6.3 Commodity styles -==================== - -When displaying amounts, hledger infers a standard display style for -each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a '-c/--commodity-style' option -(except for cost amounts and amounts displayed by the 'print' command, -which are always displayed with all decimal digits). For example, the -following will force dollar amounts to be displayed as shown: - -$ hledger print -c '$1.000,0' - - This option can repeated to set the display style for multiple -commodities/currencies. Its argument is as described in the commodity -directive. - - -File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output - -6.4 Colour -========== - -In terminal output, some commands can produce colour when the terminal -supports it: - - * if the '--color/--colour' option is given a value of 'yes' or - 'always' (or 'no' or 'never'), colour will (or will not) be used; - * otherwise, if the 'NO_COLOR' environment variable is set, colour - will not be used; - * otherwise, colour will be used if the output (terminal or file) - supports it. - - -File: hledger.info, Node: Box-drawing, Next: Paging, Prev: Colour, Up: Output - -6.5 Box-drawing -=============== - -In terminal output, you can enable unicode box-drawing characters to -render prettier tables: - - * if the '--pretty' option is given a value of 'yes' or 'always' (or - 'no' or 'never'), unicode characters will (or will not) be used; - * otherwise, unicode characters will not be used. - - -File: hledger.info, Node: Paging, Next: Debug output, Prev: Box-drawing, Up: Output - -6.6 Paging -========== - -When showing long output in the terminal, hledger will try to use the -pager specified by the 'PAGER' environment variable, or 'less', or -'more'. (A pager is a helper program that shows one page at a time -rather than scrolling everything off screen). Currently it does this -only for help output, not for reports; specifically, - - * when listing commands, with 'hledger' - * when showing help with 'hledger [CMD] --help', - * when viewing manuals with 'hledger help' or 'hledger --man'. - - Note the pager is expected to handle ANSI codes, which hledger uses -eg for bold emphasis. For the common pager 'less' (and its 'more' -compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment -variables to make this work. If you use a different pager, you might -need to configure it similarly, to avoid seeing junk on screen (let us -know). Otherwise, you can set the 'NO_COLOR' environment variable to 1 -to disable all ANSI output (see Colour). - - -File: hledger.info, Node: Debug output, Prev: Paging, Up: Output - -6.7 Debug output -================ - -We intend hledger to be relatively easy to troubleshoot, introspect and -develop. You can add '--debug[=N]' to any hledger command line to see -additional debug output. N ranges from 1 (least output, the default) to -9 (maximum output). Typically you would start with 1 and increase until -you are seeing enough. Debug output goes to stderr, and is not affected -by '-o/--output-file' (unless you redirect stderr to stdout, eg: -'2>&1'). It will be interleaved with normal output, which can help -reveal when parts of the code are evaluated. To capture debug output in -a log file instead, you can usually redirect stderr, eg: - -hledger bal --debug=3 2>hledger.log - - -File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top - -7 Environment -************* - -These environment variables affect hledger: - - *COLUMNS* This is normally set by your terminal; some hledger -commands ('register') will format their output to this width. If not -set, they will try to use the available terminal width. - - *LEDGER_FILE* The main journal file to use when not specified with -'-f/--file'. Default: '$HOME/.hledger.journal'. - - *NO_COLOR* If this environment variable is set (with any value), -hledger will not use ANSI color codes in terminal output, unless -overridden by an explicit '--color/--colour' option. - - -File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top - -8 PART 2: DATA FORMATS -********************** - - -File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top - -9 Journal -********* - -hledger's default file format, representing a General Journal. Here's a -cheatsheet/mini-tutorial, or you can skip ahead to About journal format. - -* Menu: - -* Journal cheatsheet:: -* About journal format:: -* Comments:: -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Transaction comments:: -* Postings:: -* Account names:: -* Amounts:: -* Costs:: -* Balance assertions:: -* Posting comments:: -* Tags:: -* Directives:: -* account directive:: -* alias directive:: -* commodity directive:: -* decimal-mark directive:: -* include directive:: -* P directive:: -* payee directive:: -* tag directive:: -* Periodic transactions:: -* Auto postings:: -* Other syntax:: - - -File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal - -9.1 Journal cheatsheet -====================== - -# Here is the main syntax of hledger's journal format -# (omitting extra Ledger compatibility syntax). -# hledger journals contain comments, directives, and transactions, in any order: - -############################################################################### -# 1. Comment lines are for notes or temporarily disabling things. -# They begin with #, ;, or a line containing the word "comment". - -# hash comment line -; semicolon comment line -comment -These lines -are commented. -end comment - -# Some but not all hledger entries can have same-line comments attached to them, -# from ; (semicolon) to end of line. - -############################################################################### -# 2. Directives modify parsing or reports in some way. -# They begin with a word or letter (or symbol). - -account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. -account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) -alias chkg = assets:checking -commodity $0.00 -decimal-mark . -include /dev/null -payee Whole Foods -P 2022-01-01 AAAA $1.40 -~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - -############################################################################### -# 3. Transactions are what it's all about; they are dated events, -# usually describing movements of money. -# They begin with a date. - -# DATE DESCRIPTION ; This is a transaction comment. -# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. -# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. -# ; ^^ At least 2 spaces between account and amount. -# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - -2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - -2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - -2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - -2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - -2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - -1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - -2022.01.01 These date -2022/1/1 formats are -12/31 also allowed (but consistent YYYY-MM-DD is recommended). - - -File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal - -9.2 About journal format -======================== - -hledger's usual data source is a plain text file containing journal -entries in hledger journal format. This file represents a standard -accounting general journal. I use file names ending in '.journal', but -that's not required. The journal file contains a number of transaction -entries, each describing a transfer of money (or any commodity) between -two or more named accounts, in a simple format readable by both hledger -and humans. - - hledger's journal format is compatible with most of Ledger's journal -format, but not all of it. The differences and interoperation tips are -described at hledger and Ledger. With some care, and by avoiding -incompatible features, you can keep your hledger journal readable by -Ledger and vice versa. This can useful eg for comparing the behaviour -of one app against the other. - - You can use hledger without learning any more about this file; just -use the add or web or import commands to create and update it. - - Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor addons -such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and -hledger-vscode for Visual Studio Code, make this easier, adding colour, -formatting, tab completion, and useful commands. See Editor -configuration at hledger.org for the full list. - - Here's a description of each part of the file format (and hledger's -data model). - - A hledger journal file can contain three kinds of thing: file -comments, transactions, and/or directives (counting periodic transaction -rules and auto posting rules as directives). - - -File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal - -9.3 Comments -============ - -Lines in the journal will be ignored if they begin with a hash ('#') or -a semicolon (';'). (See also Other syntax.) hledger will also ignore -regions beginning with a 'comment' line and ending with an 'end comment' -line (or file end). Here's a suggestion for choosing between them: - - * '#' for top-level notes - * ';' for commenting out things temporarily - * 'comment' for quickly commenting large regions (remember it's - there, or you might get confused) - - Eg: - -# a comment line -; another commentline -comment -A multi-line comment block, -continuing until "end comment" directive -or the end of the current file. -end comment - - Some hledger entries can have same-line comments attached to them, -from ; (semicolon) to end of line. See Transaction comments, Posting -comments, and Account comments below. - - -File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal - -9.4 Transactions -================ - -Transactions are the main unit of information in a journal file. They -represent events, typically a movement of some quantity of commodities -between two or more named accounts. - - Each transaction is recorded as a journal entry, beginning with a -simple date in column 0. This can be followed by any of the following -optional fields, separated by spaces: - - * a status character (empty, '!', or '*') - * a code (any short number or text, enclosed in parentheses) - * a description (any remaining text until end of line or a semicolon) - * a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - * 0 or more indented _posting_ lines, describing what was transferred - and the accounts involved (indented comment lines are also allowed, - but not blank lines or non-indented lines). - - Here's a simple journal file containing one transaction: - -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - -File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal - -9.5 Dates -========= - -* Menu: - -* Simple dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates - -9.5.1 Simple dates ------------------- - -Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or -'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may -be omitted, in which case it will be inferred from the context: the -current transaction, the default year set with a 'Y' directive, or the -current date when the command is run. Some examples: '2010-01-31', -'2010/01/31', '2010.1.31', '1/31'. - - (The UI also accepts simple dates, as well as the more flexible smart -dates documented in the hledger manual.) - - -File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates - -9.5.2 Posting dates -------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like 'date:DATE'. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction's date. -The 'date:' tag must have a valid simple date value if it is present, eg -a 'date:' tag with no value is not allowed. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal - -9.6 Status -========== - -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: - -mark status - ------------------ - unmarked -'!' pending -'*' cleared - - When reporting, you can filter by status with the '-U/--unmarked', -'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', -and 'status:*' queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" -state is called "uncleared". As of hledger 1.3 we have renamed it to -unmarked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching -pending, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. Some editor modes provide highlighting and -shortcuts for working with status. Eg in Emacs ledger-mode, you can -toggle transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to -you. Here's one suggestion: - -status meaning --------------------------------------------------------------------------- -uncleared recorded but not yet reconciled; needs review -pending tentatively reconciled (if needed, eg during a big - reconciliation) -cleared complete, reconciled as far as possible, and considered - correct - - With this scheme, you would use '-PC' to see the current balance at -your bank, '-U' to see things which will probably hit your bank soon -(like uncashed checks), and no flags to see the most up-to-date state of -your finances. - - -File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal - -9.7 Code -======== - -After the status mark, but before the description, you can optionally -write a transaction "code", enclosed in parentheses. This is a good -place to record a check number, or some other important transaction id -or reference number. - - -File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal - -9.8 Description -=============== - -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -9.8.1 Payee and note --------------------- - -You can optionally include a '|' (pipe) character in descriptions to -subdivide the description into separate fields for payee/payer name on -the left (up to the first '|') and an additional note field on the right -(after the first '|'). This may be worthwhile if you need to do more -precise querying and pivoting by payee or by note. - - -File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal - -9.9 Transaction comments -======================== - -Text following ';', after a transaction description, and/or on indented -lines immediately below it, form comments for that transaction. They -are reproduced by 'print' but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal - -9.10 Postings -============= - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - * (optional) a status character (empty, '!', or '*'), followed by a - space - * (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - * (optional) *two or more spaces* or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are -being removed. - - The amounts within a transaction must always sum up to zero. As a -convenience, one amount may be left blank; it will be inferred so as to -balance the transaction. - - Be sure to note the unusual two-space delimiter between account name -and amount. This makes it easy to write account names containing -spaces. But if you accidentally leave only one space (or tab) before -the amount, the amount will be considered part of the account name. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal - -9.11 Account names -================== - -Accounts are the main way of categorising things in hledger. As in -Double Entry Bookkeeping, they can represent real world accounts (such -as a bank account), or more abstract categories such as "money borrowed -from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are 'assets', -'liabilities', 'equity', 'revenues', 'expenses'. (You might see these -referred to as A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. For example, from the account names 'assets:bank:checking' -and 'expenses:food', hledger will infer this hierarchy of five accounts: - -assets -assets:bank -assets:bank:checking -expenses -expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - -assets - bank - checking -expenses - food - - hledger reports can summarise the account tree to any depth, so you -can go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. Note, when an account name and an -amount are written on the same line, they must be separated by *two or -more spaces* (or tabs). - - Parentheses or brackets enclosing the full account name indicate -virtual postings, described below. Parentheses or brackets internal to -the account name have no special meaning. - - Account names can be altered temporarily or permanently by account -aliases. - - -File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal - -9.12 Amounts -============ - -After the account name, there is usually an amount. (Important: between -account name and amount, there must be *two or more spaces*.) - - hledger's amount format is flexible, supporting several international -formats. Here are some examples. Amounts have a number (the -"quantity"): - -1 - - ..and usually a currency symbol or commodity name (more on this -below), to the left or right of the quantity, with or without a -separating space: - -$1 -4000 AAPL -3 "green apples" - - Amounts can be preceded by a minus sign (or a plus sign, though plus -is the default), The sign can be written before or after a left-side -commodity symbol: - --$1 -$-1 - - One or more spaces between the sign and the number are acceptable -when parsing (but they won't be displayed in output): - -+ $1 -$- 1 - - Scientific E notation is allowed: - -1E-6 -EUR 1E3 - -* Menu: - -* Decimal marks digit group marks:: -* Commodity:: -* Directives influencing number parsing and display:: -* Commodity display style:: -* Rounding:: - - -File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts - -9.12.1 Decimal marks, digit group marks ---------------------------------------- - -A _decimal mark_ can be written as a period or a comma: - -1.23 -1,23 - - 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 - - hledger is not biased towards period or comma decimal marks, so a -number containing just one period or comma, like '1,000' or '1.000', is -ambiguous. In such cases hledger assumes it is a decimal mark, parsing -both of these as 1. - - To disambiguate these and ensure accurate number parsing, especially -if you use digit group marks, we recommend declaring the decimal mark. -You can declare it for each file with 'decimal-mark' directives, or for -each commodity with 'commodity' directives (described below). - - -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts - -9.12.2 Commodity ----------------- - -Amounts in hledger have both a "quantity", which is a signed decimal -number, and a "commodity", which is a currency symbol, stock ticker, or -any word or phrase describing something you are tracking. - - If the commodity name contains non-letters (spaces, numbers, or -punctuation), you must always write it inside double quotes ('"green -apples"', '"ABC123"'). - - If you write just a bare number, that too will have a commodity, with -name '""'; we call that the "no-symbol commodity". - - Actually, hledger combines these single-commodity amounts into more -powerful multi-commodity amounts, which are what it works with most of -the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 -TSLA'. In practice, you will only see multi-commodity amounts in -hledger's output; you can't write them directly in the journal file. - - (If you are writing scripts or working with hledger's internals, -these are the 'Amount' and 'MixedAmount' types.) - - -File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts - -9.12.3 Directives influencing number parsing and display --------------------------------------------------------- - -You can add 'decimal-mark' and 'commodity' directives to the journal, to -declare and control these things more explicitly and precisely. These -are described below, but here's a quick example: - -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 - - -File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts - -9.12.4 Commodity display style ------------------------------- - -For the amounts in each commodity, hledger chooses a consistent display -style (symbol placement, decimal mark and digit group marks, number of -decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a 'D' directive declaring a default commodity, that -commodity symbol and amount format is applied to all no-symbol amounts -in the journal. - - Then each commodity's display style is determined from its -'commodity' directive. We recommend always declaring commodities with -'commodity' directives, since they help ensure consistent display styles -and precisions, and bring other benefits such as error checking for -commodity symbols. - - But if a 'commodity' directive is not present, hledger infers a -commodity's display styles from its amounts as they are written in the -journal (excluding cost amounts and amounts in periodic transaction -rules or auto posting rules). It uses - - * the symbol placement and decimal mark of the first amount seen - * the digit group marks of the first amount with digit group marks - * and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a -default style, like '$1000.00' (symbol on the left with no space, period -as decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -'-c/--commodity-style' command line option. - - -File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts - -9.12.5 Rounding ---------------- - -Amounts are stored internally as decimal numbers with up to 255 decimal -places. They are displayed with their original journal precisions by -print and print-like reports, and rounded to their display precision -(the number of decimal digits specified by the commodity display style) -by other reports. When rounding, hledger uses banker's rounding (it -rounds to the nearest even digit). So eg 0.5 displayed with zero -decimal digits appears as "0". - - -File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal - -9.13 Costs -========== - -After a posting amount, you can note its cost (when buying) or selling -price (when selling) in another commodity, by writing either '@ -UNITPRICE' or '@@ TOTALPRICE' after it. This indicates a conversion -transaction, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, -discussions, or code; that term was directionally neutral and reminded -that it is a price specific to a transaction, but we now just call it -"cost", with the understanding that the transaction could be a purchase -or a sale.) - - Costs are usually written explicitly with '@' or '@@', but can also -be inferred automatically for simple multi-commodity transactions. -Note, if costs are inferred, the order of postings is significant; the -first posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign -currency in hledger, using the cost notation either explicitly or -implicitly: - - 1. Write the price per unit, as '@ UNITPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as '@@ TOTALPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction. - Note the effect of posting order: the price is added to first - posting, making it '€100 @@ $135', as in example 2: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the '-B/--cost' -flag; this is discussed more in the Cost reporting section. - - Note that the cost normally should be a positive amount, though it's -not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. - -* Menu: - -* Other cost/lot notations:: - - -File: hledger.info, Node: Other cost/lot notations, Up: Costs - -9.13.1 Other cost/lot notations -------------------------------- - -A slight digression for Ledger and Beancount users. Ledger has a number -of cost/lot-related notations: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a conversion rate, as in hledger - * when buying, also creates a lot than can be selected at - selling time - - * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) - * like the above, but also means "this cost was exceptional, - don't use it when inferring market prices". - - Currently, hledger treats the above like '@' and '@@'; the -parentheses are ignored. - - * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) - * when buying, means "this cost is also the fixed price, don't - let it fluctuate in value reports" - - * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) - * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', - also creates a lot - * when selling, combined with '@ ...', specifies an investment - lot by its cost basis; does not check if that lot is present - - * and related: '[YYYY/MM/DD]' (lot date) - * when buying, attaches this acquisition date to the lot - * when selling, selects a lot by its acquisition date - - * '(SOME TEXT)' (lot note) - * when buying, attaches this note to the lot - * when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. (This can break transaction -balancing.) - - For Beancount users, the notation and behaviour is different: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a cost without creating a lot, as in hledger - * when buying (augmenting) or selling (reducing) a lot, combined - with '{...}': documents the cost/selling price (not used for - transaction balancing) - - * '{UNITCOST}' and '{{TOTALCOST}}' - * when buying (augmenting), expresses the cost for transaction - balancing, and also creates a lot with this cost basis - attached - * when selling (reducing), - * selects a lot by its cost basis - * raises an error if that lot is not present or can not be - selected unambiguously (depending on booking method - configured) - * expresses the selling price for transaction balancing - - Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation -but ignores it. - - * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, - "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. - - Currently, hledger rejects these. - - -File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal - -9.14 Balance assertions -======================= - -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, '= EXPECTEDBALANCE' following a posting's -amount. Eg here we assert the expected dollar balance in accounts a and -b after each posting: - -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the '-I/--ignore-assertions' flag, which can be useful for -troubleshooting or for reading Ledger files. (Note: this flag currently -does not disable balance assignments, described below). - -* Menu: - -* Assertions and ordering:: -* Assertions and multiple included files:: -* Assertions and multiple -f files:: -* Assertions and commodities:: -* Assertions and prices:: -* Assertions and subaccounts:: -* Assertions and virtual postings:: -* Assertions and auto postings:: -* Assertions and precision:: - - -File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions - -9.14.1 Assertions and ordering ------------------------------- - -hledger sorts an account's postings and assertions first by date and -then (for postings on the same day) by parse order. Note this is -different from Ledger, which sorts assertions only by parse order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder -differently-dated transactions within the journal. But if you reorder -same-dated transactions or postings, assertions might break and require -updating. This order dependence does bring an advantage: precise -control over the order of postings and assertions within a day, so you -can assert intra-day balances. - - -File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions - -9.14.2 Assertions and multiple included files ---------------------------------------------- - -Multiple files included with the 'include' directive are processed as if -concatenated into one file, preserving their order and the posting order -within each file. It means that balance assertions in later files will -see balance from earlier files. - - And if you have multiple postings to an account on the same day, -split across multiple files, and you want to assert the account's -balance on that day, you'll need to put the assertion in the right file -- the last one in the sequence, probably. - - -File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions - -9.14.3 Assertions and multiple -f files ---------------------------------------- - -Unlike 'include', when multiple files are specified on the command line -with multiple '-f/--file' options, balance assertions will not see -balance from earlier files. This can be useful when you do not want -problems in earlier files to disrupt valid assertions in later files. - - If you do want assertions to see balance from earlier files, use -'include', or concatenate the files temporarily. - - -File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions - -9.14.4 Assertions and commodities ---------------------------------- - -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity's balance within the -(possibly multi-commodity) account balance. This is how assertions work -in Ledger also. We could call this a "partial" balance assertion. - - To assert the balance of more than one commodity in an account, you -can write multiple postings, each asserting one commodity's balance. - - You can make a stronger "total" balance assertion by writing a double -equals sign ('== EXPECTEDBALANCE'). This asserts that there are no -other commodities in the account besides the asserted one (or at least, -that their balance is 0). - -2013/1/1 - a $1 - a 1€ - b $-1 - c -1€ - -2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1€ - b 0 == $-1 - c 0 == -1€ - -2013/1/3 ; This assertion fails as 'a' also contains 1€ - a 0 == $1 - - It's not yet possible to make a complete assertion about a balance -that has multiple commodities. One workaround is to isolate each -commodity into its own subaccount: - -2013/1/1 - a:usd $1 - a:euro 1€ - b - -2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1€ - - -File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions - -9.14.5 Assertions and prices ----------------------------- - -Balance assertions ignore costs, and should normally be written without -one: - -2019/1/1 - (a) $1 @ €1 = $1 - - We do allow prices to be written there, however, and print shows -them, even though they don't affect whether the assertion passes or -fails. This is for backward compatibility (hledger's close command used -to generate balance assertions with prices), and because balance -_assignments_ do use them (see below). - - -File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions - -9.14.6 Assertions and subaccounts ---------------------------------- - -The balance assertions above ('=' and '==') do not count the balance -from subaccounts; they check the account's exclusive balance only. You -can assert the balance including subaccounts by writing '=*' or '==*', -eg: - -2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 - - -File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions - -9.14.7 Assertions and virtual postings --------------------------------------- - -Balance assertions always consider both real and virtual postings; they -are not affected by the '--real/-R' flag or 'real:' query. - - -File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions - -9.14.8 Assertions and auto postings ------------------------------------ - -Balance assertions _are_ affected by the '--auto' flag, which generates -auto postings, which can alter account balances. Because auto postings -are optional in hledger, accounts affected by them effectively have two -balances. But balance assertions can only test one or the other of -these. So to avoid making fragile assertions, either: - - * assert the balance calculated with '--auto', and always use - '--auto' with that file - * or assert the balance calculated without '--auto', and never use - '--auto' with that file - * or avoid balance assertions on accounts affected by auto postings - (or avoid auto postings entirely). - - -File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions - -9.14.9 Assertions and precision -------------------------------- - -Balance assertions compare the exactly calculated amounts, which are not -always what is shown by reports. Eg a commodity directive may limit the -display precision, but this will not affect balance assertions. Balance -assertion failure messages show exact amounts. - - -File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal - -9.15 Posting comments -===================== - -Text following ';', at the end of a posting line, and/or on indented -lines immediately below it, form comments for that posting. They are -reproduced by 'print' but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - -File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal - -9.16 Tags -========= - -Tags are a way to add extra labels or labelled data to transactions, -postings, or accounts, which you can then search or pivot on. - - They are written as a word (optionally hyphenated) immediately -followed by a full colon, in a transaction or posting or account -directive's comment. (This is an exception to the usual rule that -things in comments are ignored.) Eg, here four different tags are -recorded: one on the checking account, two on the transaction, and one -on the expenses posting: - -account assets:checking ; accounttag: - -2017/1/16 bought groceries ; transactiontag-1: - ; transactiontag-2: - assets:checking $-1 - expenses:food $1 ; postingtag: - - Postings also inherit tags from their transaction and their account. -And transactions also acquire tags from their postings (and postings' -accounts). So in the example above, the expenses posting effectively -has all four tags (by inheriting from account and transaction), and the -transaction also has all four tags (by acquiring from the expenses -posting). - - You can list tag names with 'hledger tags [NAMEREGEX]', or match by -tag name with a 'tag:NAMEREGEX' query. - -* Menu: - -* Tag values:: - - -File: hledger.info, Node: Tag values, Up: Tags - -9.16.1 Tag values ------------------ - -Tags can have a value, which is any text after the colon up until a -comma or end of line (with surrounding whitespace removed). Note this -means that hledger tag values can not contain commas. Eg in the -following posting, the three tags' values are "value 1", "value 2", and -"" (empty) respectively: - - expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - - Note that tags can be repeated, and are additive rather than -overriding: when the same tag name is seen again with a new value, the -new name:value pair is added to the tags. (It is not possible to -override a tag's value or remove a tag.) - - You can list a tag's values with 'hledger tags TAGNAME --values', or -match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query. - - -File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal - -9.17 Directives -=============== - -Besides transactions, there is something else you can put in a 'journal' -file: directives. These are declarations, beginning with a keyword, -that modify hledger's behaviour. Some directives can have more specific -subdirectives, indented below them. hledger's directives are similar to -Ledger's in many cases, but there are also many differences. Directives -are not required, but can be useful. Here are the main directives: - -purpose directive --------------------------------------------------------------------------- -*READING DATA:* -Rewrite account names 'alias' -Comment out sections of the file 'comment' -Declare file's decimal mark, to help 'decimal-mark' -parse amounts accurately -Include other data files 'include' -*GENERATING DATA:* -Generate recurring transactions or '~' -budget goals -Generate extra postings on existing '=' -transactions -*CHECKING FOR ERRORS:* -Define valid entities to provide more 'account', 'commodity', -error checking 'payee', 'tag' -*REPORTING:* -Declare accounts' type and display 'account' -order -Declare commodity display styles 'commodity' -Declare market prices 'P' - -* Menu: - -* Directives and multiple files:: -* Directive effects:: - - -File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives - -9.17.1 Directives and multiple files ------------------------------------- - -Directives vary in their scope, ie which journal entries and which input -files they affect. Most often, a directive will affect the following -entries and included files if any, until the end of the current file - -and no further. You might find this inconvenient! For example, 'alias' -directives do not affect parent or sibling files. But there are usually -workarounds; for example, put 'alias' directives in your top-most file, -before including other files. - - The restriction, though it may be annoying at first, is in a good -cause; it allows reports to be stable and deterministic, independent of -the order of input. Without it, reports could show different numbers -depending on the order of -f options, or the positions of include -directives in your files. - - -File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives - -9.17.2 Directive effects ------------------------- - -Here are all hledger's directives, with their effects and scope -summarised - nine main directives, plus four others which we consider -non-essential: - -directivewhat it does ends - at - file - end? ---------------------------------------------------------------------------- -*'account'*Declares an account, for checking all entries in all files; andN - its display order and type. Subdirectives: any text, ignored. -*'alias'*Rewrites account names, in following entries until end of Y - current file or 'end aliases'. Command line equivalent: - '--alias' -*'comment'*Ignores part of the journal file, until end of current file orY - 'end comment'. -*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N - all amounts in all files 2. the decimal mark for parsing - amounts of this commodity, in the following entries until end of - current file (if there is no 'decimal-mark' directive) 3. and - the display style for amounts of this commodity 4. which is - also the precision to use for balanced-transaction checking in - this commodity. Takes precedence over 'D'. Subdirectives: - 'format' (Ledger-compatible syntax). Command line equivalent: - '-c/--commodity-style' -*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y - commodities in following entries until next 'decimal-mark' or - end of current file. Included files can override. Takes - precedence over 'commodity' and 'D'. -*'include'*Includes entries and directives from another file, as if theyN - were written inline. Command line alternative: multiple - '-f/--file' -*'payee'*Declares a payee name, for checking all entries in all files. N -*'P'*Declares the market price of a commodity on some date, for value N - reports. -*'~'*Declares a periodic transaction rule that generates future N -(tilde)transactions with '--forecast' and budget goals with 'balance - --budget'. -Other -syntax: -*'applyPrepends a common parent account to all account names, in Y -account'*following entries until end of current file or 'end apply - account'. -*'D'*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no 'commodity' directive for this commodity: its - decimal mark, balancing precision, and display style, as above. -*'Y'*Sets a default year to use for any yearless dates, in following Y - entries until end of current file. -*'='*Declares an auto posting rule that generates extra postings on partly -(equals)matched transactions with '--auto', in current, parent, and - child files (but not sibling files, see #1212). -*OtherOther directives from Ledger's file format are accepted but -Ledgerignored. -directives* - - -File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal - -9.18 'account' directive -======================== - -'account' directives can be used to declare accounts (ie, the places -that amounts are transferred from and to). Though not required, these -declarations can provide several benefits: - - * They can document your intended chart of accounts, providing a - reference. - * In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - * They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - * They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - * They can store additional account information as comments, or as - tags which can be used to filter or pivot reports. - * They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - - They are written as the word 'account' followed by a hledger-style -account name, eg: - -account assets:bank:checking - - Note, however, that accounts declared in account directives are not -allowed to have surrounding brackets and parentheses, unlike accounts -used in postings. So the following journal will not parse: - -account (assets:bank:checking) - -* Menu: - -* Account comments:: -* Account subdirectives:: -* Account error checking:: -* Account display order:: -* Account types:: - - -File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive - -9.18.1 Account comments ------------------------ - -Text following *two or more spaces* and ';' at the end of an account -directive line, and/or following ';' on indented lines immediately below -it, form comments for that account. They are ignored except they may -contain tags, which are not ignored. - - The two-space requirement for same-line account comments is because -';' is allowed in account names. - -account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - -File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive - -9.18.2 Account subdirectives ----------------------------- - -Ledger-style indented subdirectives are also accepted, but currently -ignored: - -account assets:bank:checking - format subdirective is ignored - - -File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive - -9.18.3 Account error checking ------------------------------ - -By default, accounts need not be declared; they come into existence when -a posting references them. This is convenient, but it means hledger -can't warn you when you mis-spell an account name in the journal. -Usually you'll find that error later, as an extra account in balance -reports, or an incorrect balance when reconciling. - - In strict mode, enabled with the '-s'/'--strict' flag, hledger will -report an error if any transaction uses an account name that has not -been declared by an account directive. Some notes: - - * The declaration is case-sensitive; transactions must use the - correct account name capitalisation. - * The account directive's scope is "whole file and below" (see - directives). This means it affects all of the current file, and - any files it includes, but not parent or sibling files. The - position of account directives within the file does not matter, - though it's usual to put them at the top. - * Accounts can only be declared in 'journal' files, but will affect - included files of all types. - * It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - -File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive - -9.18.4 Account display order ----------------------------- - -The order in which account directives are written influences the order -in which accounts appear in reports, hledger-ui, hledger-web etc. By -default accounts appear in alphabetical order, but if you add these -account directives to the journal file: - -account assets -account liabilities -account equity -account revenues -account expenses - - those accounts will be displayed in declaration order: - -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses - - Any undeclared accounts are displayed last, in alphabetical order. - - Sorting is done at each level of the account tree, within each group -of sibling accounts under the same parent. And currently, this -directive: - -account other:zoo - - would influence the position of 'zoo' among 'other''s subaccounts, -but not the position of 'other' among the top-level accounts. This -means: - - * you will sometimes declare parent accounts (eg 'account other' - above) that you don't intend to post to, just to customize their - display order - * sibling accounts stay together (you couldn't display 'x:y' in - between 'a:b' and 'a:c'). - - -File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive - -9.18.5 Account types --------------------- - -hledger knows that accounts come in several types: assets, liabilities, -expenses and so on. This enables easy reports like balancesheet and -incomestatement, and filtering by account type with the 'type:' query. - - As a convenience, hledger will detect these account types -automatically if you are using common english-language top-level account -names (described below). But generally we recommend you declare types -explicitly, by adding a 'type:' tag to your top-level account -directives. Subaccounts will inherit the type of their parent. The -tag's value should be one of the five main account types: - - * 'A' or 'Asset' (things you own) - * 'L' or 'Liability' (things you owe) - * 'E' or 'Equity' (investment/ownership; balanced counterpart of - assets & liabilities) - * 'R' or 'Revenue' (what you received money from, AKA income; - technically part of Equity) - * 'X' or 'Expense' (what you spend money on; technically part of - Equity) - - or, it can be (these are used less often): - - * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the - cashflow report) - * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost - reporting).) - - Here is a typical set of account type declarations: - -account assets ; type: A -account liabilities ; type: L -account equity ; type: E -account revenues ; type: R -account expenses ; type: X - -account assets:bank ; type: C -account assets:cash ; type: C - -account equity:conversion ; type: V - - Here are some tips for working with account types. - - * The rules for inferring types from account names are as follows. - These are just a convenience that sometimes help new users get - going; if they don't work for you, just ignore them and declare - your account types. See also Regular expressions. - - If account's name contains this (CI) regular expression: | its type is: - --------------------------------------------------------------------|------------- - ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash - ^assets?(:|$) | Asset - ^(debts?|liabilit(y|ies))(:|$) | Liability - ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion - ^equity(:|$) | Equity - ^(income|revenue)s?(:|$) | Revenue - ^expenses?(:|$) | Expense - - * If you declare any account types, it's a good idea to declare an - account for all of the account types, because a mixture of declared - and name-inferred types can disrupt certain reports. - - * Certain uses of account aliases can disrupt account types. See - Rewriting accounts > Aliases and account types. - - * As mentioned above, subaccounts will inherit a type from their - parent account. More precisely, an account's type is decided by - the first of these that exists: - - 1. A 'type:' declaration for this account. - 2. A 'type:' declaration in the parent accounts above it, - preferring the nearest. - 3. An account type inferred from this account's name. - 4. An account type inferred from a parent account's name, - preferring the nearest parent. - 5. Otherwise, it will have no type. - - * For troubleshooting, you can list accounts and their types with: - - $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] - - -File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal - -9.19 'alias' directive -====================== - -You can define account alias rules which rewrite your account names, or -parts of them, before generating reports. This can be useful for: - - * expanding shorthand account names to their full form, allowing - easier data entry and a less verbose journal - * adapting old journals to your current chart of accounts - * experimenting with new account organisations, like a new hierarchy - * combining two accounts into one, eg to see their sum or difference - on one line - * customising reports - - Account aliases also rewrite account names in account directives. -They do not affect account names being entered via hledger add or -hledger-web. - - Account aliases are very powerful. They are generally easy to use -correctly, but you can also generate invalid account names with them; -more on this below. - - See also Rewrite account names. - -* Menu: - -* Basic aliases:: -* Regex aliases:: -* Combining aliases:: -* Aliases and multiple files:: -* end aliases directive:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive - -9.19.1 Basic aliases --------------------- - -To set an account alias, use the 'alias' directive in your journal file. -This affects all subsequent journal entries in the current file or its -included files (but note: not sibling or parent files). The spaces -around the = are optional: - -alias OLD = NEW - - Or, you can use the '--alias 'OLD=NEW'' option on the command line. -This affects all entries. It's useful for trying out aliases -interactively. - - OLD and NEW are case sensitive full account names. hledger will -replace any occurrence of the old account name with the new one. -Subaccounts are also affected. Eg: - -alias checking = assets:bank:wells fargo:checking -; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - -File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive - -9.19.2 Regex aliases --------------------- - -There is also a more powerful variant that uses a regular expression, -indicated by wrapping the pattern in forward slashes. (This is the only -place where hledger requires forward slashes around a regular -expression.) - - Eg: - -alias /REGEX/ = REPLACEMENT - - or: - -$ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by -REPLACEMENT. REGEX is case-insensitive as usual. - - If you need to match a forward slash, escape it with a backslash, eg -'/\/=:'. - - If REGEX contains parenthesised match groups, these can be referenced -by the usual backslash and number in REPLACEMENT: - -alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 -; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - REPLACEMENT continues to the end of line (or on command line, to end -of option argument), so it can contain trailing whitespace. - - -File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive - -9.19.3 Combining aliases ------------------------- - -You can define as many aliases as you like, using journal directives -and/or command line options. - - Recursive aliases - where an account name is rewritten by one alias, -then by another alias, and so on - are allowed. Each alias sees the -effect of previously applied aliases. - - In such cases it can be important to understand which aliases will be -applied and in which order. For (each account name in) each journal -entry, we apply: - - 1. 'alias' directives preceding the journal entry, most recently - parsed first (ie, reading upward from the journal entry, bottom to - top) - 2. '--alias' options, in the order they appeared on the command line - (left to right). - - In other words, for (an account name in) a given journal entry: - - * the nearest alias declaration before/above the entry is applied - first - * the next alias before/above that will be be applied next, and so on - * aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps -provide semantic stability - aliases will keep working the same way -independent of which files are being read and in which order. - - In case of trouble, adding '--debug=6' to the command line will show -which aliases are being applied when. - - -File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive - -9.19.4 Aliases and multiple files ---------------------------------- - -As explained at Directives and multiple files, 'alias' directives do not -affect parent or sibling files. Eg in this command, - -hledger -f a.aliases -f b.journal - - account aliases defined in a.aliases will not affect b.journal. -Including the aliases doesn't work either: - -include a.aliases - -2023-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 - -2023-01-01 ; affected by aliases above - foo 1 - bar - -include c.journal ; also affected - - -File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive - -9.19.5 'end aliases' directive ------------------------------- - -You can clear (forget) all currently defined aliases (seen in the -journal so far, or defined on the command line) with this directive: - -end aliases - - -File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive - -9.19.6 Aliases can generate bad account names ---------------------------------------------- - -Be aware that account aliases can produce malformed account names, which -could cause confusing reports or invalid 'print' output. For example, -you could erase all account names: - -2021-01-01 - a:aa 1 - b - -$ hledger print --alias '/.*/=' -2021-01-01 - 1 - - The above 'print' output is not a valid journal. Or you could insert -an illegal double space, causing 'print' output that would give a -different journal when reparsed: - -2021-01-01 - old 1 - other - -$ hledger print --alias old="new USD" | hledger -f- print -2021-01-01 - new USD 1 - other - - -File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive - -9.19.7 Aliases and account types --------------------------------- - -If an account with a type declaration (see Declaring accounts > Account -types) is renamed by an alias, normally the account type remains in -effect. - - However, renaming in a way that reshapes the account tree (eg -renaming parent accounts but not their children, or vice versa) could -prevent child accounts from inheriting the account type of their -parents. - - Secondly, if an account's type is being inferred from its name, -renaming it by an alias could prevent or alter that. - - If you are using account aliases and the 'type:' query is not -matching accounts as you expect, try troubleshooting with the accounts -command, eg something like: - -$ hledger accounts --alias assets=bassetts type:a - - -File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal - -9.20 'commodity' directive -========================== - -The 'commodity' directive performs several functions: - - 1. It declares which commodity symbols may be used in the journal, - enabling useful error checking with strict mode or the check - command. (See Commodity error checking below.) - - 2. It declares the precision with which this commodity's amounts - should be compared when checking for balanced transactions. - - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See Commodity display style above.) - - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no 'decimal-mark' - directive in effect. See Decimal marks, digit group marks above. - For related dev discussion, see #793.) - - Declaring commodities solves several common parsing/display problems, -so we recommend it. Generally you should put 'commodity' directives at -the top of your journal file (because function 4 is position-sensitive). - -* Menu: - -* Commodity directive syntax:: -* Commodity error checking:: - - -File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive - -9.20.1 Commodity directive syntax ---------------------------------- - -A commodity directive is normally the word 'commodity' followed by a -sample amount (and optionally a comment). Only the amount's symbol and -format is significant. Eg: - -commodity $1000.00 -commodity 1.000,00 EUR -commodity 1 000 000.0000 ; the no-symbol commodity - - A commodity directive's sample amount must always include a period or -comma decimal mark (this rule helps disambiguate decimal marks and digit -group marks). If you don't want to show any decimal digits, write the -decimal mark at the end: - -commodity 1000. AAAA ; show AAAA with no decimals - - Commodity symbols containing spaces, numbers, or punctuation must be -enclosed in double quotes, as usual: - -commodity 1.0000 "AAAA 2023" - - Commodity directives normally include a sample amount, but can -declare only a symbol (ie, just function 1 above): - -commodity $ -commodity INR -commodity "AAAA 2023" -commodity "" ; the no-symbol commodity - - Commodity directives may also be written with an indented 'format' -subdirective, as in Ledger. The symbol is repeated and must be the same -in both places. Other subdirectives are currently ignored: - -; 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 - an unsupported subdirective ; ignored by hledger - - -File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive - -9.20.2 Commodity error checking -------------------------------- - -In strict mode ('-s'/'--strict') (or when you run 'hledger check -commodities'), hledger will report an error if an undeclared commodity -symbol is used. (With one exception: zero amounts are always allowed to -have no commodity symbol.) It works like account error checking -(described above). - - -File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal - -9.21 'decimal-mark' directive -============================= - -You can use a 'decimal-mark' directive - usually one per file, at the -top of the file - to declare which character represents a decimal mark -when parsing amounts in this file. It can look like - -decimal-mark . - - or - -decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we -recommend it, especially if the file contains digit group marks (eg -thousands separators). - - -File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal - -9.22 'include' directive -======================== - -You can pull in the content of additional files by writing an include -directive, like this: - -include FILEPATH - - Only journal files can include, and only journal, timeclock or -timedot files can be included (not CSV files, currently). - - If the file path does not begin with a slash, it is relative to the -current file's folder. - - A tilde means home directory, eg: 'include ~/main.journal'. - - The path may contain glob patterns to match multiple files, eg: -'include *.journal'. - - There is limited support for recursive wildcards: '**/' (the slash is -required) matches 0 or more subdirectories. It's not super convenient -since you have to avoid include cycles and including directories, but -this can be done, eg: 'include */**/*.journal'. - - The path may also be prefixed to force a specific file format, -overriding the file extension (as described in Data formats): 'include -timedot:~/notes/2023*.md'. - - -File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal - -9.23 'P' directive -================== - -The 'P' directive declares a market price, which is a conversion rate -between two commodities on a certain date. This allows value reports to -convert amounts of one commodity to their value in another, on or after -that date. These prices are often obtained from a stock exchange, -cryptocurrency exchange, the or foreign exchange market. - - The format is: - -P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the -commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and -quantity) of commodity 2 that one unit of commodity 1 is worth on this -date. Examples: - -# one euro was worth $1.35 from 2009-01-01 onward: -P 2009-01-01 € $1.35 - -# and $1.40 from 2010-01-01 onward: -P 2010-01-01 € $1.40 - - The '-V', '-X' and '--value' flags use these market prices to show -amount values in another commodity. See Value reporting. - - -File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal - -9.24 'payee' directive -====================== - -'payee PAYEE NAME' - - This directive can be used to declare a limited set of payees which -may appear in transaction descriptions. The "payees" check will report -an error if any transaction refers to a payee that has not been -declared. Eg: - -payee Whole Foods - - Any indented subdirectives are currently ignored. - - -File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal - -9.25 'tag' directive -==================== - -'tag TAGNAME' - - This directive can be used to declare a limited set of tag names -allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - -tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is -used. It is quite easy to accidentally create a tag through normal use -of colons in comments(#comments]; if you want to prevent this, you can -declare and check your tags . - - -File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal - -9.26 Periodic transactions -========================== - -The '~' directive declares recurring transactions. Such directives -allow hledger to generate temporary future transactions (visible in -reports, not in the journal file) to help with forecasting or budgeting. - - Periodic transactions can be a little tricky, so before you use them, -read this whole section, or at least these tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - 2. For troubleshooting, show the generated transactions with 'hledger - print --forecast tag:generated' or 'hledger register --forecast - tag:generated'. - 3. Forecasted transactions will begin only after the last - non-forecasted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. - See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs - improvement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in 'weekly from DATE', DATE - must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give - an error. - 7. Other period expressions with an interval are automatically - expanded to cover a whole number of that interval. (This is done - to improve reports, but it also affects periodic transactions. - Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th - day of month from 2023/01', which is equivalent to '~ every 10th - day of month from 2023/01/01', will be adjusted to start on - 2019/12/10. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -9.26.1 Periodic rule syntax ---------------------------- - -A periodic transaction rule looks like a normal journal entry, with the -date replaced by a tilde ('~') followed by a period expression -(mnemonic: '~' looks like a recurring sine wave.): - -# every first of month -~ monthly - expenses:rent $2000 - assets:bank:checking - -# every 15th of month in 2023's first quarter: -~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying -multi-period reports, just interpreted differently; there, it specifies -report periods; here it specifies recurrence dates (the periods' start -dates). - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -9.26.2 Periodic rules and relative dates ----------------------------------------- - -Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', -'next quarter') are usually not recommended in periodic rules, since the -results will change as time passes. If used, they will be interpreted -relative to, in order of preference: - - 1. the first day of the default year specified by a recent 'Y' - directive - 2. or the date specified with '--today' - 3. or the date on which you are running the report. - - They will not be affected at all by report period or forecast period -dates. - - -File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions - -9.26.3 Two spaces between period expression and description! ------------------------------------------------------------- - -If the period expression is followed by a transaction description, these -must be separated by *two or more spaces*. This helps hledger know -where the period expression ends, so that descriptions can not -accidentally alter their meaning, as in this example: - -; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" -; || -; vv -~ every 2 months in 2023, 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: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal - -9.27 Auto postings -================== - -The '=' directive declares a rule for generating temporary extra -postings on transactions. Wherever the rule matches an existing -posting, it can add one or more companion postings below that one, -optionally influenced by the matched posting's amount. This can be -useful for generating tax postings with a standard percentage, for -example. - - Note that depending on generated data is not ideal for financial -records (it's less portable, less future-proof, less auditable by -others, and less robust, since other features like balance assertions -will depend on using or not using '--auto'). - - 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:: - - -File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings - -9.27.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). - -* Menu: - -* Auto postings and dates:: -* Auto postings and transaction balancing / inferred amounts / balance assertions:: -* Auto posting tags:: -* Auto postings on forecast transactions only:: - - -File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files - -9.27.1.1 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 and multiple files - -9.27.1.2 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, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files - -9.27.1.3 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: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files - -9.27.1.4 Auto postings on forecast transactions only -.................................................... - -Tip: you can can make auto postings that will apply to forecast -transactions but not recorded transactions, by adding -'tag:_generated-transaction' to their QUERY. This can be useful when -generating new journal entries to be saved in the journal. - - -File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal - -9.28 Other syntax -================= - -hledger journal format supports quite a few other features, mainly to -make interoperating with or converting from Ledger easier. Note some of -the features below are powerful and can be useful in special cases, but -in general, features in this section are considered less important or -even not recommended for most users. Downsides are mentioned to help -you decide if you want to use them. - -* Menu: - -* Balance assignments:: -* Bracketed posting dates:: -* D directive:: -* apply account directive:: -* Y directive:: -* Secondary dates:: -* Star comments:: -* Valuation expressions:: -* Virtual postings:: -* Other Ledger directives:: - - -File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax - -9.28.1 Balance assignments --------------------------- - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). - - Downsides: using balance assignments makes your journal less -explicit; to know the exact amount posted, you have to run hledger or do -the calculations yourself, instead of just reading it. Also balance -assignments' forcing of balances can hide errors. These things make -your financial data less portable, less future-proof, and less -trustworthy in an audit. - -* Menu: - -* Balance assignments and prices:: -* Balance assignments and multiple files:: - - -File: hledger.info, Node: Balance assignments and prices, Next: Balance assignments and multiple files, Up: Balance assignments - -9.28.1.1 Balance assignments and prices -....................................... - -A cost in a balance assignment will cause the calculated amount to have -that price attached: - -2019/1/1 - (a) = $1 @ €2 - -$ hledger print --explicit -2019-01-01 - (a) $1 @ €2 = $1 @ €2 - - -File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and prices, Up: Balance assignments - -9.28.1.2 Balance assignments and multiple files -............................................... - -Balance assignments handle multiple files like balance assertions. They -see balance from other files previously included from the current file, -but not from previous sibling or parent files. - - -File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax - -9.28.2 Bracketed posting dates ------------------------------- - -For setting posting dates and secondary posting dates, Ledger's -bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or -'[=DATE2]' in posting comments. hledger will attempt to parse any -square-bracketed sequence of the '0123456789/-.=' characters in this -way. With this syntax, DATE infers its year from the transaction and -DATE2 infers its year from DATE. - - Downsides: another syntax to learn, redundant with hledger's -'date:'/'date2:' tags, and confusingly similar to Ledger's lot date -syntax. - - -File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax - -9.28.3 'D' directive --------------------- - -'D AMOUNT' - - This directive sets a default commodity, to be used for any -subsequent commodityless amounts (ie, plain numbers) seen while parsing -the journal. This effect lasts until the next 'D' directive, or the end -of the journal. - - For compatibility/historical reasons, 'D' also acts like a -'commodity' directive (setting the commodity's decimal mark for parsing -and display style for output). So its argument is not just a commodity -symbol, but a full amount demonstrating the style. The amount must -include a decimal mark (either period or comma). Eg: - -; commodity-less amounts should be treated as dollars -; (and displayed with the dollar sign on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity's display style, a 'commodity' directive has -highest priority, then a 'D' directive. - - For detecting a commodity's decimal mark during parsing, -'decimal-mark' has highest priority, then 'commodity', then 'D'. - - For checking commodity symbols with the check command, a 'commodity' -directive is required ('hledger check commodities' ignores 'D' -directives). - - Downsides: omitting commodity symbols makes your financial data less -explicit, less portable, and less trustworthy in an audit. It is -usually an unsustainable shortcut; sooner or later you will want to -track multiple commodities. D is overloaded with functions redundant -with 'commodity' and 'decimal-mark'. And it works differently from -Ledger's 'D'. - - -File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax - -9.28.4 'apply account' directive --------------------------------- - -This directive sets a default parent account, which will be prepended to -all accounts in following entries, until an 'end apply account' -directive or end of current file. Eg: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - 'account' directives are also affected, and so is any 'include'd -content. - - Account names entered via hledger add or hledger-web are not -affected. - - Account aliases, if any, are applied after the parent account is -prepended. - - Downsides: this can make your financial data less explicit, less -portable, and less trustworthy in an audit. - - -File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax - -9.28.5 'Y' directive --------------------- - -'Y YEAR' - - or (deprecated backward-compatible forms): - - 'year YEAR' 'apply year YEAR' - - The space is optional. This sets a default year to be used for -subsequent dates which don't specify a year. Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -year 2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at -least) makes your financial data less explicit, less portable, and less -trustworthy in an audit. Such dates can get separated from their -corresponding Y directive, eg when evaluating a region of the journal in -your editor. A missing Y directive makes reports dependent on today's -date. - - -File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax - -9.28.6 Secondary dates ----------------------- - -A secondary date is written after the primary date, following an equals -sign. If the year is omitted, the primary date's year is assumed. When -running reports, the primary (left) date is used by default, but with -the '--date2' flag (or '--aux-date' or '--effective'), the secondary -(right) date will be used instead. - - The meaning of secondary dates is up to you, but it's best to follow -a consistent rule. Eg "primary = the bank's clearing date, secondary = -date the transaction was initiated, if different". - - Downsides: makes your financial data more complicated, less portable, -and less trustworthy in an audit. Keeping the meaning of the two dates -consistent requires discipline, and you have to remember which reporting -mode is appropriate for a given report. Posting dates are simpler and -better. - - -File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax - -9.28.7 Star comments --------------------- - -Lines beginning with '*' (star/asterisk) are also comment lines. This -feature allows Emacs users to insert org headings in their journal, -allowing them to fold/unfold/navigate it like an outline when viewed -with org mode. - - Downsides: another, unconventional comment syntax to learn. -Decreases your journal's portability. And switching to Emacs org mode -just for folding/unfolding meant losing the benefits of ledger mode; -nowadays you can add outshine mode to ledger mode to get folding without -losing ledger mode's features. - - -File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax - -9.28.8 Valuation expressions ----------------------------- - -Ledger allows a valuation function or value to be written in double -parentheses after an amount. hledger ignores these. - - -File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax - -9.28.9 Virtual postings ------------------------ - -A posting with parentheses around the account name ('(some:account)') is -called a _unbalanced virtual posting_. Such postings do not participate -in transaction balancing. (And if you write them without an amount, a -zero amount is always inferred.) These can occasionally be convenient -for special circumstances, but they violate double entry bookkeeping and -make your data less portable across applications, so many people avoid -using them at all. - - A posting with brackets around the account name ('[some:account]') is -called a _balanced virtual posting_. The balanced virtual postings in a -transaction must add up to zero, just like ordinary postings, but -separately from them. These are not part of double entry bookkeeping -either, but they are at least balanced. An example: - -2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Ordinary postings, whose account names are neither parenthesised nor -bracketed, are called _real postings_. You can exclude virtual postings -from reports with the '-R/--real' flag or a 'real:1' query. - - -File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax - -9.28.10 Other Ledger directives -------------------------------- - -These other Ledger directives are currently accepted but ignored. This -allows hledger to read more Ledger files, but be aware that hledger's -reports may differ from Ledger's if you use these. - -apply fixed COMM AMT -apply tag TAG -assert EXPR -bucket / A ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR -end apply fixed -end apply tag -end apply year -end tag -eval / expr EXPR -python - PYTHONCODE -tag NAME -value EXPR ---command-line-flags - - See also https://hledger.org/ledger.html for a detailed -hledger/Ledger syntax comparison. - - -File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top - -10 CSV -****** - -hledger can read CSV files (Character Separated Value - usually comma, -semicolon, or tab) containing dated records, automatically converting -each record into a transaction. - - (To learn about _writing_ CSV, see CSV output.) - - For best error messages when reading CSV/TSV/SSV files, make sure -they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use -a hledger file prefix (see File Extension below). - - Each CSV file must be described by a corresponding _rules file_. -This contains rules describing the CSV data (header line, fields layout, -date format etc.), how to construct hledger transactions from it, and -how to categorise transactions based on description or other attributes. - - By default hledger looks for a rules file named like the CSV file -with an extra '.rules' extension, in the same directory. Eg when asked -to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'. You can -specify a different rules file with the '--rules-file' option. If no -rules file is found, hledger will create a sample rules file, which -you'll need to adjust. - - At minimum, the rules file must identify the date and amount fields, -and often it also specifies the date format and how many header lines -there are. Here's a simple CSV file and a rules file for it: - -Date, Description, Id, Amount -12/11/2019, Foo, 123, 10.23 - -# basic.csv.rules -skip 1 -fields date, description, , amount -date-format %d/%m/%Y - -$ hledger print -f basic.csv -2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There's an introductory Importing CSV data tutorial on hledger.org, -and more CSV rules examples below, and a larger collection at -https://github.com/simonmichael/hledger/tree/master/examples/csv. - -* Menu: - -* CSV rules cheatsheet:: -* source:: -* separator:: -* skip:: -* date-format:: -* timezone:: -* newest-first:: -* intra-day-reversed:: -* decimal-mark:: -* fields list:: -* Field assignment:: -* Field names:: -* if block:: -* Matchers:: -* if table:: -* balance-type:: -* include:: -* Working with CSV:: -* CSV rules examples:: - - -File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV - -10.1 CSV rules cheatsheet -========================= - -The following kinds of rule can appear in the rules file, in any order. -(Blank lines and lines beginning with '#' or ';' or '*' are ignored.) - -*'source'* optionally declare which file to read data - from -*'separator'* declare the field separator, instead of - relying on file extension -*'skip'* skip one or more header lines at start of file -*'date-format'* declare how to parse CSV dates/date-times -*'timezone'* declare the time zone of ambiguous CSV - date-times -*'newest-first'* improve txn order when: there are multiple - records, newest first, all with the same date -*'intra-day-reversed'* improve txn order when: same-day txns are in - opposite order to the overall file -*'decimal-mark'* declare the decimal mark used in CSV amounts, - when ambiguous -*'fields' list* name CSV fields for easy reference, and - optionally assign their values to hledger - fields -*Field assignment* assign a CSV value or interpolated text value - to a hledger field -*'if' block* conditionally assign values to hledger fields, - or 'skip' a record or 'end' (skip rest of - file) -*'if' table* conditionally assign values to hledger fields, - using compact syntax -*'balance-type'* select which type of balance - assertions/assignments to generate -*'include'* inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are -evaluated. - - -File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV - -10.2 'source' -============= - -If you tell hledger to read a csv file with '-f foo.csv', it will look -for rules in 'foo.csv.rules'. Or, you can tell it to read the rules -file, with '-f foo.csv.rules', and it will look for data in 'foo.csv' -(since 1.30). - - These are mostly equivalent, but the second method provides some -extra features. For one, the data file can be missing, without causing -an error; it is just considered empty. And, you can specify a different -data file by adding a "source" rule: - -source ./Checking1.csv - - If you specify just a file name with no path, hledger will look for -it in your system's downloads directory ('~/Downloads', currently): - -source Checking1.csv - - And if you specify a glob pattern, hledger will read the most recent -of the matched files (useful with repeated downloads): - -source Checking1*.csv - - See also "Working with CSV > Reading files specified by rule". - - -File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV - -10.3 'separator' -================ - -You can use the 'separator' rule to read other kinds of -character-separated data. The argument is any single separator -character, or the words 'tab' or 'space' (case insensitive). Eg, for -comma-separated values (CSV): - -separator , - - or for semicolon-separated values (SSV): - -separator ; - - or for tab-separated values (TSV): - -separator TAB - - If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a -'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be -inferred automatically, and you won't need this rule. - - -File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV - -10.4 'skip' -=========== - -skip N - - The word 'skip' followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines at the start of the input -data. You'll need this whenever your CSV data contains header lines. -Note, empty and blank lines are skipped automatically, so you don't need -to count those. - - 'skip' has a second meaning: it can be used inside if blocks -(described below), to skip one or more records whenever the condition is -true. Records skipped in this way are ignored, except they are still -required to be valid CSV. - - -File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV - -10.5 'date-format' -================== - -date-format DATEFMT - - This is a helper for the 'date' (and 'date2') fields. If your CSV -dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD', -you'll need to add a date-format rule describing them with a -strptime-style date parsing pattern - see -https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. -The pattern must parse the CSV date value completely. Some examples: - -# MM/DD/YY -date-format %m/%d/%y - -# D/M/YYYY -# The - makes leading zeros optional. -date-format %-d/%-m/%Y - -# YYYY-Mmm-DD -date-format %Y-%h-%d - -# M/D/YYYY HH:MM AM some other junk -# Note the time and junk must be fully parsed, though only the date is used. -date-format %-m/%-d/%Y %l:%M %p some other junk - - -File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV - -10.6 'timezone' -=============== - -timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone -other than yours, but containing no explicit time zone information, you -can use this rule to declare the CSV's native time zone, which helps -prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don't -need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ', -'%Ez'; see the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware -conversion, localising the CSV date-times to your current system time -zone. If you prefer to localise to some other time zone, eg for -reproducibility, you can (on unix at least) set the output timezone with -the TZ environment variable, eg: - -$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - 'timezone' currently does not understand timezone names, except -"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". -For others, use numeric format: +HHMM or -HHMM. - - -File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV - -10.7 'newest-first' -=================== - -hledger tries to ensure that the generated transactions will be ordered -chronologically, including same-day transactions. Usually it can -auto-detect how the CSV records are ordered. But if it encounters CSV -where all records are on the same date, it assumes that the records are -oldest first. If in fact the CSV's records are normally newest first, -like: - -2022-10-01, txn 3... -2022-10-01, txn 2... -2022-10-01, txn 1... - - you can add the 'newest-first' rule to help hledger generate the -transactions in correct order. - -# same-day CSV records are newest first -newest-first - - -File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV - -10.8 'intra-day-reversed' -========================= - -If CSV records within a single day are ordered opposite to the overall -record order, you can add the 'intra-day-reversed' rule to improve the -order of journal entries. Eg, here the overall record order is newest -first, but same-day records are oldest first: - -2022-10-02, txn 3... -2022-10-02, txn 4... -2022-10-01, txn 1... -2022-10-01, txn 2... - -# transactions within each day are reversed with respect to the overall date order -intra-day-reversed - - -File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV - -10.9 'decimal-mark' -=================== - -decimal-mark . - - or: - -decimal-mark , - - hledger automatically accepts either period or comma as a decimal -mark when parsing numbers (cf Amounts). However if any numbers in the -CSV contain digit group marks, such as thousand-separating commas, you -should declare the decimal mark explicitly with this rule, to avoid -misparsed numbers. - - -File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV - -10.10 'fields' list -=================== - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word 'fields' followed by comma-separated field -names) is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say - '%SomeField' instead of remembering '%13'. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and - build a transaction. - - Here's an example that says "use the 1st, 2nd and 4th fields as the -transaction's date, description and amount; name the last two fields for -later reference; and ignore the others": - -fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to -the CSV file's separator. Also: - - * There must be least two items in the list (at least one comma). - * Field names may not contain spaces. Spaces before/after field - names are optional. - * Field names may contain '_' (underscore) or '-' (hyphen). - * Fields you don't care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it's convenient to use these for -your field names, suitably modified (eg lower-cased with spaces replaced -by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning -to a hledger field with the same name. Eg you could call the CSV's -"balance" field 'balance_' to avoid directly setting hledger's 'balance' -field (and generating a balance assertion). - - -File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV - -10.11 Field assignment -====================== - -HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to -hledger fields. They can be used instead of or in addition to a fields -list (see above). - - To assign a value to a hledger field, write the field name (any of -the standard hledger field/pseudo-field names, defined below), a space, -followed by a text value on the same line. This text value may -interpolate CSV fields, referenced either by their 1-based position in -the CSV record ('%N') or by the name they were given in the fields list -('%CSVFIELD'), and regular expression match groups ('\N'). - - Some examples: - -# set the amount to the 4th CSV field, with " USD" appended -amount %4 USD - -# combine three fields to make a comment, containing note: and date: tags -comment note: %somefield - %anotherfield, date: %1 - - Tips: - - * Interpolation strips outer whitespace (so a CSV value like '" 1 "' - becomes '1' when interpolated) (#1051). - * Interpolations always refer to a CSV field - you can't interpolate - a hledger field. (See Referencing other fields below). - - -File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV - -10.12 Field names -================= - -Note the two kinds of field names mentioned here, and used only in -hledger CSV rules files: - - 1. *CSV field names* ('CSVFIELD' in these docs): you can optionally - name the CSV columns for easy reference (since hledger doesn't yet - automatically recognise column headings in a CSV file), by writing - arbitrary names in a 'fields' list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you - must set at least some of these to generate the hledger transaction - from a CSV record, by writing them as the left hand side of a field - assignment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a 'fields' list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what -happens when you assign values to them: - -* Menu: - -* date field:: -* date2 field:: -* status field:: -* code field:: -* description field:: -* comment field:: -* account field:: -* amount field:: -* currency field:: -* balance field:: - - -File: hledger.info, Node: date field, Next: date2 field, Up: Field names - -10.12.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 - -10.12.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 - -10.12.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 - -10.12.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 - -10.12.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 - -10.12.6 comment field ---------------------- - -'comment' sets the transaction's comment, if any. - - 'commentN', where N is a number, sets the Nth posting's comment. - - You can assign multi-line comments by writing literal '\n' in the -code. A comment starting with '\n' will begin on a new line. - - Comments can contain tags, as usual. - - -File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names - -10.12.7 account field ---------------------- - -Assigning to 'accountN', where N is 1 to 99, sets the account name of -the Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you'll want to set 'account1' -and 'account2'. Typically 'account1' is associated with the CSV file, -and is set once with a top-level assignment, while 'account2' is set -based on each transaction's description, in conditional rules. - - If a posting's account name is left unset but its amount is set (see -below), a default account name will be chosen (like "expenses:unknown" -or "income:unknown"). - - -File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names - -10.12.8 amount field --------------------- - -There are several ways to set posting amounts from CSV, useful in -different situations. - - 1. *'amount'* is the oldest and simplest. Assigning to this sets the - amount of the first and second postings. In the second posting, - the amount will be negated; also, if it has a cost attached, it - will be converted to cost. - - 2. *'amount-in'* and *'amount-out'* work exactly like the above, but - should be used when the CSV has two amount fields (such as "Debit" - and "Credit", or "Inflow" and "Outflow"). Whichever field has a - non-zero value will be used as the amount of the first and second - postings. Here are some tips to avoid confusion: - - * It's not "amount-in for posting 1 and amount-out for posting - 2", it is "extract a single amount from the amount-in or - amount-out field, and use that for posting 1 and (negated) for - posting 2". - * Don't use both 'amount' and 'amount-in'/'amount-out' in the - same rules file; choose based on whether the amount is in a - single CSV field or spread across two fields. - * In each record, at most one of the two CSV fields should - contain a non-zero amount; the other field must contain a zero - or nothing. - * hledger assumes both CSV fields contain unsigned numbers, and - it automatically negates the amount-out values. - * If the data doesn't fit these requirements, you'll probably - need an if rule (see below). - - 3. *'amountN'* (where N is a number from 1 to 99) sets the amount of - only a single posting: the Nth posting in the transaction. You'll - usually need at least two such assignments to make a balanced - transaction. You can also generate more than two postings, to - represent more complex transactions. The posting numbers don't - have to be consecutive; with if rules, higher posting numbers can - be useful to ensure a certain order of postings. - - 4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but - should be used when the CSV has two amount fields. This is - analogous to 'amount-in' and 'amount-out', and those tips also - apply here. - - 5. Remember that a 'fields' list can also do assignments. So in a - fields list if you name a CSV field "amount", that counts as - assigning to 'amount'. (If you don't want that, call it something - else in the fields list, like "amount_".) - - 6. The above don't handle every situation; if you need more - flexibility, use an 'if' rule to set amounts conditionally. See - "Working with CSV > Setting amounts" below for more on this and on - amount-setting generally. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -10.12.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 - -10.12.10 balance field ----------------------- - -'balanceN' sets a balance assertion amount (or if the posting amount is -left empty, a balance assignment) on posting N. - - 'balance' is a compatibility spelling for hledger <1.17; it is -equivalent to 'balance1'. - - You can adjust the type of assertion/assignment with the -'balance-type' rule (see below). - - See Tips below for more about setting amounts and currency. - - -File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV - -10.13 'if' block -================ - -Rules can be applied conditionally, depending on patterns in the CSV -data. This allows flexibility; in particular, it is how you can -categorise transactions, selecting an appropriate account name based on -their description (for example). There are two ways to write -conditional rules: "if blocks", described here, and "if tables", -described below. - - An if block is the word 'if' and one or more "matcher" expressions -(can be a word or phrase), one per line, starting either on the same or -next line; followed by one or more indented rules. Eg, - -if MATCHER - RULE - - or - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be -applied. They are usually field assignments, but the following special -rules may also be used within an if block: - - * 'skip' - skips the matched CSV record (generating no transaction - from it) - * 'end' - skips the rest of the current CSV file. - - Some examples: - -# if the record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the record contains any of these phrases, set account2 and a transaction comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - -# if an empty record is seen (assuming five fields), ignore the rest of the CSV file -if ,,,, - end - - -File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV - -10.14 Matchers -============== - -There are two kinds: - - 1. A record matcher is a word or single-line text fragment or regular - expression ('REGEX'), which hledger will try to match - case-insensitively anywhere within the CSV record. - Eg: 'whole foods' - - 2. A field matcher is preceded with a percent sign and CSV field name - ('%CSVFIELD REGEX'). hledger will try to match these just within - the named CSV field. - Eg: '%date 2023' - - The regular expression is (as usual in hledger) a POSIX extended -regular expression, that also supports GNU word boundaries ('\b', '\B', -'\<', '\>'), and nothing else. If you have trouble, see "Regular -expressions" in the hledger manual -(https://hledger.org/hledger.html#regular-expressions). - - With record matchers, it's important to know that the record matched -is not the original CSV record, but a modified one: separators will be -converted to commas, and enclosing double quotes (but not enclosing -whitespace) are removed. So for example, when reading an SSV file, if -the original record was: - -2023-01-01; "Acme, Inc."; 1,000 - - the regex would see, and try to match, this modified record text: - -2023-01-01,Acme, Inc., 1,000 - - When an if block has multiple matchers, they are combined as follows: - - * By default they are OR'd (any one of them can match) - * When a matcher is preceded by ampersand ('&') it will be AND'ed - with the previous matcher (both of them must match). - - When a matcher is preceded by an exclamation mark (!), the matcher -will be negated, ie it will exclude CSV records that match. - -* Menu: - -* Match groups:: - - -File: hledger.info, Node: Match groups, Up: Matchers - -10.14.1 Match groups --------------------- - -Matchers can define match groups: parenthesised portions of the regular -expression which are available for reference in field assignments. -Groups are enclosed in regular parentheses ('(' and ')') and can be -nested. Each group is available in field assignments using the token -'\N', where N is an index into the match groups for this conditional -block (e.g. '\1', '\2', etc.). - - Example: Warp credit card payment postings to the beginning of the -billing period (Month start), to match how they are presented in -statements, using posting dates: - -if %date (....-..)-.. - comment2 date:\1-01 - - Another example: Read the expense account from the CSV field, but -throw away a prefix: - -if %account1 liabilities:family:(expenses:.*) - account1 \1 - - -File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV - -10.15 'if' table -================ - -"if tables" are an alternative to if blocks; they can express many -matchers and field assignments in a more compact tabular format, like -this: - -if,HLEDGERFIELD1,HLEDGERFIELD2,... -MATCHERA,VALUE1,VALUE2,... -MATCHERB,VALUE1,VALUE2,... -MATCHERC,VALUE1,VALUE2,... - - - The first character after 'if' is taken to be this if table's field -separator. It is unrelated to the separator used in the CSV file. It -should be a non-alphanumeric character like ',' or '|' that does not -appear anywhere else in the table (it should not be used in field names -or matchers or values, and it cannot be escaped with a backslash). - - Each line must contain the same number of separators; empty values -are allowed. Whitespace can be used in the matcher lines for -readability (but not in the if line, currently). The table must be -terminated by an empty line (or end of file). - - An if table like the above is interpreted as follows: try all of the -matchers; whenever a matcher succeeds, assign all of the values on that -line to the corresponding hledger fields; later lines can overrider -earlier ones. It is equivalent to this sequence of if blocks: - -if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERB - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - -if,account2,comment -atm transaction fee,expenses:business:banking,deductible? check it -%description groceries,expenses:groceries, -2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - -File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV - -10.16 'balance-type' -==================== - -Balance assertions generated by assigning to balanceN are of the simple -'=' type by default, which is a single-commodity, subaccount-excluding -assertion. You may find the subaccount-including variants more useful, -eg if you have created some virtual subaccounts of checking to help with -budgeting. You can select a different type of assertion with the -'balance-type' rule: - -# balance assertions will consider all commodities and all subaccounts -balance-type ==* - - Here are the balance assertion types for quick reference: - -= single commodity, exclude subaccounts -=* single commodity, include subaccounts -== multi commodity, exclude subaccounts -==* multi commodity, include subaccounts - - -File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV - -10.17 'include' -=============== - -include RULESFILE - - This includes the contents of another CSV rules file at this point. -'RULESFILE' is an absolute file path or a path relative to the current -file's directory. This can be useful for sharing common rules between -several rules files, eg: - -# someaccount.csv.rules - -## someaccount-specific rules -fields date,description,amount -account1 assets:someaccount -account2 expenses:misc - -## common rules -include categorisation.rules - - -File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV - -10.18 Working with CSV -====================== - -Some tips: - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading CSV from standard input:: -* Reading multiple CSV files:: -* Reading files specified by rule:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Amount signs:: -* Setting currency/commodity:: -* Amount decimal places:: -* Referencing other fields:: -* How CSV rules are evaluated:: -* Well factored rules:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV - -10.18.1 Rapid feedback ----------------------- - -It's a good idea to get rapid feedback while creating/troubleshooting -CSV rules. Here's a good way, using entr from eradman.com/entrproject: - -$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - - A desc: query (eg) is used to select just one, or a few, transactions -of interest. "bash -c" is used to run multiple commands, so we can echo -a separator each time the command re-runs, making it easier to read the -output. - - -File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV - -10.18.2 Valid CSV ------------------ - -Note that hledger will only accept valid CSV conforming to RFC 4180, and -equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab -as separators). This means, eg: - - * Values may be enclosed in double quotes, or not. Enclosing in - single quotes is not allowed. (Eg ''A','B'' is rejected.) - * When values are enclosed in double quotes, spaces outside the - quotes are not allowed. (Eg '"A", "B"' is rejected.) - * When values are not enclosed in quotes, they may not contain double - quotes. (Eg 'A"A, B' is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you'll need to -transform it before reading with hledger. Try using sed, or a more -permissive CSV parser like python's csv lib. - - -File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV - -10.18.3 File Extension ----------------------- - -To help hledger choose the CSV file reader and show the right error -messages (and choose the right field separator character by default), -it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv' -filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV -reader (and the default field separator) by prefixing the file path with -'csv:', 'ssv:' or 'tsv:': Eg: - -$ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator -rule if needed. - - -File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV - -10.18.4 Reading CSV from standard input ---------------------------------------- - -You'll need the file format prefix when reading CSV from stdin also, -since hledger assumes journal format by default. Eg: - -$ cat foo.dat | hledger -f ssv:- print - - -File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV - -10.18.5 Reading multiple CSV files ----------------------------------- - -If you use multiple '-f' options to read multiple CSV files at once, -hledger will look for a correspondingly-named rules file for each CSV -file. But if you use the '--rules-file' option, that rules file will be -used for all the CSV files. - - -File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV - -10.18.6 Reading files specified by rule ---------------------------------------- - -Instead of specifying a CSV file in the command line, you can specify a -rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will -read data from foo.csv in the same directory, but you can add a source -rule to specify a different data file, perhaps located in your web -browser's download directory. - - This feature was added in hledger 1.30, so you won't see it in most -CSV rules examples. But it helps remove some of the busywork of -managing CSV downloads. Most of your financial institutions's default -CSV filenames are different and can be recognised by a glob pattern. So -you can put a rule like 'source Checking1*.csv' in -foo-checking.csv.rules, and then periodically follow a workflow like: - - 1. Download CSV from Foo's website, using your browser's defaults - 2. Run 'hledger import foo-checking.csv.rules' to import any new - transactions - - After import, you can: discard the CSV, or leave it where it is for a -while, or move it into your archives, as you prefer. If you do nothing, -next time your browser will save something like Checking1-2.csv, and -hledger will use that because of the '*' wild card and because it is the -most recent. - - -File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV - -10.18.7 Valid transactions --------------------------- - -After reading a CSV file, hledger post-processes and validates the -generated journal entries as it would for a journal file - balancing -them, applying balance assignments, and canonicalising amount styles. -Any errors at this stage will be reported in the usual way, displaying -the problem entry. - - There is one exception: balance assertions, if you have generated -them, will not be checked, since normally these will work only when the -CSV data is part of the main journal. If you do need to check balance -assertions generated from CSV right away, pipe into another hledger: - -$ hledger -f file.csv print | hledger -f- print - - -File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV - -10.18.8 Deduplicating, importing --------------------------------- - -When you download a CSV file periodically, eg to get your latest bank -transactions, the new file may overlap with the old one, containing some -of the same records. - - The import command will (a) detect the new transactions, and (b) -append just those transactions to your main journal. It is idempotent, -so you don't have to remember how many times you ran it or with which -version of the CSV. (It keeps state in a hidden '.latest.FILE.csv' -file.) This is the easiest way to import CSV data. Eg: - -# download the latest CSV files, then run this command. -# Note, no -f flags needed here. -$ hledger import *.csv [--dry] - - This method works for most CSV files. (Where records have a stable -chronological order, and new records appear only at the new end.) - - A number of other tools and workflows, hledger-specific and -otherwise, exist for converting, deduplicating, classifying and managing -CSV data. See: - - * https://hledger.org/cookbook.html#setups-and-workflows - * https://plaintextaccounting.org -> data import/conversion - - -File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV - -10.18.9 Setting amounts ------------------------ - -Continuing from amount field above, here are more tips for -amount-setting: - - 1. *If the amount is in a single CSV field:* - - a. *If its sign indicates direction of flow:* - Assign it to 'amountN', to set the Nth posting's amount. N is - usually 1 or 2 but can go up to 99. - - b. *If another field indicates direction of flow:* - Use one or more conditional rules to set the appropriate - amount sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. *If the amount is in two CSV fields (such as Debit and Credit, or - In and Out):* - - a. *If both fields are unsigned:* - Assign one field to 'amountN-in' and the other to - 'amountN-out'. hledger will automatically negate the "out" - field, and will use whichever field value is non-zero as - posting N's amount. - - b. *If either field is signed:* - You will probably need to override hledger's sign for one or - the other field, as in the following example: - - # Negate the -out value, but only if it is not empty: - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields can contain a non-zero value (or both can be - empty):* - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such - as '1' and 'none'. For such cases, use conditional rules to - help select the amount. Eg, to handle the above you could - select the value containing non-zero digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. *If you want posting 2's amount converted to cost:* - Use the unnumbered 'amount' (or 'amount-in' and 'amount-out') - syntax. - - 4. *If the CSV has only balance amounts, not transaction amounts:* - Assign to 'balanceN', to set a balance assignment on the Nth - posting, causing the posting's amount to be calculated - automatically. 'balance' with no number is equivalent to - 'balance1'. In this situation hledger is more likely to guess the - wrong default account name, so you may need to set that explicitly. - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV - -10.18.10 Amount signs ---------------------- - -There is some special handling making it easier to parse and to reverse -amount signs. (This only works for whole amounts, not for cost amounts -such as COST in 'amount1 AMT @ COST'): - - * *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 '""'. - - It's not possible (without preprocessing the CSV) to set an amount to -its absolute value, ie discard its sign. - - -File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV - -10.18.11 Setting currency/commodity ------------------------------------ - -If the currency/commodity symbol is included in the CSV's amount -field(s): - -2023-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 - -2023-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - -2023-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 - -2023-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 - -2023-01-01 foo - expenses:unknown 123.00 USD - income:unknown -123.00 USD - - Note we used a temporary field name ('cur') that is not 'currency' - -that would trigger the prepending effect, which we don't want here. - - -File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV - -10.18.12 Amount decimal places ------------------------------- - -Like amounts in a journal file, the amounts generated by CSV rules like -'amount1' influence commodity display styles, such as the number of -decimal places displayed in reports. - - The original amounts as written in the CSV file do not affect display -style (because we don't yet reliably know their commodity). - - -File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV - -10.18.13 Referencing other fields ---------------------------------- - -In field assignments, you can interpolate only CSV fields, not hledger -fields. In the example below, there's both a CSV field and a hledger -field named amount1, but %amount1 always means the CSV field, not the -hledger field: - -# Name the third CSV field "amount1" -fields date,description,amount1 - -# Set hledger's amount1 to the CSV amount1 field followed by USD -amount1 %amount1 USD - -# Set comment to the CSV amount1 (not the amount1 assigned above) -comment %amount1 - - Here, since there's no CSV amount1 field, %amount1 will produce a -literal "amount1": - -fields date,description,csvamount -amount1 %csvamount USD -# Can't interpolate amount1 here -comment %amount1 - - When there are multiple field assignments to the same hledger field, -only the last one takes effect. Here, comment's value will be be B, or -C if "something" is matched, but never A: - -comment A -comment B -if something - comment C - - -File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV - -10.18.14 How CSV rules are evaluated ------------------------------------- - -Here's how to think of CSV rules being evaluated (if you really need -to). First, - - * 'include' - all includes are inlined, from top to bottom, depth - first. (At each include point the file is inlined and scanned for - further includes, recursively, before proceeding.) - - Then "global" rules are evaluated, top to bottom. If a rule is -repeated, the last one wins: - - * 'skip' (at top level) - * 'date-format' - * 'newest-first' - * 'fields' - names the CSV fields, optionally sets up initial - assignments to hledger fields - - Then for each CSV record in turn: - - * test all 'if' blocks. If any of them contain a 'end' rule, skip - all remaining CSV records. Otherwise if any of them contain a - 'skip' rule, skip that many CSV records. If there are multiple - matched 'skip' rules, the first one wins. - * collect all field assignments at top level and in matched 'if' - blocks. When there are multiple assignments for a field, keep only - the last one. - * compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELD references), or a - default - * generate a hledger transaction (journal entry) from these values. - - This is all part of the CSV reader, one of several readers hledger -can use to parse input files. When all files have been read -successfully, the transactions are passed as input to whichever hledger -command the user specified. - - -File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV - -10.18.15 Well factored rules ----------------------------- - -Some things than can help reduce duplication and complexity in rules -files: - - * Extracting common rules usable with multiple CSV files into a - 'common.rules', and adding 'include common.rules' to each CSV's - rules file. - - * Splitting if blocks into smaller if blocks, extracting the - frequently used parts. - - -File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV - -10.19 CSV rules examples -======================== - -* Menu: - -* Bank of Ireland:: -* Coinbase:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples - -10.19.1 Bank of Ireland ------------------------ - -Here's a CSV with two amount fields (Debit and Credit), and a balance -field, which we can use to add balance assertions, which is not -necessary but provides extra error checking: - -Date,Details,Debit,Credit,Balance -07/12/2012,LODGMENT 529898,,10.0,131.21 -07/12/2012,PAYMENT,5,,126 - -# bankofireland-checking.csv.rules - -# skip the header line -skip - -# name the csv fields, and assign some of them as journal entry fields -fields date, description, amount-out, amount-in, balance - -# We generate balance assertions by assigning to "balance" -# above, but you may sometimes need to remove these because: -# -# - the CSV balance differs from the true balance, -# by up to 0.0000000000005 in my experience -# -# - it is sometimes calculated based on non-chronological ordering, -# eg when multiple transactions clear on the same day - -# date is in UK/Ireland format -date-format %d/%m/%Y - -# set the currency -currency EUR - -# set the base account for all txns -account1 assets:bank:boi:checking - -$ hledger -f bankofireland-checking.csv print -2012-12-07 LODGMENT 529898 - assets:bank:boi:checking EUR10.0 = EUR131.2 - income:unknown EUR-10.0 - -2012-12-07 PAYMENT - assets:bank:boi:checking EUR-5.0 = EUR126.0 - expenses:unknown EUR5.0 - - The balance assertions don't raise an error above, because we're -reading directly from CSV, but they will be checked if these entries are -imported into a journal file. - - -File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples - -10.19.2 Coinbase ----------------- - -A simple example with some CSV from Coinbase. The spot price is -recorded using cost notation. The legacy 'amount' field name -conveniently sets amount 2 (posting 2's amount) to the total cost. - -# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes -# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - -# coinbase.csv.rules -skip 1 -fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes -date %Timestamp -date-format %Y-%m-%dT%T%Z -description %Notes -account1 assets:coinbase:cc -amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - -$ hledger print -f coinbase.csv -2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - -File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples - -10.19.3 Amazon --------------- - -Here we convert amazon.com order history, and use an if block to -generate a third posting if there's a fee. (In practice you'd probably -get this data from your bank instead, but it's an example.) - -"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" -"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" -"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" - -# amazon-orders.csv.rules - -# skip one header line -skip 1 - -# name the csv fields, and assign the transaction's date, amount and code. -# Avoided the "status" and "amount" hledger field names to prevent confusion. -fields date, _, toorfrom, name, amzstatus, amzamount, fees, code - -# how to parse the date -date-format %b %-d, %Y - -# combine two fields to make the description -description %toorfrom %name - -# save the status as a tag -comment status:%amzstatus - -# set the base account for all transactions -account1 assets:amazon -# leave amount1 blank so it can balance the other(s). -# I'm assuming amzamount excludes the fees, don't remember - -# set a generic account2 -account2 expenses:misc -amount2 %amzamount -# and maybe refine it further: -#include categorisation.rules - -# add a third posting for fees, but only if they are non-zero. -if %fees [1-9] - account3 expenses:fees - amount3 %fees - -$ hledger -f amazon-orders.csv print -2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed - assets:amazon - expenses:misc $20.00 - -2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed - assets:amazon - expenses:misc $25.00 - expenses:fees $1.00 - - -File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples - -10.19.4 Paypal --------------- - -Here's a real-world rules file for (customised) Paypal CSV, with some -Paypal-specific rules, and a second rules file included: - -"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" -"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" -"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" -"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" -"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" -"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" -"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" -"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" - -# paypal-custom.csv.rules - -# Tips: -# Export from Activity -> Statements -> Custom -> Activity download -# Suggested transaction type: "Balance affecting" -# Paypal's default fields in 2018 were: -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" -# This rules file assumes the following more detailed fields, configured in "Customize report fields": -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" - -fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note - -skip 1 - -date-format %-m/%-d/%Y - -# ignore some paypal events -if -In Progress -Temporary Hold -Update to - skip - -# add more fields to the description -description %description_ %itemtitle - -# save some other fields as tags -comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ - -# convert to short currency symbols -if %currency USD - currency $ -if %currency EUR - currency E -if %currency GBP - currency P - -# generate postings - -# the first posting will be the money leaving/entering my paypal account -# (negative means leaving my account, in all amount fields) -account1 assets:online:paypal -amount1 %netamount - -# the second posting will be money sent to/received from other party -# (account2 is set below) -amount2 -%grossamount - -# if there's a fee, add a third posting for the money taken by paypal. -if %feeamount [1-9] - account3 expenses:banking:paypal - amount3 -%feeamount - comment3 business: - -# choose an account for the second posting - -# override the default account names: -# if the amount is positive, it's income (a debit) -if %grossamount ^[^-] - account2 income:unknown -# if negative, it's an expense (a credit) -if %grossamount ^- - account2 expenses:unknown - -# apply common rules for setting account2 & other tweaks -include common.rules - -# apply some overrides specific to this csv - -# Transfers from/to bank. These are usually marked Pending, -# which can be disregarded in this case. -if -Bank Account -Bank Deposit to PP Account - description %type for %referencetxnid %itemtitle - account2 assets:bank:wf:pchecking - account1 assets:online:paypal - -# Currency conversions -if Currency Conversion - account2 equity:currency conversion - -# common.rules - -if -darcs -noble benefactor - account2 revenues:foss donations:darcshub - comment2 business: - -if -Calm Radio - account2 expenses:online:apps - -if -electronic frontier foundation -Patreon -wikimedia -Advent of Code - account2 expenses:dues - -if Google - account2 expenses:online:apps - description google | music - -$ hledger -f paypal-custom.csv print -2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed - assets:online:paypal $-6.99 = $-6.99 - expenses:online:apps $6.99 - -2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $6.99 = $0.00 - assets:bank:wf:pchecking $-6.99 - -2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed - assets:online:paypal $-7.00 = $-7.00 - expenses:dues $7.00 - -2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $7.00 = $0.00 - assets:bank:wf:pchecking $-7.00 - -2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed - assets:online:paypal $-2.00 = $-2.00 - expenses:dues $2.00 - expenses:banking:paypal ; business: - -2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $2.00 = $0.00 - assets:bank:wf:pchecking $-2.00 - -2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed - assets:online:paypal $9.41 = $9.41 - revenues:foss donations:darcshub $-10.00 ; business: - expenses:banking:paypal $0.59 ; business: - - -File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top - -11 Timeclock -************ - -The time logging format of timeclock.el, as read by hledger. - - hledger can read time logs in timeclock format. As with Ledger, -these are (a subset of) timeclock.el's format, containing clock-in and -clock-out entries as in the example below. The date is a simple date. -The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are -optional. The timezone, if present, must be four digits and is ignored -(currently the time is always interpreted as a local time). Lines -beginning with '#' or ';' or '*', and blank lines, are ignored. - -i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: -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 2 spaces ; optional comment, tags: - (some account) 0.33h - -2015-03-31 * 22:21-23:59 - (another:account) 1.64h - -2015-04-01 * 00:00-02:00 - (another:account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - -$ hledger -f sample.timeclock balance # current time balances -$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 -$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - * use emacs and the built-in timeclock.el, or the extended - timeclock-x.el and perhaps the extras in ledgerutils.el - - * at the command line, use these bash aliases: 'shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' - - * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. - These rely on a "timeclock" executable which I think is just the - ledger 2 executable renamed. - - -File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top - -12 Timedot -********** - -'timedot' format is hledger's human-friendly time logging format. -Compared to 'timeclock' format, it is more convenient for quick, -approximate, and retroactive time logging, and more human-readable (you -can see at a glance where time was spent). A quick example: - -2023-05-01 -hom:errands .... .... ; two hours; the space is ignored -fos:hledger:timedot .. ; half an hour -per:admin:finance ; no time spent yet - - hledger reads this as a transaction on this day with three -(unbalanced) postings, where each dot represents "0.25". No commodity -symbol is assumed, but we typically interpret it as hours. - -$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required -2023-05-01 * - (hom:errands) 2.00 ; two hours - (fos:hledger:timedot) 0.50 ; half an hour - (per:admin:finance) 0 - - A timedot file contains a series of transactions (usually one per -day). Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D), -optionally be followed on the same line by a transaction description, -and/or a transaction comment following a semicolon. - - After the date line are zero or more time postings, consisting of: - - * *An account name* - any hledger-style account name, optionally - indented. - - * *Two or more spaces* - required if there is an amount (as in - journal format). - - * *A timedot amount*, which can be - - * empty (representing zero) - - * a number, optionally followed by a unit 's', 'm', 'h', 'd', - 'w', 'mo', or 'y', representing a precise number of seconds, - minutes, hours, days weeks, months or years (hours is assumed - by default), which will be converted to hours according to 60s - = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. - - * one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can - be used for grouping/alignment. - - * one or more letters. These are like dots but they also - generate a tag 't:' (short for "type") with the letter as its - value, and a separate posting for each of the values. This - provides a second dimension of categorisation, viewable in - reports with '--pivot t'. - - * *An optional comment* following a semicolon (a hledger-style - posting comment). - - There is some flexibility to help with keeping time log data and -notes in the same file: - - * Blank lines and lines beginning with '#' or ';' are ignored. - - * After the first date line, lines which do not contain a double - space are parsed as postings with zero amount. (hledger's register - reports will show these if you add -E). - - * Before the first date line, lines beginning with '*' (eg org - headings) are ignored. And from the first date line onward, Emacs - org mode heading prefixes at the start of lines (one or more '*''s - followed by a space) will be ignored. This means the time log can - also be a org outline. - -* Menu: - -* Timedot examples:: - - -File: hledger.info, Node: Timedot examples, Up: Timedot - -12.1 Timedot examples -===================== - -Numbers: - -2016/2/3 -inc:client1 4 -fos:hledger 3h -biz:research 60m - - Dots: - -# 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 . - -$ 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 - - Letters: - -# Activity types: -# c cleanup/catchup/repair -# e enhancement -# s support -# l learning/research - -2023-11-01 -work:adm ccecces - -$ hledger -f a.timedot print -2023-11-01 - (work:adm) 1 ; t:c - (work:adm) 0.5 ; t:e - (work:adm) 0.25 ; t:s - -$ hledger -f a.timedot bal - 1.75 work:adm --------------------- - 1.75 - -$ hledger -f a.timedot bal --pivot t - 1.00 c - 0.50 e - 0.25 s --------------------- - 1.75 - - Org: - -* 2023 Work Diary -** Q1 -*** 2023-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 - - Using '.' as account name separator: - -2016/2/4 -fos.hledger.timedot 4h -fos.ledger .. - -$ hledger -f a.timedot --alias '/\./=:' bal -t - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger --------------------- - 4.50 - - -File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Amount formatting parseability, Prev: Timedot, Up: Top - -13 PART 3: REPORTING CONCEPTS -***************************** - - -File: hledger.info, Node: Amount formatting parseability, Next: Time periods, Prev: PART 3 REPORTING CONCEPTS, Up: Top - -14 Amount formatting, parseability -********************************** - -If you're wondering why your 'print' report sometimes shows trailing -decimal marks, with no decimal digits; it does this when showing amounts -that have digit group marks but no decimal digits, to disambiguate them -and allow them to be re-parsed reliably (see also Decimal marks, digit -group marks. Eg: - -commodity $1,000.00 - -2023-01-02 - (a) $1000 - -$ hledger print -2023-01-02 - (a) $1,000. - - If this is a problem (eg when exporting to Ledger), you can avoid it -by disabling digit group marks, eg with -c/-commodity (for each affected -commodity): - -$ hledger print -c '$1000.00' -2023-01-02 - (a) $1000 - - or by forcing print to always show decimal digits, with -round: - -$ hledger print -c '$1,000.00' --round=soft -2023-01-02 - (a) $1,000.00 - - More generally: hledger output falls into three rough categories, -which format amounts a little bit differently to suit different -consumers: - - *1. "hledger-readable output" - should be readable by hledger (and -by humans)* - - * This is produced by reports that show full journal entries: - 'print', 'import', 'close', 'rewrite' etc. - * It shows amounts with their original journal precisions, which may - not be consistent. - * It adds a trailing decimal mark when needed to avoid showing - ambiguous amounts. - * It can be parsed reliably (by hledger and ledger2beancount at - least, but perhaps not by Ledger..) - - *2. "human-readable output" - usually for humans* - - * This is produced by all other reports. - * It shows amounts with standard display precisions, which will be - consistent within each commodity. - * It shows ambiguous amounts unmodified. - * It can be parsed reliably in the context of a known report (when - you know decimals are consistently not being shown, you can assume - a single mark is a digit group mark). - - *3. "machine-readable output" - usually for other software* - - * This is produced by all reports when an output format like 'csv', - 'tsv', 'json', or 'sql' is selected. - * It shows amounts as 1 or 2 do, but without digit group marks. - * It can be parsed reliably (if needed, the decimal mark can be - changed with -c/-commodity-style). - - -File: hledger.info, Node: Time periods, Next: Depth, Prev: Amount formatting parseability, Up: Top - -15 Time periods -*************** - -* Menu: - -* Report start & end date:: -* Smart dates:: -* Report intervals:: -* Date adjustment:: -* Period expressions:: - - -File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods - -15.1 Report start & end date -============================ - -By default, most hledger reports will show the full span of time -represented by the journal. The report start date will be the earliest -transaction or posting date, and the report end date will be the latest -transaction, posting, or market price date. - - Often you will want to see a shorter time span, such as the current -month. You can specify a start and/or end date using '-b/--begin', -'-e/--end', '-p/--period' or a 'date:' query (described below). All of -these accept the smart date syntax (below). - - Some notes: - - * End dates are exclusive, as in Ledger, so you should write the date - _after_ the last day you want to see in the report. - * As noted in reporting options: among start/end dates specified with - _options_, the last (i.e. right-most) option takes precedence. - * The effective report start and end dates are the intersection of - the start/end dates from options and that from 'date:' queries. - That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January - 2019, the smallest common time span. - * In some cases a report interval will adjust start/end dates to fall - on interval boundaries (see below). - - Examples: - -'-b begin on St. Patrick's day 2016 -2016/3/17' -'-e 12/1' end at the start of december 1st of the current year - (11/30 will be the last date included) -'-b all transactions on or after the 1st of the current month -thismonth' -'-p all transactions in the current month -thismonth' -'date:2016/3/17..'the above written as queries instead ('..' can also be - replaced with '-') -'date:..12/1' -'date:thismonth..' -'date:thismonth' - - -File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods - -15.2 Smart dates -================ - -hledger's user interfaces accept a "smart date" syntax for added -convenience. Smart dates optionally can be relative to today's date, be -written with english words, and have less-significant parts omitted -(missing parts are inferred as 1). Some examples: - -'2004/10/1', exact date, several separators allowed. Year -'2004-01-01', is 4+ digits, month is 1-12, day is 1-31 -'2004.9.1' -'2004' start of year -'2004/10' start of month -'10/1' month and day in current year -'21' day in current month -'october, oct' start of month in current year -'yesterday, today, -1, 0, 1 days from today -tomorrow' -'last/this/next -1, 0, 1 periods from the current period -day/week/month/quarter/year' -'in n n periods from the current period -days/weeks/months/quarters/years' -'n n periods from the current period -days/weeks/months/quarters/years -ahead' -'n -n periods from the current period -days/weeks/months/quarters/years -ago' -'20181201' 8 digit YYYYMMDD with valid year month and - day -'201812' 6 digit YYYYMM with valid year and month - - Some counterexamples - malformed digit sequences might give -surprising results: - -'201813' 6 digits with an invalid month is parsed as start of - 6-digit year -'20181301' 8 digits with an invalid month is parsed as start of - 8-digit year -'20181232' 8 digits with an invalid day gives an error -'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error - - "Today's date" can be overridden with the '--today' option, in case -it's needed for testing or for recreating old reports. (Except for -periodic transaction rules, which are not affected by '--today'.) - - -File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods - -15.3 Report intervals -===================== - -A report interval can be specified so that reports like register, -balance or activity become multi-period, showing each subperiod as a -separate row or column. - - The following standard intervals can be enabled with command-line -flags: - - * '-D/--daily' - * '-W/--weekly' - * '-M/--monthly' - * '-Q/--quarterly' - * '-Y/--yearly' - - More complex intervals can be specified using '-p/--period', -described below. - - -File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods - -15.4 Date adjustment -==================== - -When there is a report interval (other than daily), report start/end -dates which have been inferred, eg from the journal, are automatically -adjusted to natural period boundaries. This is convenient for producing -simple periodic reports. More precisely: - - * an inferred start date will be adjusted earlier if needed to fall - on a natural period boundary - - * an inferred end date will be adjusted later if needed to make the - last period the same length as the others. - - By contrast, start/end dates which have been specified explicitly, -with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger -1.29). This makes it possible to specify non-standard report periods, -but it also means that if you are specifying a start date, you should -pick one that's on a period boundary if you want to see simple report -period headings. - - -File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods - -15.5 Period expressions -======================= - -The '-p/--period' option specifies a period expression, which is a -compact way of expressing a start date, end date, and/or report -interval. - - Here's a period expression with a start and end date (specifying the -first quarter of 2009): - -'-p "from 2009/1/1 to 2009/4/1"' - - Several keywords like "from" and "to" are supported for readability; -these are optional. "to" can also be written as ".." or "-". The -spaces are also optional, as long as you don't run two dates together. -So the following are equivalent to the above: - -'-p "2009/1/1 2009/4/1"' -'-p2009/1/1to2009/4/1' -'-p2009/1/1..2009/4/1' - - Dates are smart dates, so if the current year is 2009, these are also -equivalent to the above: - -'-p "1/1 4/1"' -'-p "jan-apr"' -'-p "this year to 4/1"' - - If you specify only one date, the missing start or end date will be -the earliest or latest transaction date in the journal: - -'-p "from 2009/1/1"' everything after january 1, 2009 -'-p "since 2009/1"' the same, since is a synonym -'-p "from 2009"' the same -'-p "to 2009"' everything before january 1, 2009 - - You can also specify a period by writing a single partial or full -date: - -'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” -'-p "2009/1"' the month of january 2009; equivalent to “2009/1/1 to - 2009/2/1” -'-p the first day of 2009; equivalent to “2009/1/1 to -"2009/1/1"' 2009/1/2” - - or by using the "Q" quarter-year syntax (case insensitive): - -'-p "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to - 2009/4/1” -'-p "q4"' fourth quarter of the current year - -* Menu: - -* Period expressions with a report interval:: -* More complex report intervals:: -* Multiple weekday intervals:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -15.5.1 Period expressions with a report interval ------------------------------------------------- - -A period expression can also begin with a report interval, separated -from the start/end dates (if any) by a space or the word 'in': - -'-p "weekly from 2009/1/1 to 2009/4/1"' -'-p "monthly in 2008"' -'-p "quarterly"' - - -File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions - -15.5.2 More complex report intervals ------------------------------------- - -Some more complex intervals can be specified within period expressions, -such as: - - * 'biweekly' (every two weeks) - * 'fortnightly' - * 'bimonthly' (every two months) - * 'every day|week|month|quarter|year' - * 'every N days|weeks|months|quarters|years' - - Weekly on a custom day: - - * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted - after the number) - * 'every WEEKDAYNAME' (full or three-letter english weekday name, - case insensitive) - - Monthly on a custom day: - - * 'every Nth day [of month]' - * 'every Nth WEEKDAYNAME [of month]' - - Yearly on a custom day: - - * 'every MM/DD [of year]' (month number and day of month number) - * 'every MONTHNAME DDth [of year]' (full or three-letter english - month name, case insensitive, and day of month number) - * 'every DDth MONTHNAME [of year]' (equivalent to the above) - - Examples: - -'-p "bimonthly from -2008"' -'-p "every 2 weeks"' -'-p "every 5 months from -2009/03"' -'-p "every 2nd day of periods will go from Tue to Tue -week"' -'-p "every Tue"' same -'-p "every 15th day"' period boundaries will be on 15th of each - month -'-p "every 2nd Monday"' period boundaries will be on second Monday - of each month -'-p "every 11/05"' yearly periods with boundaries on 5th of - November -'-p "every 5th November"' same -'-p "every Nov 5th"' same - - Show historical balances at end of the 15th day of each month (N is -an end date, exclusive as always): - -$ hledger balance -H -p "every 16th day" - - Group postings from the start of wednesday to end of the following -tuesday (N is both (inclusive) start date and (exclusive) end date): - -$ hledger register checking -p "every 3rd day of week" - - -File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions - -15.5.3 Multiple weekday intervals ---------------------------------- - -This special form is also supported: - - * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english - weekday names, case insensitive) - - Also, 'weekday' and 'weekendday' are shorthand for -'mon,tue,wed,thu,fri' and 'sat,sun'. - - This is mainly intended for use with '--forecast', to generate -periodic transactions on arbitrary days of the week. It may be less -useful with '-p', since it divides each week into subperiods of unequal -length, which is unusual. (Related: #1632) - - Examples: - -'-p "every dates will be Mon, Wed, Fri; periods will be -mon,wed,fri"' Mon-Tue, Wed-Thu, Fri-Sun -'-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will -weekday"' be Mon, Tue, Wed, Thu, Fri-Sun -'-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri -weekendday"' - - -File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top - -16 Depth -******** - -With the '--depth NUM' option (short form: '-NUM'), reports will show -accounts only to the specified depth, hiding deeper subaccounts. Use -this when you want a summary with less detail. This flag has the same -effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are -equivalent. - - -File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top - -17 Queries -********** - -One of hledger's strengths is being able to quickly report on a precise -subset of your data. Most hledger commands accept optional query -arguments to restrict their scope. The syntax is as follows: - - * Zero or more space-separated query terms. These are most often - account name substrings: - - 'utilities food:groceries' - - * Terms with spaces or other special characters should be enclosed in - quotes: - - '"personal care"' - - * Regular expressions are also supported: - - '"^expenses\b"' - '"accounts (payable|receivable)"' - - * Add a query type prefix to match other parts of the data: - - 'date:202312-' - 'status:' - 'desc:amazon' - 'cur:USD' - '"amt:>0"' - - * Add a 'not:' prefix to negate: - - 'not:cur:USD' - - * Multiple unlike terms are AND-ed, multiple like terms are OR-ed - - 'date:2022 desc:amazon desc:amzn' - (all transactions with "amazon" or "amzn" in description during - 2022) - -* Menu: - -* Query types:: -* Combining query terms:: -* Queries and command options:: -* Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value:: - - -File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries - -17.1 Query types -================ - -Here are the types of query term available. Remember these can also be -prefixed with *'not:'* to convert them into a negative match. - - *'acct:REGEX', 'REGEX'* -Match account names containing this (case insensitive) regular -expression. This is the default query type when there is no prefix, and -regular expression syntax is typically not needed, so usually we just -write an account name substring, like 'expenses' or 'food'. - - *'amt:N, amt:N, amt:>=N'* -Match postings with a single-commodity amount equal to, less than, or -greater than N. (Postings with multi-commodity amounts are not tested -and will always match.) The comparison has two modes: if N is preceded -by a + or - sign (or is 0), the two signed numbers are compared. -Otherwise, the absolute magnitudes are compared, ignoring sign. - - *'code:REGEX'* -Match by transaction code (eg check number). - - *'cur:REGEX'* -Match postings or transactions including any amounts whose -currency/commodity symbol is fully matched by REGEX. (For a partial -match, use '.*REGEX.*'). Note, to match special characters which are -regex-significant, you need to escape them with '\'. And for characters -which are significant to your shell you may need one more level of -escaping. So eg to match the dollar sign: -'hledger print cur:\\$'. - - *'desc:REGEX'* -Match transaction descriptions. - - *'date:PERIODEXPR'* -Match dates (or with the '--date2' flag, secondary dates) within the -specified period. PERIODEXPR is a period expression with no report -interval. Examples: -'date:2016', 'date:thismonth', 'date:2/1-2/15', -'date:2021-07-27..nextquarter'. - - *'date2:PERIODEXPR'* -Match secondary dates within the specified period (independent of the -'--date2' flag). - - *'depth:N'* -Match (or display, depending on command) accounts at or above this -depth. - - *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg) -Match with a boolean combination of queries (which must be enclosed in -quotes). See Combining query terms below. - - *'note:REGEX'* -Match transaction notes (the part of the description right of '|', or -the whole description if there's no '|'). - - *'payee:REGEX'* -Match transaction payee/payer names (the part of the description left of -'|', or the whole description if there's no '|'). - - *'real:, real:0'* -Match real or virtual postings respectively. - - *'status:, status:!, status:*'* -Match unmarked, pending, or cleared transactions respectively. - - *'type:TYPECODES'* -Match by account type (see Declaring accounts > Account types). -'TYPECODES' is one or more of the single-letter account type codes -'ALERXCV', case insensitive. Note 'type:A' and 'type:E' will also match -their respective subtypes 'C' (Cash) and 'V' (Conversion). Certain -kinds of account alias can disrupt account types, see Rewriting accounts -> Aliases and account types. - - *'tag:REGEX[=REGEX]'* -Match by tag name, and optionally also by tag value. (To match only by -value, use 'tag:.=REGEX'.) - - When querying by tag, note that: - - * Accounts also inherit the tags of their parent accounts - * Postings also inherit the tags of their account and their - transaction - * Transactions also acquire the tags of their postings. - - (*'inacct:ACCTNAME'* -A special query term used automatically in hledger-web only: tells -hledger-web to show the transaction register for an account.) - - -File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries - -17.2 Combining query terms -========================== - -When given multiple space-separated query terms, most commands select -things which match: - - * any of the description terms AND - * any of the account terms AND - * any of the status terms AND - * all the other terms. - - The print command is a little different, showing transactions which: - - * match any of the description terms AND - * have any postings matching any of the positive account terms AND - * have no postings matching any of the negative account terms AND - * match all the other terms. - - We also support more complex boolean queries with the 'expr:' prefix. -This allows one to combine queries using one of three operators: AND, -OR, and NOT, where NOT is different syntax for 'not:'. - - Examples of such queries are: - - * Match transactions with 'cool' in the description AND with the 'A' - tag - - 'expr:"desc:cool AND tag:A"' - - * Match transactions NOT to the 'expenses:food' account OR with the - 'A' tag - - 'expr:"NOT expenses:food OR tag:A"' - - * Match transactions NOT involving the 'expenses:food' account OR - with the 'A' tag AND involving the 'expenses:drink' account. (the - AND is implicitly added by space-separation, following the rules - above) - - 'expr:"expenses:food OR (tag:A expenses:drink)"' - - -File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries - -17.3 Queries and command options -================================ - -Some queries can also be expressed as command-line options: 'depth:2' is -equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. -When you mix command options and query arguments, generally the -resulting query is their intersection. - - -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries - -17.4 Queries and valuation -========================== - -When amounts are converted to other commodities in cost or value -reports, 'cur:' and 'amt:' match the old commodity symbol and the old -amount quantity, not the new ones (except in hledger 1.22.0 where it's -reversed, see #1625). - - -File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries - -17.5 Querying with account aliases -================================== - -When account names are rewritten with '--alias' or 'alias', note that -'acct:' will match either the old or the new account name. - - -File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries - -17.6 Querying with cost or value -================================ - -When amounts are converted to other commodities in cost or value -reports, note that 'cur:' matches the new commodity symbol, and not the -old one, and 'amt:' matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, see -the discussion at #1625. - - -File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top - -18 Pivoting -*********** - -Normally, hledger groups and sums amounts within each account. The -'--pivot FIELD' option substitutes some other transaction field for -account names, causing amounts to be grouped and summed by that field's -value instead. FIELD can be any of the transaction fields 'acct', -'status', 'code', 'desc', 'payee', 'note', or a tag name. When pivoting -on a tag and a posting has multiple values of that tag, only the first -value is displayed. Values containing 'colon:separated:parts' will be -displayed hierarchically, like account names. Multiple, colon-delimited -fields can be pivoted simultaneously, generating a hierarchical account -name. - - Some examples: - -2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe, kind: Lifetime - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues --------------------- - 0 - - Pivoted balance report, using member: tag values instead: - -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 - - One way to show only amounts with a member: value (using a query): - -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account -name"): - -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR - - Hierarchical reports can be generated with multiple pivots: - -$ hledger balance Income:Dues --pivot kind:member - -2 EUR Lifetime:John Doe --------------------- - -2 EUR - - -File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top - -19 Generating data -****************** - -hledger has several features for generating data, such as: - - * Periodic transaction rules can generate single or repeating - transactions following a template. These are usually dated in the - future, eg to help with forecasting. They are activated by the - '--forecast' option. - - * The balance command's '--budget' option uses these same periodic - rules to generate goals for the budget report. - - * Auto posting rules can generate extra postings on certain matched - transactions. They are always applied to forecast transactions; - with the '--auto' flag they are applied to transactions recorded in - the journal as well. - - * The '--infer-equity' flag infers missing conversion equity postings - from @/@@ costs. And the inverse '--infer-costs' flag infers - missing @/@@ costs from conversion equity postings. - - Generated data of this kind is temporary, existing only at report -time. But you can see it in the output of 'hledger print', and you can -save that to your journal, in effect converting it from temporary -generated data to permanent recorded data. This could be useful as a -data entry aid. - - If you are wondering what data is being generated and why, add the -'--verbose-tags' flag. In 'hledger print' output you will see extra -tags like 'generated-transaction', 'generated-posting', and 'modified' -on generated/modified data. Also, even without '--verbose-tags', -generated data always has equivalen hidden tags (with an underscore -prefix), so eg you could match generated transactions with -'tag:_generated-transaction'. - - -File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top - -20 Forecasting -************** - -Forecasting, or speculative future reporting, can be useful for -estimating future balances, or for exploring different future scenarios. - - The simplest and most flexible way to do it with hledger is to -manually record a bunch of future-dated transactions. You could keep -these in a separate 'future.journal' and include that with '-f' only -when you want to see them. - -* Menu: - -* --forecast:: -* Inspecting forecast transactions:: -* Forecast reports:: -* Forecast tags:: -* Forecast period in detail:: -* Forecast troubleshooting:: - - -File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting - -20.1 -forecast -============== - -There is another way: with the '--forecast' option, hledger can generate -temporary "forecast transactions" for reporting purposes, according to -periodic transaction rules defined in the journal. Each rule can -generate multiple recurring transactions, so by changing one rule you -can change many forecasted transactions. (These same rules can also -generate budget goals, described in Budgeting.) - - Forecast transactions usually start after ordinary transactions end. -By default, they begin after your latest-dated ordinary transaction, or -today, whichever is later, and they end six months from today. (The -exact rules are a little more complicated, and are given below.) - - This is the "forecast period", which need not be the same as the -report period. You can override it - eg to forecast farther into the -future, or to force forecast transactions to overlap your ordinary -transactions - by giving the -forecast option a period expression -argument, like '--forecast=..2099' or '--forecast=2023-02-15..'. Note -that the '=' is required. - - -File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting - -20.2 Inspecting forecast transactions -===================================== - -'print' is the best command for inspecting and troubleshooting forecast -transactions. Eg: - -~ monthly from 2022-12-20 rent - assets:bank:checking - expenses:rent $1000 - -$ hledger print --forecast --today=2023/4/21 -2023-05-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-06-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-07-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-08-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-09-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - Here there are no ordinary transactions, so the forecasted -transactions begin on the first occurence after today's date. (You -won't normally use '--today'; it's just to make these examples -reproducible.) - - -File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting - -20.3 Forecast reports -===================== - -Forecast transactions affect all reports, as you would expect. Eg: - -$ hledger areg rent --forecast --today=2023/4/21 -Transactions in expenses:rent and subaccounts: -2023-05-20 rent as:ba:checking $1000 $1000 -2023-06-20 rent as:ba:checking $1000 $2000 -2023-07-20 rent as:ba:checking $1000 $3000 -2023-08-20 rent as:ba:checking $1000 $4000 -2023-09-20 rent as:ba:checking $1000 $5000 - -$ hledger bal -M expenses --forecast --today=2023/4/21 -Balance changes in 2023-05-01..2023-09-30: - - || May Jun Jul Aug Sep -===============++=================================== - expenses:rent || $1000 $1000 $1000 $1000 $1000 ----------------++----------------------------------- - || $1000 $1000 $1000 $1000 $1000 - - -File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting - -20.4 Forecast tags -================== - -Forecast transactions generated by -forecast have a hidden tag, -'_generated-transaction'. So if you ever need to match forecast -transactions, you could use 'tag:_generated-transaction' (or just -'tag:generated') in a query. - - For troubleshooting, you can add the '--verbose-tags' flag. Then, -visible 'generated-transaction' tags will be added also, so you can view -them with the 'print' command. Their value indicates which periodic -rule was responsible. - - -File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting - -20.5 Forecast period, in detail -=============================== - -Forecast start/end dates are chosen so as to do something useful by -default in almost all situations, while also being flexible. Here are -(with luck) the exact rules, to help with troubleshooting: - - The forecast period starts on: - - * the later of - * the start date in the periodic transaction rule - * the start date in '--forecast''s argument - - * otherwise (if those are not available): the later of - * the report start date specified with '-b'/'-p'/'date:' - * the day after the latest ordinary transaction in the journal - - * otherwise (if none of these are available): today. - - The forecast period ends on: - - * the earlier of - * the end date in the periodic transaction rule - * the end date in '--forecast''s argument - - * otherwise: the report end date specified with '-e'/'-p'/'date:' - * otherwise: 180 days (~6 months) from today. - - -File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting - -20.6 Forecast troubleshooting -============================= - -When -forecast is not doing what you expect, one of these tips should -help: - - * Remember to use the '--forecast' option. - * Remember to have at least one periodic transaction rule in your - journal. - * Test with 'print --forecast'. - * Check for typos or too-restrictive start/end dates in your periodic - transaction rule. - * Leave at least 2 spaces between the rule's period expression and - description fields. - * Check for future-dated ordinary transactions suppressing forecasted - transactions. - * Try setting explicit report start and/or end dates with '-b', '-e', - '-p' or 'date:' - * Try adding the '-E' flag to encourage display of empty periods/zero - transactions. - * Try setting explicit forecast start and/or end dates with - '--forecast=START..END' - * Consult Forecast period, in detail, above. - * Check inside the engine: add '--debug=2' (eg). - - -File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top - -21 Budgeting -************ - -With the balance command's '--budget' report, each periodic transaction -rule generates recurring budget goals in specified accounts, and goals -and actual performance can be compared. See the balance command's doc -below. - - You can generate budget goals and forecast transactions at the same -time, from the same or different periodic transaction rules: 'hledger -bal -M --budget --forecast ...' - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Budgeting, Up: Top - -22 Cost reporting -***************** - -In some transactions - for example a currency conversion, or a purchase -or sale of stock - one commodity is exchanged for another. In these -transactions there is a conversion rate, also called the cost (when -buying) or selling price (when selling). In hledger docs we just say -"cost", for convenience; feel free to mentally translate to "conversion -rate" or "selling price" if helpful. - -* Menu: - -* Recording costs:: -* Reporting at cost:: -* Equity conversion postings:: -* Inferring equity conversion postings:: -* Combining costs and equity conversion postings:: -* Requirements for detecting equity conversion postings:: -* Infer cost and equity by default ?:: - - -File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting - -22.1 Recording costs -==================== - -We'll explore several ways of recording transactions involving costs. -These are also summarised at hledger Cookbook > Cost notation. - - Costs can be recorded explicitly in the journal, using the '@ -UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs: - - *Variant 1* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 ; $1.35 per euro (unit cost) - - *Variant 2* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 @@ $135 ; $135 total cost - - Typically, writing the unit cost (variant 1) is preferable; it can be -more effort, requiring more attention to decimal digits; but it reveals -the per-unit cost basis, and makes stock sales easier. - - Costs can also be left implicit, and hledger will infer the cost that -is consistent with a balanced transaction: - - *Variant 3* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 - - Here, hledger will attach a '@@ €100' cost to the first amount (you -can see it with 'hledger print -x'). This form looks convenient, but -there are downsides: - - * It sacrifices some error checking. For example, if you - accidentally wrote €10 instead of €100, hledger would not be able - to detect the mistake. - - * It is sensitive to the order of postings - if they were reversed, a - different entry would be inferred and reports would be different. - - * The per-unit cost basis is not easy to read. - - So generally this kind of entry is not recommended. You can make -sure you have none of these by using '-s' (strict mode), or by running -'hledger check balanced'. - - -File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting - -22.2 Reporting at cost -====================== - -Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's --B/-basis/-cost flag), any amounts which have been annotated with costs -will be converted to their cost's commodity (in the report output). Ie -they will be displayed "at cost" or "at sale price". - - Some things to note: - - * Costs are attached to specific posting amounts in specific - transactions, and once recorded they do not change. This contrasts - with market prices, which are ambient and fluctuating. - - * Conversion to cost is performed before conversion to market value - (described below). - - -File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting - -22.3 Equity conversion postings -=============================== - -There is a problem with the entries above - they are not conventional -Double Entry Bookkeeping (DEB) notation, and because of the "magical" -transformation of one commodity into another, they cause an imbalance in -the Accounting Equation. This shows up as a non-zero grand total in -balance reports like 'hledger bse'. - - For most hledger users, this doesn't matter in practice and can -safely be ignored ! But if you'd like to learn more, keep reading. - - Conventional DEB uses an extra pair of equity postings to balance the -transaction. Of course you can do this in hledger as well: - - *Variant 4* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 - equity:conversion $135 - equity:conversion €-100 - - Now the transaction is perfectly balanced according to standard DEB, -and 'hledger bse''s total will not be disrupted. - - And, hledger can still infer the cost for cost reporting, but it's -not done by default - you must add the '--infer-costs' flag like so: - -$ hledger print --infer-costs -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 @@ €100 - assets:euros €100 - equity:conversion $135 - equity:conversion €-100 - -$ hledger bal --infer-costs -B - €-100 assets:dollars - €100 assets:euros --------------------- - 0 - - Here are some downsides of this kind of entry: - - * The per-unit cost basis is not easy to read. - - * Instead of '-B' you must remember to type '-B --infer-costs'. - - * '--infer-costs' works only where hledger can identify the two - equity:conversion postings and match them up with the two - non-equity postings. So writing the journal entry in a particular - format becomes more important. More on this below. - - -File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting - -22.4 Inferring equity conversion postings -========================================= - -Can we go in the other direction ? Yes, if you have transactions -written with the @/@@ cost notation, hledger can infer the missing -equity postings, if you add the '--infer-equity' flag. Eg: - -2022-01-01 - assets:dollars -$135 - assets:euros €100 @ $1.35 - -$ hledger print --infer-equity -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 - equity:conversion:$-€:€ €-100 - equity:conversion:$-€:$ $135.00 - - The equity account names will be "equity:conversion:A-B:A" and -"equity:conversion:A-B:B" where A is the alphabetically first commodity -symbol. You can customise the "equity:conversion" part by declaring an -account with the 'V'/'Conversion' account type. - - -File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting - -22.5 Combining costs and equity conversion postings -=================================================== - -Finally, you can use both the @/@@ cost notation and equity postings at -the same time. This in theory gives the best of all worlds - preserving -the accounting equation, revealing the per-unit cost basis, and -providing more flexibility in how you write the entry: - - *Variant 5* - -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 @ $1.35 - - All the other variants above can (usually) be rewritten to this final -form with: - -$ hledger print -x --infer-costs --infer-equity - - Downsides: - - * This was added in hledger-1.29 and is still somewhat experimental. - - * The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it - will give a transaction balancing error. - - * The add command does not yet accept this kind of entry (#2056). - - * This is the most verbose form. - - -File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting - -22.6 Requirements for detecting equity conversion postings -========================================================== - -'--infer-costs' has certain requirements (unlike '--infer-equity', which -always works). It will infer costs only in transactions with: - - * Two non-equity postings, in different commodities. Their order is - significant: the cost will be added to the first of them. - - * Two postings to equity conversion accounts, next to one another, - which balance the two non-equity postings. This balancing is - checked to the same precision (number of decimal places) used in - the conversion posting's amount. Equity conversion accounts are: - - * any accounts declared with account type 'V'/'Conversion', or - their subaccounts - * otherwise, accounts named 'equity:conversion', 'equity:trade', - or 'equity:trading', or their subaccounts. - - And multiple such four-posting groups can coexist within a single -transaction. When '--infer-costs' fails, it does not infer a cost in -that transaction, and does not raise an error (ie, it infers costs where -it can). - - Reading variant 5 journal entries, combining cost notation and equity -postings, has all the same requirements. When reading such an entry -fails, hledger raises an "unbalanced transaction" error. - - -File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting - -22.7 Infer cost and equity by default ? -======================================= - -Should '--infer-costs' and '--infer-equity' be enabled by default ? Try -using them always, eg with a shell alias: - -alias h="hledger --infer-equity --infer-costs" - - and let us know what problems you find. - - -File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top - -23 Value reporting -****************** - -Instead of reporting amounts in their original commodity, hledger can -convert them to cost/sale amount (using the conversion rate recorded in -the transaction), and/or to market value (using some market price on a -certain date). This is controlled by the '--value=TYPE[,COMMODITY]' -option, which will be described below. We also provide the simpler '-V' -and '-X COMMODITY' options, and often one of these is all you need: - -* Menu: - -* -V Value:: -* -X Value in specified commodity:: -* Valuation date:: -* Finding market price:: -* --infer-market-prices market prices from transactions:: -* Valuation commodity:: -* Simple valuation examples:: -* --value Flexible valuation:: -* More valuation examples:: -* Interaction of valuation and queries:: -* Effect of valuation on reports:: - - -File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Value reporting - -23.1 -V: Value -============== - -The '-V/--market' flag converts amounts to market value in their default -_valuation commodity_, using the market prices in effect on the -_valuation date(s)_, if any. More on these in a minute. - - -File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Value reporting - -23.2 -X: Value in specified commodity -===================================== - -The '-X/--exchange=COMM' option is like '-V', except you tell it which -currency you want to convert to, and it tries to convert everything to -that. - - -File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Value reporting - -23.3 Valuation date -=================== - -Market prices can change from day to day. hledger will use the prices -on a particular valuation date (or on more than one date). By default -hledger uses "end" dates for valuation. More specifically: - - * For single period reports (including normal print and register - reports): - * If an explicit report end date is specified, that is used - * Otherwise the latest transaction date or P directive date is - used (even if it's in the future) - - * For multiperiod reports, each period is valued on its last day. - - This can be customised with the -value option described below, which -can select either "then", "end", "now", or "custom" dates. (Note, this -has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key -always resets it to "end".) - - -File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting - -23.4 Finding market price -========================= - -To convert a commodity A to its market value in another commodity B, -hledger looks for a suitable market price (exchange rate) as follows, in -this order of preference: - - 1. A _declared market price_ or _inferred market price_: A's latest - market price in B on or before the valuation date as declared by a - P directive, or (with the '--infer-market-prices' flag) inferred - from costs. - - 2. A _reverse market price_: the inverse of a declared or inferred - market price from B to A. - - 3. A _forward chain of market prices_: a synthetic price formed by - combining the shortest chain of "forward" (only 1 above) market - prices, leading from A to B. - - 4. _Any chain of market prices_: a chain of any market prices, - including both forward and reverse prices (1 and 2 above), leading - from A to B. - - There is a limit to the length of these price chains; if hledger -reaches that length without finding a complete chain or exhausting all -possibilities, it will give up (with a "gave up" message visible in -'--debug=2' output). That limit is currently 1000. - - Amounts for which no suitable market price can be found, are not -converted. - - -File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting - -23.5 -infer-market-prices: market prices from transactions -========================================================== - -Normally, market value in hledger is fully controlled by, and requires, -P directives in your journal. Since adding and updating those can be a -chore, and since transactions usually take place at close to market -value, why not use the recorded costs as additional market prices (as -Ledger does) ? Adding the '--infer-market-prices' flag to '-V', '-X' or -'--value' enables this. - - So for example, 'hledger bs -V --infer-market-prices' will get market -prices both from P directives and from transactions. If both occur on -the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in -confusing/undesired ways by your journal entries. If this happens to -you, read all of this Value reporting section carefully, and try adding -'--debug' or '--debug=2' to troubleshoot. - - '--infer-market-prices' can infer market prices from: - - * multicommodity transactions with explicit prices ('@'/'@@') - - * multicommodity transactions with implicit prices (no '@', two - commodities, unbalanced). (With these, the order of postings - matters. 'hledger print -x' can be useful for troubleshooting.) - - * multicommodity transactions with equity postings, if cost is - inferred with '--infer-costs'. - - There is a limitation (bug) currently: when a valuation commodity is -not specified, prices inferred with '--infer-market-prices' do not help -select a default valuation commodity, as 'P' prices would. So -conversion might not happen because no valuation commodity was detected -('--debug=2' will show this). To be safe, specify the valuation -commmodity, eg: - - * '-X EUR --infer-market-prices', not '-V --infer-market-prices' - * '--value=then,EUR --infer-market-prices', not '--value=then - --infer-market-prices' - - Signed costs and market prices can be confusing. For reference, here -is the current behaviour, since hledger 1.25. (If you think it should -work differently, see #1870.) - -2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - -2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - -2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - -2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - -2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - -2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each -day, the two transactions are considered equivalent). Here are the -market prices inferred for B: - -$ hledger -f- --infer-market-prices prices -P 2022-01-01 B A 1 -P 2022-01-01 B A 1.0 -P 2022-01-02 B A -1 -P 2022-01-02 B A -1.0 -P 2022-01-03 B A -1 -P 2022-01-03 B A -1.0 - - -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Value reporting - -23.6 Valuation commodity -======================== - -*When you specify a valuation commodity ('-X COMM' or '--value -TYPE,COMM'):* -hledger will convert all amounts to COMM, wherever it can find a -suitable market price (including by reversing or chaining prices). - - *When you leave the valuation commodity unspecified ('-V' or '--value -TYPE'):* -For each commodity A, hledger picks a default valuation commodity as -follows, in this order of preference: - - 1. The price commodity from the latest P-declared market price for A - on or before valuation date. - - 2. The price commodity from the latest P-declared market price for A - on any date. (Allows conversion to proceed when there are inferred - prices before the valuation date.) - - 3. If there are no P directives at all (any commodity or date) and the - '--infer-market-prices' flag is used: the price commodity from the - latest transaction-inferred price for A on or before valuation - date. - - This means: - - * If you have P directives, they determine which commodities '-V' - will convert, and to what. - - * If you have no P directives, and use the '--infer-market-prices' - flag, costs determine it. - - Amounts for which no valuation commodity can be found are not -converted. - - -File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Value reporting - -23.7 Simple valuation examples -============================== - -Here are some quick examples of '-V': - -; one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -; purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -; the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 - - How many euros do I have ? - -$ hledger -f t.j bal -N euros - €100 assets:euros - - What are they worth at end of nov 3 ? - -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date -specified, defaults to today) - -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - -File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Value reporting - -23.8 -value: Flexible valuation -=============================== - -'-V' and '-X' are special cases of the more general '--value' option: - - --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. - COMM is an optional commodity symbol. - Shows amounts converted to: - - default valuation commodity (or COMM) using market prices at posting dates - - default valuation commodity (or COMM) using market prices at period end(s) - - default valuation commodity (or COMM) using current market prices - - default valuation commodity (or COMM) using market prices at some date - - The TYPE part selects cost or value and valuation date: - -'--value=then' - - Convert amounts to their value in the default valuation commodity, - using market prices on each posting's date. -'--value=end' - - Convert amounts to their value in the default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal's end date); or in multiperiod reports, - market prices on the last day of each subperiod. -'--value=now' - - Convert amounts to their value in the default valuation commodity - using current market prices (as of when report is generated). -'--value=YYYY-MM-DD' - - Convert amounts to their value in the default valuation commodity - using market prices on this date. - - To select a different valuation commodity, add the optional ',COMM' -part: a comma, then the target commodity's symbol. Eg: -*'--value=now,EUR'*. hledger will do its best to convert amounts to -this commodity, deducing market prices as described above. - - -File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting - -23.9 More valuation examples -============================ - -Here are some examples showing the effect of '--value', as seen with -'print': - -P 2000-01-01 A 1 B -P 2000-02-01 A 2 B -P 2000-03-01 A 3 B -P 2000-04-01 A 4 B - -2000-01-01 - (a) 1 A @ 5 B - -2000-02-01 - (a) 1 A @ 6 B - -2000-03-01 - (a) 1 A @ 7 B - - Show the cost of each posting: - -$ hledger -f- print --cost -2000-01-01 - (a) 5 B - -2000-02-01 - (a) 6 B - -2000-03-01 - (a) 7 B - - Show the value as of the last day of the report period (2000-02-29): - -$ hledger -f- print --value=end date:2000/01-2000/03 -2000-01-01 - (a) 2 B - -2000-02-01 - (a) 2 B - - With no report period specified, that shows the value as of the last -day of the journal (2000-03-01): - -$ hledger -f- print --value=end -2000-01-01 - (a) 3 B - -2000-02-01 - (a) 3 B - -2000-03-01 - (a) 3 B - - Show the current value (the 2000-04-01 price is still in effect -today): - -$ hledger -f- print --value=now -2000-01-01 - (a) 4 B - -2000-02-01 - (a) 4 B - -2000-03-01 - (a) 4 B - - Show the value on 2000/01/15: - -$ hledger -f- print --value=2000-01-15 -2000-01-01 - (a) 1 B - -2000-02-01 - (a) 1 B - -2000-03-01 - (a) 1 B - - -File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Value reporting - -23.10 Interaction of valuation and queries -========================================== - -When matching postings based on queries in the presence of valuation, -the following happens. - - 1. The query is separated into two parts: - 1. the currency ('cur:') or amount ('amt:'). - 2. all other parts. - - 2. The postings are matched to the currency and amount queries based - on pre-valued amounts. - 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on - post-valued amounts. - - See: 1625 - - -File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting - -23.11 Effect of valuation on reports -==================================== - -Here is a reference for how valuation is supposed to affect each part of -hledger's reports (and a glossary). (It's wide, you'll have to scroll -sideways.) It may be useful when troubleshooting. If you find -problems, please report them, ideally with a reproducible example. -Related: #329, #1083. - -Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', -type '--cost' '--value=now' ------------------------------------------------------------------------------- -*print* -posting cost value at value at posting value at value -amounts report end date report or at - or today journal DATE/today - end -balance unchanged unchanged unchanged unchanged unchanged -assertions/assignments -*register* -starting cost value at valued at day value at value -balance report or each historical report or at -(-H) journal posting was made journal DATE/today - end end -starting cost value at valued at day value at value -balance day before each historical day before at -(-H) report or posting was made report or DATE/today -with journal journal -report start start -interval -posting cost value at value at posting value at value -amounts report or date report or at - journal journal DATE/today - end end -summary summarised value at sum of postings value at value -posting cost period in interval, period at -amounts ends valued at ends DATE/today -with interval start -report -interval -running sum/average sum/average sum/average of sum/average sum/average -total/averageof of displayed values of of - displayed displayed displayed displayed - values values values values -*balance -(bs, -bse, cf, -is)* -balance sums of value at value at posting value at value -changes costs report end date report or at - or today journal DATE/today - of sums of end of of - postings sums of sums - postings of - postings -budget like like like balance like like -amounts balance balance changes balances balance -(-budget) changes changes changes -grand sum of sum of sum of displayed sum of sum of -total displayed displayed valued displayed displayed - values values values values -*balance -(bs, -bse, cf, -is) with -report -interval* -starting sums of value at sums of values value at sums -balances costs of report of postings report of -(-H) postings start of before report start of postings - before sums of start at sums of before - report all respective all report - start postings posting dates postings start - before before - report report - start start -balance sums of same as sums of values balance value -changes costs of -value=end of postings in change in at -(bal, postings period at each DATE/today -is, bs in period respective period, of --change, posting dates valued at sums -cf period of --change) ends postings -end sums of same as sums of values period end value -balances costs of -value=end of postings from balances, at -(bal -H, postings before period valued at DATE/today -is -H, from start to period period of -bs, cf) before end at ends sums - report respective of - start to posting dates postings - period end -budget like like like balance like like -amounts balance balance changes/end balances balance -(-budget) changes/end changes/end balances changes/end - balances balances balances -row sums, sums, sums, averages sums, sums, -totals, averages averages of displayed averages averages -row of of values of of -averages displayed displayed displayed displayed -(-T, -A) values values values values -column sums of sums of sums of sums of sums -totals displayed displayed displayed values displayed of - values values values displayed - values -grand sum, sum, sum, average of sum, sum, -total, average of average of column totals average of average -grand column column column of -average totals totals totals column - totals - - '--cumulative' is omitted to save space, it works like '-H' but with -a zero starting balance. - - *Glossary:* - -_cost_ - - calculated using price(s) recorded in the transaction(s). -_value_ - - market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. -_report start_ - - the first day of the report period specified with -b or -p or - date:, otherwise today. -_report or journal start_ - - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. -_report end_ - - the last day of the report period specified with -e or -p or date:, - otherwise today. -_report or journal end_ - - the last day of the report period specified with -e or -p or date:, - otherwise the latest transaction date in the journal, otherwise - today. -_report interval_ - - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report's multi-period mode (whether showing one or many - subperiods). - - -File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Value reporting, Up: Top - -24 PART 4: COMMANDS -******************* - -* Menu: - -* Commands overview:: -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* demo:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* register:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: - - -File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS - -24.1 Commands overview -====================== - -Here are the built-in commands: - -* Menu: - -* DATA ENTRY:: -* DATA CREATION:: -* DATA MANAGEMENT:: -* REPORTS FINANCIAL:: -* REPORTS VERSATILE:: -* REPORTS BASIC:: -* HELP:: -* ADD-ONS:: - - -File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview - -24.1.1 DATA ENTRY ------------------ - -These data entry commands are the only ones which can modify your -journal file. - - * add - add transactions using terminal prompts - * import - add new transactions from other files, eg CSV files - - -File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview - -24.1.2 DATA CREATION --------------------- - - * close - generate balance-zeroing/restoring transactions - * rewrite - generate auto postings, like print -auto - - -File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview - -24.1.3 DATA MANAGEMENT ----------------------- - - * check - check for various kinds of error in the data - * diff - compare account transactions in two journal files - - -File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview - -24.1.4 REPORTS, FINANCIAL -------------------------- - - * aregister (areg) - show transactions in a particular account - * balancesheet (bs) - show assets, liabilities and net worth - * balancesheetequity (bse) - show assets, liabilities and equity - * cashflow (cf) - show changes in liquid assets - * incomestatement (is) - show revenues and expenses - - -File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview - -24.1.5 REPORTS, VERSATILE -------------------------- - - * balance (bal) - show balance changes, end balances, budgets, - gains.. - * print - show transactions or export journal data - * register (reg) - show postings in one or more accounts & running - total - * roi - show return on investments - - -File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview - -24.1.6 REPORTS, BASIC ---------------------- - - * accounts - show account names - * activity - show bar charts of posting counts per period - * codes - show transaction codes - * commodities - show commodity/currency symbols - * descriptions - show transaction descriptions - * files - show input file paths - * notes - show note parts of transaction descriptions - * payees - show payee parts of transaction descriptions - * prices - show market prices - * stats - show journal statistics - * tags - show tag names - * test - run self tests - - -File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview - -24.1.7 HELP ------------ - - * help - show the hledger manual with info/man/pager - * demo - show small hledger demos in the terminal - - -File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview - -24.1.8 ADD-ONS --------------- - -And here are some typical add-on commands. Some of these are installed -by the hledger-install script. If installed, they will appear in -hledger's commands list: - - * ui - run hledger's terminal UI - * web - run hledger's web UI - * iadd - add transactions using a TUI (currently hard to build) - * interest - generate interest transactions - * stockquotes - download market prices from AlphaVantage - * Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, - pijul, plot, and more.. - - Next, each command is described in detail, in alphabetical order. - - -File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS - -24.2 accounts -============= - -Show account names. - - This command lists account names. By default it shows all known -accounts, either used in transactions or declared with account -directives. - - With query arguments, only matched account names and account names -referenced by matched postings are shown. - - Or it can show just the used accounts ('--used'/'-u'), the declared -accounts ('--declared'/'-d'), the accounts declared but not used -('--unused'), the accounts used but not declared ('--undeclared'), or -the first account matched by an account name pattern, if any ('--find'). - - It shows a flat list by default. With '--tree', it uses indentation -to show the account hierarchy. In flat mode you can add '--drop N' to -omit the first few account name components. Account names can be -depth-clipped with 'depth:N' or '--depth N' or '-N'. - - With '--types', it also shows each account's type, if it's known. -(See Declaring accounts > Account types.) - - With '--positions', it also shows the file and line number of each -account's declaration, if any, and the account's overall declaration -order; these may be useful when troubleshooting account display order. - - With '--directives', it adds the 'account' keyword, showing valid -account directives which can be pasted into a journal file. This is -useful together with '--undeclared' when updating your account -declarations to satisfy 'hledger check accounts'. - - The '--find' flag can be used to look up a single account name, in -the same way that the 'aregister' command does. It returns the -alphanumerically-first matched account name, or if none can be found, it -fails with a non-zero exit code. - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - -$ hledger accounts --undeclared --directives >> $LEDGER_FILE -$ hledger check accounts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS - -24.3 activity -============= - -Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - - Examples: - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS - -24.4 add -======== - -Prompt for transactions and add them to the journal. Any arguments will -be used as default inputs for the first N prompts. - - Many hledger users edit their journals directly with a text editor, -or generate them from CSV. For more interactive data entry, there is the -'add' command, which prompts interactively on the console for new -transactions, and appends them to the main journal file (which should be -in journal format). Existing transactions are not changed. This is one -of the few hledger commands that writes to the journal file (see also -'import'). - - To use it, just run 'hledger add' and follow the prompts. You can -add as many transactions as you like; when you are finished, enter '.' -or press control-d or control-c to exit. - - Features: - - * add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as - a template. - * You can also set the initial defaults with command line arguments. - * Readline-style edit keys can be used during data entry. - * The tab key will auto-complete whenever possible - accounts, - payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If - the input area is empty, it will insert the default value. - * If the journal defines a default commodity, it will be added to any - bare numbers entered. - * A parenthesised transaction code may be entered following a date. - * Comments and tags may be entered following a description or amount. - * If you make a mistake, enter '<' at any prompt to go one step - backward. - * Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see https://hledger.org/add.html for a detailed tutorial): - -$ hledger add -Adding transactions to journal file /src/hledger/examples/sample.journal -Any command line arguments will be used as defaults. -Use tab key to complete, readline keys to edit, enter to accept defaults. -An optional (CODE) may follow transaction dates. -An optional ; COMMENT may follow descriptions or amounts. -If you make a mistake, enter < at any prompt to go one step backward. -To end a transaction, enter . when prompted. -To quit, enter . at a date prompt or press control-d or control-c. -Date [2015/05/22]: -Description: supermarket -Account 1: expenses:food -Amount 1: $10 -Account 2: assets:checking -Amount 2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): . -2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - -Save this transaction to the journal ? [y]: -Saved. -Starting the next transaction (. or ctrl-D/ctrl-C to quit) -Date [2015/05/22]: $ - - On Microsoft Windows, the add command makes sure that no part of the -file path ends with a period, as that would cause problems (#1056). - - -File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS - -24.5 aregister -============== - -(areg) - - Show the transactions and running historical balance of a single -account, with each transaction displayed as one line. - - 'aregister' shows the overall transactions affecting a particular -account (and any subaccounts). Each report line represents one -transaction in this account. Transactions before the report start date -are always included in the running balance ('--historical' mode is -always on). - - This is a more "real world", bank-like view than the 'register' -command (which shows individual postings, possibly from multiple -accounts, not necessarily in historical mode). As a quick rule of -thumb: - use 'aregister' for reviewing and reconciling real-world -asset/liability accounts - use 'register' for reviewing detailed -revenues/expenses. - - 'aregister' requires one argument: the account to report on. You can -write either the full account name, or a case-insensitive regular -expression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can -be surprising; eg if you have 'assets:per:checking 1' and -'assets:biz:checking 2' accounts, 'hledger areg checking' would select -'assets:biz:checking 2'. It's just a convenience to save typing, so if -in doubt, write the full account name, or a distinctive substring that -matches uniquely. - - Transactions involving subaccounts of this account will also be -shown. 'aregister' ignores depth limits, so its final total will always -match a balance report with similar arguments. - - Any additional arguments form a query which will filter the -transactions shown. Note some queries will disturb the running balance, -causing it to be different from the account's real-world running -balance. - - An example: this shows the transactions and historical running -balance during july, in the first account whose name contains -"checking": - -$ hledger areg checking date:jul - - Each 'aregister' line item shows: - - * the transaction's date (or the relevant posting's date if - different, see below) - * the names of all the other account(s) involved in this transaction - (probably abbreviated) - * the total change to this account's balance from this transaction - * the account's historical running balance after this transaction. - - Transactions making a net change of zero are not shown by default; -add the '-E/--empty' flag to show them. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -'--align-all' flag. - - This command also supports the output destination and output format -options. The output formats supported are 'txt', 'csv', 'tsv', and -'json'. - -* Menu: - -* aregister and posting dates:: - - -File: hledger.info, Node: aregister and posting dates, Up: aregister - -24.5.1 aregister and posting dates ----------------------------------- - -aregister always shows one line (and date and amount) per transaction. -But sometimes transactions have postings with different dates. Also, -not all of a transaction's postings may be within the report period. To -resolve this, aregister shows the earliest of the transaction's date and -posting dates that is in-period, and the sum of the in-period postings. -In other words it will show a combined line item with just the earliest -date, and the running balance will (temporarily, until the transaction's -last posting) be inaccurate. Use 'register -H' if you need to see the -individual postings. - - There is also a '--txn-dates' flag, which filters strictly by -transaction date, ignoring posting dates. This too can cause an -inaccurate running balance. - - -File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS - -24.6 balance -============ - -(bal) - - Show accounts and their balances. - - 'balance' is one of hledger's oldest and most versatile commands, for -listing account balances, balance changes, values, value changes and -more, during one time period or many. Generally it shows a table, with -rows representing accounts, and columns representing periods. - - Note there are some higher-level variants of the 'balance' command -with convenient defaults, which can be simpler to use: 'balancesheet', -'balancesheetequity', 'cashflow' and 'incomestatement'. When you need -more control, then use 'balance'. - -* Menu: - -* balance features:: -* Simple balance report:: -* Balance report line format:: -* Filtered balance report:: -* List or tree mode:: -* Depth limiting:: -* Dropping top-level accounts:: -* Showing declared accounts:: -* Sorting by amount:: -* Percentages:: -* Multi-period balance report:: -* Balance change end balance:: -* Balance report types:: -* Budget report:: -* Balance report layout:: -* Useful balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -24.6.1 balance features ------------------------ - -Here's a quick overview of the 'balance' command's features, followed by -more detailed descriptions and examples. Many of these work with the -higher-level commands as well. - - 'balance' can show.. - - * accounts as a list ('-l') or a tree ('-t') - * optionally depth-limited ('-[1-9]') - * sorted by declaration order and name, or by amount - - ..and their.. - - * balance changes (the default) - * or actual and planned balance changes ('--budget') - * or value of balance changes ('-V') - * or change of balance values ('--valuechange') - * or unrealised capital gain/loss ('--gain') - * or postings count ('--count') - - ..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', 'tsv', 'json', and -(multi-period reports only:) 'html'. In 'txt' output in a -colour-supporting terminal, negative amounts are shown in red. - - The '--related'/'-r' flag shows the balance of the _other_ postings -in the transactions of the postings which would normally be shown. - - -File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance - -24.6.2 Simple balance report ----------------------------- - -With no arguments, 'balance' shows a list of all accounts and their -change of balance - ie, the sum of posting amounts, both inflows and -outflows - during the entire period of the journal. ("Simple" here -means just one column of numbers, covering a single period. You can -also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end -balance at the end of the journal period; more on this below. - - Accounts are sorted by declaration order if any, and then -alphabetically by account name. For instance (using -examples/sample.journal): - -$ hledger -f examples/sample.journal bal - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - Accounts with a zero balance (and no non-zero subaccounts, in tree -mode - see below) are hidden by default. Use '-E/--empty' to show them -(revealing 'assets:bank:checking' here): - -$ hledger -f examples/sample.journal bal -E - 0 assets:bank:checking - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - The total of the amounts displayed is shown as the last line, unless -'-N'/'--no-total' is used. - - -File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance - -24.6.3 Balance report line format ---------------------------------- - -For single-period balance reports displayed in the terminal (only), you -can use '--format FMT' to customise the format and content of each line. -Eg: - -$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 - - The FMT format string specifies the formatting applied to each -account/balance pair. It may contain any suitable text, with data -fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - - * MAX truncates at this width (optional) - - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance - -24.6.4 Filtered balance report ------------------------------- - -You can show fewer accounts, a different time period, totals from -cleared transactions only, etc. by using query arguments or options to -limit the postings being matched. Eg: - -$ hledger -f examples/sample.journal bal --cleared assets date:200806 - $-2 assets:cash --------------------- - $-2 - - -File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance - -24.6.5 List or tree mode ------------------------- - -By default, or with '-l/--flat', accounts are shown as a flat list with -their full names visible, as in the examples above. - - With '-t/--tree', the account hierarchy is shown, with subaccounts' -"leaf" names indented below their parent: - -$ hledger -f examples/sample.journal balance - $-1 assets - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts --------------------- - 0 - - Notes: - - * "Boring" accounts are combined with their subaccount for more - compact output, unless '--no-elide' is used. Boring accounts have - no balance of their own and just one subaccount (eg 'assets:bank' - and 'liabilities' above). - - * All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, - which requires explanation when sharing reports with - non-plaintextaccounting-users. A tree mode report's final total is - the sum of the top-level balances shown, not of all the balances - shown. - - * Each group of sibling accounts (ie, under a common parent) is - sorted separately. - - -File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance - -24.6.6 Depth limiting ---------------------- - -With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: -'-3') balance reports will show accounts only to the specified depth, -hiding the deeper subaccounts. This can be useful for getting an -overview without too much detail. - - Account balances at the depth limit always include the balances from -any deeper subaccounts (even in list mode). Eg, limiting to depth 1: - -$ hledger -f examples/sample.journal balance -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities --------------------- - 0 - - -File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance - -24.6.7 Dropping top-level accounts ----------------------------------- - -You can also hide one or more top-level account name parts, using -'--drop NUM'. This can be useful for hiding repetitive top-level -account names: - -$ hledger -f examples/sample.journal bal expenses --drop 1 - $1 food - $1 supplies --------------------- - $2 - - -File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance - -24.6.8 Showing declared accounts --------------------------------- - -With '--declared', accounts which have been declared with an account -directive will be included in the balance report, even if they have no -transactions. (Since they will have a zero balance, you will also need -'-E/--empty' to see them.) - - More precisely, _leaf_ declared accounts (with no subaccounts) will -be included, since those are usually the more useful in reports. - - The idea of this is to be able to see a useful "complete" balance -report, even when you don't have transactions in all of your declared -accounts yet. - - -File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance - -24.6.9 Sorting by amount ------------------------- - -With '-S/--sort-amount', accounts with the largest (most positive) -balances are shown first. Eg: 'hledger bal expenses -MAS' shows your -biggest averaged monthly expenses first. When more than one commodity -is present, they will be sorted by the alphabetically earliest commodity -first, and then by subsequent commodities (if an amount is missing a -commodity, it is treated as 0). - - Revenues and liability balances are typically negative, however, so -'-S' shows these in reverse order. To work around this, you can add -'--invert' to flip the signs. (Or, use one of the higher-level reports, -which flip the sign automatically. Eg: 'hledger incomestatement -MAS'). - - -File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance - -24.6.10 Percentages -------------------- - -With '-%/--percent', balance reports show each account's value expressed -as a percentage of the (column) total. - - Note it is not useful to calculate percentages if the amounts in a -column have mixed signs. In this case, make a separate report for each -sign, eg: - -$ hledger bal -% amt:`>0` -$ hledger bal -% amt:`<0` - - Similarly, if the amounts in a column have mixed commodities, convert -them to one commodity with '-B', '-V', '-X' or '--value', or make a -separate report for each commodity: - -$ hledger bal -% cur:\\$ -$ hledger bal -% cur:€ - - -File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance - -24.6.11 Multi-period balance report ------------------------------------ - -With a report interval (set by the '-D/--daily', '-W/--weekly', -'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag), -'balance' shows a tabular report, with columns representing successive -time periods (and a title): - -$ hledger -f examples/sample.journal bal --quarterly income expenses -E -Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 -===================++================================= - expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 --------------------++--------------------------------- - || $-1 $1 0 0 - - Notes: - - * The report's start/end dates will be expanded, if necessary, to - fully encompass the displayed subperiods (so that the first and - last subperiods have the same duration as the others). - * Leading and trailing periods (columns) containing all zeroes are - not shown, unless '-E/--empty' is used. - * Accounts (rows) containing all zeroes are not shown, unless - '-E/--empty' is used. - * Amounts with many commodities are shown in abbreviated form, unless - '--no-elide' is used. _(experimental)_ - * Average and/or total columns can be added with the '-A/--average' - and '-T/--row-total' flags. - * The '--transpose' flag can be used to exchange rows and columns. - * The '--pivot FIELD' option causes a different transaction field to - be used as "account name". See PIVOTING. - - Multi-period reports with many periods can be too wide for easy -viewing in the terminal. Here are some ways to handle that: - - * Hide the totals row with '-N/--no-total' - * Convert to a single currency with '-V' - * Maximize the terminal window - * Reduce the terminal's font size - * View with a pager like less, eg: 'hledger bal -D --color=yes | less - -RS' - * Output as CSV and use a CSV viewer like visidata ('hledger bal -D - -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or - a spreadsheet ('hledger bal -D -o a.csv && open a.csv') - * Output as HTML and view with a browser: 'hledger bal -D -o a.html - && open a.html' - - -File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance - -24.6.12 Balance change, end balance ------------------------------------ - -It's important to be clear on the meaning of the numbers shown in -balance reports. Here is some terminology we use: - - A *_balance change_* is the net amount added to, or removed from, an -account during some period. - - An *_end balance_* is the amount accumulated in an account as of some -date (and some time, but hledger doesn't store that; assume end of day -in your timezone). It is the sum of previous balance changes. - - We call it a *_historical end balance_* if it includes all balance -changes since the account was created. For a real world account, this -means it will match the "historical record", eg the balances reported in -your bank statements or bank web UI. (If they are correct!) - - In general, balance changes are what you want to see when reviewing -revenues and expenses, and historical end balances are what you want to -see when reviewing or reconciling asset, liability and equity accounts. - - 'balance' shows balance changes by default. To see accurate -historical end balances: - - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the - journal covers the account's full lifetime. - - 2. Include all of of the account's prior postings in the report, by - not specifying a report start date, or by using the - '-H/--historical' flag. ('-H' causes report start date to be - ignored when summing postings.) - - -File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance - -24.6.13 Balance report types ----------------------------- - -The balance command is quite flexible; here is the full detail on how to -control what it reports. If the following seems complicated, don't -worry - this is for advanced reporting, and it does take time and -experimentation to get familiar with all the report modes. - - There are three important option groups: - - 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] -...' - -* Menu: - -* Calculation type:: -* Accumulation type:: -* Valuation type:: -* Combining balance report types:: - - -File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types - -24.6.13.1 Calculation type -.......................... - -The basic calculation to perform for each table cell. It is one of: - - * '--sum' : sum the posting amounts (*default*) - * '--budget' : sum the amounts, but also show the budget goal amount - (for each account/period) - * '--valuechange' : show the change in period-end historical balance - values (caused by deposits, withdrawals, and/or market price - fluctuations) - * '--gain' : show the unrealised capital gain/loss, (the current - valued balance minus each amount's original cost) - * '--count' : show the count of postings - - -File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types - -24.6.13.2 Accumulation type -........................... - -How amounts should accumulate across report periods. Another way to say -it: which time period's postings should contribute to each cell's -calculation. It is one of: - - * '--change' : calculate with postings from column start to column - end, ie "just this column". Typically used to see - revenues/expenses. (*default for balance, incomestatement*) - - * '--cumulative' : calculate with postings from report start to - column end, ie "previous columns plus this column". Typically used - to show changes accumulated since the report's start date. Not - often used. - - * '--historical/-H' : calculate with postings from journal start to - column end, ie "all postings from before report start date until - this column's end". Typically used to see historical end balances - of assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) - - -File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types - -24.6.13.3 Valuation type -........................ - -Which kind of value or cost conversion should be applied, if any, before -displaying the report. It is one of: - - * no valuation type : don't convert to cost or value (*default*) - * '--value=cost[,COMM]' : convert amounts to cost (then optionally to - some other commodity) - * '--value=then[,COMM]' : convert amounts to market value on - transaction dates - * '--value=end[,COMM]' : convert amounts to market value on period - end date(s) - (*default with '--valuechange', '--gain'*) - * '--value=now[,COMM]' : convert amounts to market value on today's - date - * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on - another date - - or one of the equivalent simpler flags: - - * '-B/--cost' : like -value=cost (though, note -cost and -value are - independent options which can both be used at once) - * '-V/--market' : like -value=end - * '-X COMM/--exchange COMM' : like -value=end,COMM - - See Cost reporting and Value reporting for more about these. - - -File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types - -24.6.13.4 Combining balance report types -........................................ - -Most combinations of these options should produce reasonable reports, -but if you find any that seem wrong or misleading, let us know. The -following restrictions are applied: - - * '--valuechange' implies '--value=end' - * '--valuechange' makes '--change' the default when used with the - 'balancesheet'/'balancesheetequity' commands - * '--cumulative' or '--historical' disables '--row-total/-T' - - For reference, here is what the combinations of accumulation and -valuation show: - -Valuation:>no valuation '--value= then' '--value= end' '--value= -Accumulation:v YYYY-MM-DD - /now' ------------------------------------------------------------------------------ -'--change'change in sum of period-end DATE-value - period posting-date value of of change in - market values change in period - in period period -'--cumulative'change from sum of period-end DATE-value - report start to posting-date value of of change - period end market values change from from report - from report report start start to - start to period to period end period end - end -'--historicalchange from sum of period-end DATE-value -/-H' journal start posting-date value of of change - to period end market values change from from journal - (historical end from journal journal start start to - balance) start to period to period end period end - end - - -File: hledger.info, Node: Budget report, Next: Balance report layout, Prev: Balance report types, Up: balance - -24.6.14 Budget report ---------------------- - -The '--budget' report type activates extra columns showing any budget -goals for each account and period. The budget goals are defined by -periodic transactions. This is useful for comparing planned and actual -income, expenses, time usage, etc. - - For example, you can take average monthly expenses in the common -expense categories to construct a minimal monthly budget: - -;; Budget -~ monthly - income $2000 - expenses:food $400 - expenses:bus $50 - expenses:movies $30 - assets:bank:checking - -;; Two months worth of expenses -2017-11-01 - income $1950 - expenses:food $396 - expenses:bus $49 - expenses:movies $30 - expenses:supplies $20 - assets:bank:checking - -2017-12-01 - income $2100 - expenses:food $412 - expenses:bus $53 - expenses:gifts $100 - assets:bank:checking - - You can now see a monthly budget report: - -$ hledger balance -M --budget -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - This is different from a normal balance report in several ways. -Currently: - - * Accounts with budget goals during the report period, and their - parents, are shown. - * Their subaccounts are not shown (regardless of the depth setting). - * Accounts without budget goals, if any, are aggregated and shown as - "". - * Amounts are always inclusive (subaccount-including), even in list - mode. - * After each actual amount, the corresponding goal amount and - percentage of goal reached are also shown, in square brackets. - - This means that the numbers displayed will not always add up! Eg -above, the 'expenses' actual amount includes the gifts and supplies -transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts -are not shown, as they have no budget amounts declared. - - This can be confusing. When you need to make things clearer, use the -'-E/--empty' flag, which will reveal all accounts including unbudgeted -ones, giving the full picture. Eg: - -$ hledger balance -M --budget --empty -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - expenses:supplies || $20 0 - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - You can roll over unspent budgets to next period with '--cumulative': - -$ hledger balance -M --budget --cumulative -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] - expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] - expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] - income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] -----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - It's common to limit budgets/budget reports to just expenses - -hledger bal -M --budget expenses - - or just revenues and expenses (eg, using account types): - -hledger bal -M --budget type:rx - - It's also common to limit or convert them to a single currency -('cur:COMM' or '-X COMM [--infer-market-prices]'). If showing multiple -currencies, '--layout bare' or '--layout tall' can help. - - For more examples and notes, see Budgeting. - -* Menu: - -* Budget report start date:: -* Budgets and subaccounts:: -* Selecting budget goals:: -* Budget vs forecast:: - - -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report - -24.6.14.1 Budget report start date -.................................. - -This might be a bug, but for now: when making budget reports, it's a -good idea to explicitly set the report's start date to the first day of -a reporting period, because a periodic rule like '~ monthly' generates -its transactions on the 1st of each month, and if your journal has no -regular transactions on the 1st, the default report start date could -exclude that budget goal, which can be a little surprising. Eg here the -default report period is just the day of 2020-01-15: - -~ monthly in 2020 - (expenses:food) $500 - -2020-01-15 - expenses:food $400 - assets:checking - -$ hledger bal expenses --budget -Budget performance in 2020-01-15: - - || 2020-01-15 -==============++============ - || $400 ---------------++------------ - || $400 - - To avoid this, specify the budget report's period, or at least the -start date, with '-b'/'-e'/'-p'/'date:', to ensure it includes the -budget goal transactions (periodic transactions) that you want. Eg, -adding '-b 2020/1/1' to the above: - -$ hledger bal expenses --budget -b 2020/1/1 -Budget performance in 2020-01-01..2020-01-15: - - || 2020-01-01..2020-01-15 -===============++======================== - expenses:food || $400 [80% of $500] ----------------++------------------------ - || $400 [80% of $500] - - -File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report - -24.6.14.2 Budgets and subaccounts -................................. - -You can add budgets to any account in your account hierarchy. If you -have budgets on both parent account and some of its children, then -budget(s) of the child account(s) would be added to the budget of their -parent, much like account balances behave. - - In the most simple case this means that once you add a budget to any -account, all its parents would have budget as well. - - To illustrate this, consider the following budget: - -~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - With this, monthly budget for electronics is defined to be $100 and -budget for personal expenses is an additional $1000, which implicitly -means that budget for both 'expenses:personal' and 'expenses' is $1100. - - Transactions in 'expenses:personal:electronics' will be counted both -towards its $100 budget and $1100 of 'expenses:personal' , and -transactions in any other subaccount of 'expenses:personal' would be -counted towards only towards the budget of 'expenses:personal'. - - For example, let's consider these transactions: - -~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - -2019/01/01 Google home hub - expenses:personal:electronics $90.00 - liabilities $-90.00 - -2019/01/02 Phone screen protector - expenses:personal:electronics:upgrades $10.00 - liabilities - -2019/01/02 Weekly train ticket - expenses:personal:train tickets $153.00 - liabilities - -2019/01/03 Flowers - expenses:personal $30.00 - liabilities - - As you can see, we have transactions in -'expenses:personal:electronics:upgrades' and 'expenses:personal:train -tickets', and since both of these accounts are without explicitly -defined budget, these transactions would be counted towards budgets of -'expenses:personal:electronics' and 'expenses:personal' accordingly: - -$ hledger balance --budget -M -Budget performance in 2019/01: - - || Jan -===============================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] --------------------------------++------------------------------- - || 0 [ 0] - - And with '--empty', we can get a better picture of budget allocation -and consumption: - -$ hledger balance --budget -M --empty -Budget performance in 2019/01: - - || Jan -========================================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] -----------------------------------------++------------------------------- - || 0 [ 0] - - -File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report - -24.6.14.3 Selecting budget goals -................................ - -The budget report evaluates periodic transaction rules to generate -special "goal transactions", which generate the goal amounts for each -account in each report subperiod. When troubleshooting, you can use -'print --forecast' to show these as forecasted transactions: - -$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated - - By default, the budget report uses all available periodic transaction -rules to generate goals. This includes rules with a different report -interval from your report. Eg if you have daily, weekly and monthly -periodic rules, all of these will contribute to the goals in a monthly -budget report. - - You can select a subset of periodic rules by providing an argument to -the '--budget' flag. '--budget=DESCPAT' will match all periodic rules -whose description contains DESCPAT, a case-insensitive substring (not a -regular expression or query). This means you can give your periodic -rules descriptions (remember that two spaces are needed), and then -select from multiple budgets defined in your journal. - - -File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report - -24.6.14.4 Budget vs forecast -............................ - -'hledger --forecast ...' and 'hledger balance --budget ...' are separate -features, though both of them use the periodic transaction rules defined -in the journal, and both of them generate temporary transactions for -reporting purposes ("forecast transactions" and "budget goal -transactions", respectively). You can use both features at the same -time if you want. Here are some differences between them, as of hledger -1.29: - - CLI: - - * -forecast is a general hledger option, usable with any command - * -budget is a 'balance' command option, usable only with that - command. - - Visibility of generated transactions: - - * forecast transactions are visible in any report, like ordinary - transactions - * budget goal transactions are invisible except for the goal amounts - they produce in -budget reports. - - Periodic transaction rules: - - * -forecast uses all available periodic transaction rules - * -budget uses all periodic rules ('--budget') or a selected subset - ('--budget=DESCPAT') - - Period of generated transactions: - - * -forecast generates forecast transactions - * from after the last regular transaction to the end of the - report period ('--forecast') - * or, during a specified period ('--forecast=PERIODEXPR') - * possibly further restricted by a period specified in the - periodic transaction rule - * and always restricted within the bounds of the report period - - * -budget generates budget goal transactions - * throughout the report period - * possibly restricted by a period specified in the periodic - transaction rule. - - -File: hledger.info, Node: Balance report layout, Next: Useful balance reports, Prev: Budget report, Up: balance - -24.6.15 Balance report layout ------------------------------ - -The '--layout' option affects how balance reports show multi-commodity -amounts and commodity symbols, which can improve readability. It can -also normalise the data for easy consumption by other programs. It has -four possible values: - - * '--layout=wide[,WIDTH]': commodities are shown on a single line, - optionally elided to WIDTH - * '--layout=tall': each commodity is shown on a separate line - * '--layout=bare': commodity symbols are in their own column, amounts - are bare numbers - * '--layout=tidy': data is normalised to easily-consumed "tidy" form, - with one row per data value - - Here are the '--layout' modes supported by each output format; note -only CSV output supports all of them: - -- txt csv html json sql ---------------------------------------- -wide Y Y Y -tall Y Y Y -bare Y Y Y -tidy Y - - Examples: - - * Wide layout. With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - * Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - * Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - * Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - * Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - * Note: bare layout will sometimes display an extra row for the - no-symbol commodity, because of zero amounts (hledger treats zeroes - as commodity-less, usually). This can break 'hledger-bar' - confusingly (workaround: add a 'cur:' query to exclude the - no-symbol row). - - * Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here's how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - -File: hledger.info, Node: Useful balance reports, Prev: Balance report layout, Up: balance - -24.6.16 Useful balance reports ------------------------------- - -Some frequently used 'balance' options/reports are: - - * 'bal -M revenues expenses' - Show revenues/expenses in each month. Also available as the - 'incomestatement' command. - - * 'bal -M -H assets liabilities' - Show historical asset/liability balances at each month end. Also - available as the 'balancesheet' command. - - * 'bal -M -H assets liabilities equity' - Show historical asset/liability/equity balances at each month end. - Also available as the 'balancesheetequity' command. - - * 'bal -M assets not:receivable' - Show changes to liquid assets in each month. Also available as the - 'cashflow' command. - - Also: - - * 'bal -M expenses -2 -SA' - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - * 'bal -M --budget expenses' - Show monthly expenses and budget goals. - - * 'bal -M --valuechange investments' - Show monthly change in market value of investment assets. - - * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert]' - Show top gainers [or losers] last week - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS - -24.7 balancesheet -================= - -(bs) - - This command displays a balance sheet, showing historical ending -balances of asset and liability accounts. (To see equity as well, use -the balancesheetequity command.) Amounts are shown with normal positive -sign, as in conventional financial statements. - - This report shows accounts declared with the 'Asset', 'Cash' or -'Liability' type (see account types). Or if no such accounts are -declared, it shows top-level accounts named 'asset' or 'liability' (case -insensitive, plurals allowed) and their subaccounts. - - Example: - -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance -H assets liabilities', but with -smarter account detection, and liabilities displayed with their sign -flipped. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS - -24.8 balancesheetequity -======================= - -(bse) - - This command displays a balance sheet, showing historical ending -balances of asset, liability and equity accounts. Amounts are shown -with normal positive sign, as in conventional financial statements. - - This report shows accounts declared with the 'Asset', 'Cash', -'Liability' or 'Equity' type (see account types). Or if no such -accounts are declared, it shows top-level accounts named 'asset', -'liability' or 'equity' (case insensitive, plurals allowed) and their -subaccounts. - - Example: - -$ hledger balancesheetequity -Balance Sheet With Equity - -Assets: - $-2 assets - $1 bank:saving - $-3 cash --------------------- - $-2 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Equity: - $1 equity:owner --------------------- - $1 - -Total: --------------------- - 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance -H assets liabilities equity', but -with smarter account detection, and liabilities/equity displayed with -their sign flipped. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS - -24.9 cashflow -============= - -(cf) - - This command displays a cashflow statement, showing the inflows and -outflows affecting "cash" (ie, liquid, easily convertible) assets. -Amounts are shown with normal positive sign, as in conventional -financial statements. - - This report shows accounts declared with the 'Cash' type (see account -types). Or if no such accounts are declared, it shows accounts - - * under a top-level account named 'asset' (case insensitive, plural - allowed) - * whose name contains some variation of 'cash', 'bank', 'checking' or - 'saving'. - - More precisely: all accounts matching this case insensitive regular -expression: - - '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)' - - and their subaccounts. - - An example cashflow report: - -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance assets not:fixed not:investment -not:receivable', but with smarter account detection. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS - -24.10 check -=========== - -Check for various kinds of errors in your data. - - hledger provides a number of built-in error checks to help prevent -problems in your data. Some of these are run automatically; or, you can -use this 'check' command to run them on demand, with no output and a -zero exit code if all is well. Specify their names (or a prefix) as -argument(s). - - Some examples: - -hledger check # basic checks -hledger check -s # basic + strict checks -hledger check ordereddates payees # basic + two other checks - - If you are an Emacs user, you can also configure flycheck-hledger to -run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available: - -* Menu: - -* Default checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: -* More about specific checks:: - - -File: hledger.info, Node: Default checks, Next: Strict checks, Up: check - -24.10.1 Default checks ----------------------- - -These checks are run automatically by (almost) all hledger commands: - - * *parseable* - data files are in a supported format, with no syntax - errors and no invalid include directives. - - * *autobalanced* - all transactions are balanced, after converting to - cost. Missing amounts and missing costs are inferred automatically - where possible. - - * *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: Default checks, Up: check - -24.10.2 Strict checks ---------------------- - -These additional checks are run when the '-s'/'--strict' (strict mode) -flag is used. Or, they can be run by giving their names as arguments to -'check': - - * *balanced* - all transactions are balanced after converting to - cost, without inferring missing costs. If conversion costs are - required, they must be explicit. - - * *accounts* - all account names used by transactions have been - declared - - * *commodities* - all commodity symbols used have been declared - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -24.10.3 Other checks --------------------- - -These checks can be run only by giving their names as arguments to -'check'. They are more specialised and not desirable for everyone: - - * *ordereddates* - transactions are ordered by date within each file - - * *payees* - all payees used by transactions have been declared - - * *recentassertions* - all accounts with balance assertions have a - balance assertion within 7 days of their latest posting - - * *tags* - all tags used by transactions have been declared - - * *uniqueleafnames* - all account leaf names are unique - - -File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check - -24.10.4 Custom checks ---------------------- - -A few more checks are are available as separate add-on commands, in -https://github.com/simonmichael/hledger/tree/master/bin: - - * *hledger-check-tagfiles* - all tag values containing / (a forward - slash) exist as file paths - - * *hledger-check-fancyassertions* - more complex balance assertions - are passing - - You could make similar scripts to perform your own custom checks. -See: Cookbook -> Scripting. - - -File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check - -24.10.5 More about specific checks ----------------------------------- - -'hledger check recentassertions' will complain if any balance-asserted -account has postings more than 7 days after its latest balance -assertion. This aims to prevent the situation where you are regularly -updating your journal, but forgetting to check your balances against the -real world, then one day must dig back through months of data to find an -error. It assumes that adding a balance assertion requires/reminds you -to check the real-world balance. (That may not be true if you -auto-generate balance assertions from bank data; in that case, I -recommend to import transactions uncleared, and when you manually review -and clear them, also check the latest assertion against the real-world -balance.) - - -File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS - -24.11 close -=========== - -(equity) - - Generate transactions which transfer account balances to and/or from -another account (typically equity). This can be useful for migrating -balances to a new journal file, or for merging earnings into equity at -end of accounting period. - - By default, it prints a transaction that zeroes out ALE accounts -(asset, liability, equity accounts; this requires account types to be -configured); or if ACCTQUERY is provided, the accounts matched by that. - - _(experimental)_ - - This command has four main modes, corresponding to the most common -use cases: - - 1. With '--close' (default), it prints a "closing balances" - transaction that zeroes out ALE (asset, liability, equity) accounts - by default (this requires account types to be inferred or - declared); or, the accounts matched by the provided ACCTQUERY - arguments. - - 2. With '--open', it prints an opposite "opening balances" transaction - that restores those balances from zero. This is similar to - Ledger's equity command. - - 3. With '--migrate', it prints both the closing and opening - transactions. This is the preferred way to migrate balances to a - new file: run 'hledger close --migrate', add the closing - transaction at the end of the old file, and add the opening - transaction at the start of the new file. The matching - closing/opening transactions cancel each other out, preserving - correct balances during multi-file reporting. - - 4. With '--retain', it prints a "retain earnings" transaction that - transfers RX (revenue and expense) balances to 'equity:retained - earnings'. Businesses traditionally do this at the end of each - accounting period; it is less necessary with computer-based - accounting, but it could still be useful if you want to see the - accounting equation (A=L+E) satisfied. - - In all modes, the defaults can be overridden: - - * the transaction descriptions can be changed with - '--close-desc=DESC' and '--open-desc=DESC' - * the account to transfer to/from can be changed with - '--close-acct=ACCT' and '--open-acct=ACCT' - * the accounts to be closed/opened can be changed with 'ACCTQUERY' - (account query arguments). - * the closing/opening dates can be changed with '-e DATE' (a report - end date) - - By default just one destination/source posting will be used, with its -amount left implicit. With '--x/--explicit', the amount will be shown -explicitly, and if it involves multiple commodities, a separate posting -will be generated for each of them (similar to 'print -x'). - - With '--show-costs', any amount costs are shown, with separate -postings for each cost. This is currently the best way to view -investment lots. If you have many currency conversion or investment -transactions, it can generate very large journal entries. - - With '--interleaved', each individual transfer is shown with source -and destination postings next to each other. This could be useful for -troubleshooting. - - The default closing date is yesterday, or the journal's end date, -whichever is later. You can change this by specifying a report end date -with '-e'. The last day of the report period will be the closing date, -eg '-e 2024' means "close on 2023-12-31". The opening date is always -the day after the closing date. - -* Menu: - -* close and balance assertions:: -* Example retain earnings:: -* Example migrate balances to a new file:: -* Example excluding closing/opening transactions:: - - -File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Up: close - -24.11.1 close and balance assertions ------------------------------------- - -Balance assertions will be generated, verifying that the accounts have -been reset to zero (and then restored to their previous balances, if -there is an opening transaction). - - These provide useful error checking, but you can ignore them -temporarily with '-I', or remove them if you prefer. - - You probably should avoid filtering transactions by status or -realness ('-C', '-R', 'status:'), or generating postings ('--auto'), -with this command, since the balance assertions would depend on these. - - Note custom posting dates spanning the file boundary will disrupt the -balance assertions: - -2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve that you can transfer the money to and from a temporary -account, in effect splitting the multi-day transaction into two -single-day transactions: - -; in 2022.journal: -2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - -; in 2023.journal: -2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - -File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close - -24.11.2 Example: retain earnings --------------------------------- - -Record 2022's revenues/expenses as retained earnings on 2022-12-31, -appending the generated transaction to the journal: - -$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - Note 2022's income statement will now show only zeroes, because -revenues and expenses have been moved entirely to equity. To see them -again, you could exclude the retain transaction: - -$ hledger -f 2022.journal is not:desc:'retain earnings' - - -File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close - -24.11.3 Example: migrate balances to a new file ------------------------------------------------ - -Close assets/liabilities/equity on 2022-12-31 and re-open them on -2023-01-01: - -$ hledger close --migrate -f 2022.journal -p 2022 -# copy/paste the closing transaction to the end of 2022.journal -# copy/paste the opening transaction to the start of 2023.journal - - Now 2022's balance sheet will show only zeroes, indicating a balanced -accounting equation. (Unless you are using @/@@ notation - in that -case, try adding -infer-equity.) To see the end-of-year balances again, -you could exclude the closing transaction: - -$ hledger -f 2022.journal bs not:desc:'closing balances' - - -File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close - -24.11.4 Example: excluding closing/opening transactions -------------------------------------------------------- - -When combining many files for multi-year reports, the closing/opening -transactions cause some noise in transaction-oriented reports like -'print' and 'register'. You can exclude them as shown above, but -'not:desc:...' is not ideal as it depends on consistent descriptions; -also you will want to avoid excluding the very first opening -transaction, which could be awkward. Here is one alternative, using -tags: - - Add 'clopen:' tags to all opening/closing balances transactions -except the first, like this: - -; 2021.journal -2021-06-01 first opening balances -... -2021-12-31 closing balances ; clopen:2022 -... - -; 2022.journal -2022-01-01 opening balances ; clopen:2022 -... -2022-12-31 closing balances ; clopen:2023 -... - -; 2023.journal -2023-01-01 opening balances ; clopen:2023 -... - - Now, assuming a combined journal like: - -; all.journal -include 2021.journal -include 2022.journal -include 2023.journal - - The 'clopen:' tag can exclude all but the first opening transaction. -To show a clean multi-year checking register: - -$ hledger -f all.journal areg checking not:tag:clopen - - And the year values allow more precision. To show 2022's year-end -balance sheet: - -$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 - - -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS - -24.12 codes -=========== - -List the codes seen in transactions, in the order parsed. - - This command prints the value of each transaction's code field, in -the order transactions were parsed. The transaction code is an optional -value written in parentheses between the date and description, often -used to store a cheque number, order number or similar. - - Transactions aren't required to have a code, and missing or empty -codes will not be shown by default. With the '-E'/'--empty' flag, they -will be printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - -2022/1/1 (123) Supermarket - Food $5.00 - Checking - -2022/1/2 (124) Post Office - Postage $8.32 - Checking - -2022/1/3 Supermarket - Food $11.23 - Checking - -2022/1/4 (126) Post Office - Postage $3.21 - Checking - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - -126 - - -File: hledger.info, Node: commodities, Next: demo, Prev: codes, Up: PART 4 COMMANDS - -24.13 commodities -================= - -List all commodity/currency symbols used or declared in the journal. - - -File: hledger.info, Node: demo, Next: descriptions, Prev: commodities, Up: PART 4 COMMANDS - -24.14 demo -========== - -Play demos of hledger usage in the terminal, if asciinema is installed. - - Run this command with no argument to list the demos. To play a demo, -write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/-speed SPEED option to set your preferred playback speed, -eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. -The default speed is 2x. - - Other asciinema options can be added following a double dash, eg '-- --i.1' to limit pauses or '-- -h' to list asciinema's other options. - - During playback, several keys are available: SPACE to pause/unpause, -. to step forward (while paused), CTRL-c quit. - - Examples: - -$ hledger demo # list available demos -$ hledger demo 1 # play the first demo at default speed (2x) -$ hledger demo install -s4 # play the "install" demo at 4x speed - - -File: hledger.info, Node: descriptions, Next: diff, Prev: demo, Up: PART 4 COMMANDS - -24.15 descriptions -================== - -List the unique descriptions that appear in transactions. - - This command lists the unique descriptions that appear in -transactions, in alphabetic order. You can add a query to select a -subset of transactions. - - Example: - -$ hledger descriptions -Store Name -Gas Station | Petrol -Person A - - -File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS - -24.16 diff -========== - -Compares a particular account's transactions in two input files. It -shows any transactions to this account which are in one file but not in -the other. - - More precisely, for each posting affecting this account in either -file, it looks for a corresponding posting in the other file which posts -the same amount to the same account (ignoring date, description, etc.) -Since postings not transactions are compared, this also works when -multiple bank transactions have been combined into a single journal -entry. - - This is useful eg if you have downloaded an account's transactions -from your bank (eg as CSV data). When hledger and your bank disagree -about the account balance, you can compare the bank data with your -journal to find out the cause. - - Examples: - -$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only: - -2014/01/01 Opening Balances - assets:bank:giro EUR ... - ... - equity:opening balances EUR -... - -These transactions are in the second file only: - - -File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS - -24.17 files -=========== - -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - - -File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS - -24.18 help -========== - -Show the hledger user manual in the terminal, with 'info', 'man', or a -pager. With a TOPIC argument, open it at that topic if possible. TOPIC -can be any heading in the manual, or a heading prefix, case insensitive. -Eg: 'commands', 'print', 'forecast', 'journal', 'amount', '"auto -postings"'. - - This command shows the hledger manual built in to your hledger -version. It can be useful when offline, or when you prefer the terminal -to a web browser, or when the appropriate hledger manual or viewing -tools are not installed on your system. - - By default it chooses the best viewer found in $PATH, trying (in this -order): 'info', 'man', '$PAGER', 'less', 'more'. You can force the use -of info, man, or a pager with the '-i', '-m', or '-p' flags, If no -viewer can be found, or the command is run non-interactively, it just -prints the manual to stdout. - - If using 'info', note that version 6 or greater is needed for TOPIC -lookup. If you are on mac you will likely have info 4.8, and should -consider installing a newer version, eg with 'brew install texinfo' -(#1770). - - Examples - -$ hledger help --help # show how the help command works -$ hledger help # show the hledger manual with info, man or $PAGER -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help -m journal # show it with man, even if info is installed - - -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS - -24.19 import -============ - -Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. - - This command may append new transactions to the main journal file -(which should be in journal format). Existing transactions are not -changed. This is one of the few hledger commands that writes to the -journal file (see also 'add'). - - Unlike other hledger commands, with 'import' the journal file is an -output file, and will be modified, though only by appending (existing -data will not be changed). The input files are specified as arguments, -so to import one or more CSV files to your main journal, you will run -'hledger import bank.csv' or perhaps 'hledger import *.csv'. - - Note you can import from any file format, though CSV files are the -most common import source, and these docs focus on that case. - -* Menu: - -* Deduplication:: -* Import testing:: -* Importing balance assignments:: -* Commodity display styles:: - - -File: hledger.info, Node: Deduplication, Next: Import testing, Up: import - -24.19.1 Deduplication ---------------------- - -'import' does _time-based deduplication_, to detect only the new -transactions since the last successful import. (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 downloaded data, which may overlap with -previous downloads. Eg if every week (or every day) you download a -bank's last three months of CSV data, you can safely run 'hledger import -thebank.csv' each time and only new transactions will be imported. - - 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.FILE" file in FILE's directory (after a -succesful import). - - 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. - - Related: CSV > Working with CSV > Deduplicating, importing. - - -File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import - -24.19.2 Import testing ----------------------- - -With '--dry-run', the transactions that will be imported are printed to -the terminal, without updating your journal or state files. The output -is valid journal format, like the print command, so you can re-parse it. -Eg, to see any importable transactions which CSV rules have not -categorised: - -$ hledger import --dry bank.csv | hledger -f- -I print unknown - - or (live updating): - -$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' - - Note: when importing from multiple files at once, it's currently -possible for some .latest files to be updated successfully, while the -actual import fails because of a problem in one of the files, leaving -them out of sync (and causing some transactions to be missed). To -prevent this, do a -dry-run first and fix any problems before the real -import. - - -File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import - -24.19.3 Importing balance assignments -------------------------------------- - -Entries added by import will have their posting amounts made explicit -(like 'hledger print -x'). This means that any balance assignments in -imported files must be evaluated; but, imported files don't get to see -the main file's account balances. As a result, importing entries with -balance assignments (eg from an institution that provides only balances -and not posting amounts) will probably generate incorrect posting -amounts. To avoid this problem, use print instead of import: - -$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - - (If you think import should leave amounts implicit like print does, -please test it and send a pull request.) - - -File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import - -24.19.4 Commodity display styles --------------------------------- - -Imported amounts will be formatted according to the canonical commodity -styles (declared or inferred) in the main journal file. - - -File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS - -24.20 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', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS - -24.21 notes -=========== - -List the unique notes that appear in transactions. - - This command lists the unique notes that appear in transactions, in -alphabetic order. You can add a query to select a subset of -transactions. The note is the part of the transaction description after -a | character (or if there is no |, the whole description). - - Example: - -$ hledger notes -Petrol -Snacks - - -File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS - -24.22 payees -============ - -List the unique payee/payer names that appear in transactions. - - This command lists unique payee/payer names which have been declared -with payee directives (-declared), used in transaction descriptions -(-used), or both (the default). - - The payee/payer is the part of the transaction description before a | -character (or if there is no |, the whole description). - - You can add query arguments to select a subset of transactions. This -implies -used. - - Example: - -$ hledger payees -Store Name -Gas Station -Person A - - -File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS - -24.23 prices -============ - -Print the market prices declared with P directives. With --infer-market-prices, also show any additional prices inferred from -costs. With -show-reverse, also show additional prices inferred by -reversing known prices. - - Price amounts are always displayed with their full precision, except -for reverse prices which are limited to 8 decimal digits. - - Prices can be filtered by a date:, cur: or amt: query. - - Generally if you run this command with -infer-market-prices --show-reverse, it will show the same prices used internally to calculate -value reports. But if in doubt, you can inspect those directly by -running the value report with -debug=2. - - -File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS - -24.24 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). - - 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/regenerate your journal you should take care to also copy -over the directives and inter-transaction comments. - - Eg: - -$ hledger print -f examples/sample.journal date:200806 -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 - -* Menu: - -* print explicitness:: -* print amount style:: -* print parseability:: -* print other features:: -* print output format:: - - -File: hledger.info, Node: print explicitness, Next: print amount style, Up: print - -24.24.1 print explicitness --------------------------- - -Normally, whether posting amounts are implicit or explicit is preserved. -For example, when an amount is omitted in the journal, it will not -appear in the output. Similarly, if a conversion cost is implied but -not written, it will not appear in the output. - - You can use the '-x'/'--explicit' flag to force explicit display of -all amounts and costs. This 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'. - - The '-x'/'--explicit' flag will cause any postings with a -multi-commodity amount (which can arise when a multi-commodity -transaction has an implicit amount) to be split into multiple -single-commodity postings, keeping the output parseable. - - -File: hledger.info, Node: print amount style, Next: print parseability, Prev: print explicitness, Up: print - -24.24.2 print amount style --------------------------- - -Amounts are shown right-aligned within each transaction (but not aligned -across all transactions; you can do that with ledger-mode in Emacs). - - Amounts will be (mostly) normalised to their commodity display style: -their symbol placement, decimal mark, and digit group marks will be made -consistent. By default, decimal digits are shown as they are written in -the journal. - - With the '--round' option, 'print' will try increasingly hard to -display decimal digits according to the commodity display styles: - - * '--round=none' show amounts with original precisions (default) - * '--round=soft' add/remove decimal zeros in amounts (except costs) - * '--round=hard' round amounts (except costs), possibly hiding - significant digits - * '--round=all' round all amounts and costs - - 'soft' is good for non-lossy cleanup, formatting amounts more -consistently where it's safe to do so. - - 'hard' and 'all' can cause 'print' to show invalid unbalanced journal -entries; they may be useful eg for stronger cleanup, with manual fixups -when needed. - - -File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print - -24.24.3 print parseability --------------------------- - -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 (though the same can be achieved with 'expr:' queries -now): - -# 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: - - * Value reporting 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. - - -File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print - -24.24.4 print, other features ------------------------------ - -With '-B'/'--cost', amounts with costs are shown converted to cost. - - With '--new', print shows 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.) - - With '-m DESC'/'--match=DESC', print shows one recent transaction -whose description is most similar to DESC. DESC should contain at least -two characters. If there is no similar-enough match, no transaction -will be shown and the program exit code will be non-zero. - - -File: hledger.info, Node: print output format, Prev: print other features, Up: print - -24.24.5 print output format ---------------------------- - -This command also supports the output destination and output format -options The output formats supported are 'txt', 'beancount', 'csv', -'tsv', 'json' and 'sql'. - - _Experimental:_ The 'beancount' format tries to produce -Beancount-compatible output, as follows: - - * Transaction and postings with unmarked status are converted to - cleared ('*') status. - * Transactions' payee and note are backslash-escaped and - double-quote-escaped and wrapped in double quotes. - * Transaction tags are copied to Beancount #tag format. - * Commodity symbols are converted to upper case, and a small number - of currency symbols like '$' are converted to the corresponding - currency names. - * Account name parts are capitalised and unsupported characters are - replaced with '-'. If an account name part does not begin with a - letter, or if the first part is not Assets, Liabilities, Equity, - Income, or Expenses, an error is raised. (Use '--alias' options to - bring your accounts into compliance.) - * An 'open' directive is generated for each account used, on the - earliest transaction date. - - Some limitations: - - * Balance assertions are removed. - * Balance assignments become missing amounts. - * Virtual and balanced virtual postings become regular postings. - * Directives are not converted. - - Here's an example of print's CSV output: - -$ hledger print -Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" -"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" -"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - * There is one CSV record per posting, with the parent transaction's - fields repeated. - * The "txnidx" (transaction index) field shows which postings belong - to the same transaction. (This number might change if transactions - are reordered within the file, files are parsed/included in a - different order, etc.) - * The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - * The numeric amount is repeated in either the "credit" or "debit" - column, for convenience. (Those names are not accurate in the - accounting sense; it just puts negative amounts under credit and - zero or greater amounts under debit.) - - -File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS - -24.25 register -============== - -(reg) - - Show postings and their running total. - - The register command displays matched postings, across all accounts, -in date order, with their running total or running historical balance. -(See also the 'aregister' command, which shows matched transactions in a -specific account.) - - register normally shows line per posting, but note that -multi-commodity amounts will occupy multiple lines (one line per -commodity). - - It is typically used with a query selecting a particular account, to -see that account's activity: - -$ hledger register checking -2008/01/01 income assets:bank:checking $1 $1 -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 - - With '--date2', it shows and sorts by secondary date instead. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -'--align-all' flag. - - The '--historical'/'-H' flag adds the balance from any undisplayed -prior postings to the running total. This is useful when you want to -see only recent activity, with a historically accurate running balance: - -$ hledger register checking -b 2008/6 --historical -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 - - The '--depth' option limits the amount of sub-account detail -displayed. - - The '--average'/'-A' flag shows the running average posting amount -instead of the running total (so, the final number displayed is the -average for the whole report period). This flag implies '--empty' (see -below). It is affected by '--historical'. It works best when showing -just one account and one commodity. - - The '--related'/'-r' flag shows the _other_ postings in the -transactions of the postings which would normally be shown. - - The '--invert' flag negates all amounts. For example, it can be used -on an income account where amounts are normally displayed as negative -numbers. It's also useful to show postings on the checking account -together with the related account: - -$ hledger register --related --invert assets:checking - - With a reporting interval, register shows summary postings, one per -interval, aggregating the postings to each account: - -$ hledger register --monthly income -2008/01 income:salary $-1 $-1 -2008/06 income:gifts $-1 $-2 - - Periods with no activity, and summary postings with a zero amount, -are not shown by default; use the '--empty'/'-E' flag to see them: - -$ hledger register --monthly income -E -2008/01 income:salary $-1 $-1 -2008/02 0 $-1 -2008/03 0 $-1 -2008/04 0 $-1 -2008/05 0 $-1 -2008/06 income:gifts $-1 $-2 -2008/07 0 $-2 -2008/08 0 $-2 -2008/09 0 $-2 -2008/10 0 $-2 -2008/11 0 $-2 -2008/12 0 $-2 - - Often, you'll want to see just one line per interval. The '--depth' -option helps with this, causing subaccounts to be aggregated: - -$ hledger register --monthly assets --depth 1h -2008/01 assets $1 $1 -2008/06 assets $-1 0 -2008/12 assets $-1 $-1 - - Note when using report intervals, if you specify start/end dates -these will be adjusted outward if necessary to contain a whole number of -intervals. This ensures that the first and last intervals are full -length and comparable to the others in the report. - - With '-m DESC'/'--match=DESC', register does a fuzzy search for one -recent posting whose description is most similar to DESC. DESC should -contain at least two characters. If there is no similar-enough match, -no posting will be shown and the program exit code will be non-zero. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -24.25.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', 'tsv', and -(experimental) 'json'. - - -File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS - -24.26 rewrite -============= - -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - - This is a start at a generic rewriter of transaction entries. It -reads the default journal and prints the transactions, like print, but -adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing -transaction's first posting amount. - - Examples: - -$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -$ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the -two spaces between account and amount. - - More: - -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for '--add-posting' option is a usual posting of transaction -with an exception for amount specification. More precisely, you can use -''*'' (star symbol) before the amount to indicate that that this is a -factor for an amount of original matched posting. If the amount -includes a commodity name, the new posting amount will be in the new -commodity; otherwise, it will be in the matched posting amount's -commodity. - -* Menu: - -* Re-write rules in a file:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -24.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 - -24.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 - -24.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: PART 4 COMMANDS - -24.27 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, also known as money-weighted rate of return) and time-weighted -rate of return (TWR) for your investments for the time period requested. -IRR is always annualized due to the way it is computed, but TWR is -reported both as a rate over the chosen reporting period and as an -annual rate. - - Price directives will be taken into account if you supply appropriate -'--cost' or '--value' flags (see VALUATION). - - Note, in some cases this report can fail, for these reasons: - - * Error (NotBracketed): No solution for Internal Rate of Return - (IRR). Possible causes: IRR is huge (>1000000%), balance of - investment becomes negative at some point in time. - * Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or - converges too slowly. - - Examples: - - * Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger - - * Cookbook > Return on Investment: https://hledger.org/roi.html - -* Menu: - -* Spaces and special characters in --inv and --pnl:: -* Semantics of --inv and --pnl:: -* IRR and TWR explained:: - - -File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi - -24.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 - -24.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 - -24.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, and -the time between them. Investment at a particular fixed interest rate -is going to give you more interest than the same amount invested at the -same interest rate, but made later in time. 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, -so your IRR will be smaller. And if you are adding to your investment, -you will receive bigger absolute gains, which will be a bigger -percentage of your initial investment, so your IRR will be larger. - - 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 -account for the effect of your in-flows and out-flows, but unlike IRR it -will try to compute the true rate of return of the underlying asset, -compensating for the effect that deposits and withdrawas have on the -apparent rate of growth of your investment. - - 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, and make TWR less sensitive than IRR to the effects of -cash in-flows and out-flows. - - References: - - * Explanation of rate of return - * Explanation of IRR - * Explanation of TWR - * IRR vs TWR - * Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS - -24.28 stats -=========== - -Show journal and performance statistics. - - The stats command displays summary information for the whole journal, -or a matched part of it. With a reporting interval, it shows a report -for each report period. - - At the end, it shows (in the terminal) the overall run time and -number of transactions processed per second. Note these are approximate -and will vary based on machine, current load, data size, hledger -version, haskell lib versions, GHC version.. but they may be of -interest. The 'stats' command's run time is similar to that of a -single-column balance report. - - Example: - -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s - - This command supports the -o/-output-file option (but not --O/-output-format selection). - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS - -24.29 tags -========== - -List the tags used in the journal, or their values. - - This command lists the tag names used in the journal, whether on -transactions, postings, or account declarations. - - With a TAGREGEX argument, only tag names matching this regular -expression (case insensitive, infix matched) are shown. - - With QUERY arguments, only transactions and accounts matching this -query are considered. If the query involves transaction fields (date:, -desc:, amt:, ...), the search is restricted to the matched transactions -and their accounts. - - With the -values flag, the tags' unique non-empty values are listed -instead. With -E/-empty, blank/empty values are also shown. - - With -parsed, tags or values are shown in the order they were parsed, -with duplicates included. (Except, tags from account declarations are -always shown first.) - - Tip: remember, accounts also acquire tags from their parents, -postings also acquire tags from their account and transaction, -transactions also acquire tags from their postings. - - -File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS - -24.30 test -========== - -Run built-in unit tests. - - This command runs the unit tests built in to hledger and hledger-lib, -printing the results on stdout. If any test fails, the exit code will -be non-zero. - - This is mainly used by hledger developers, but you can also use it to -sanity-check the installed hledger executable on your platform. All -tests are expected to pass - if you ever see a failure, please report as -a bug! - - This command also accepts tasty test runner options, written after a -- (double hyphen). Eg to run only the tests in Hledger.Data.Amount, -with ANSI colour codes disabled: - -$ hledger test -- -pData.Amount --color=never - - For help on these, see https://github.com/feuerbach/tasty#options -('-- --help' currently doesn't show them). - - -File: hledger.info, Node: PART 5 COMMON TASKS, Next: BUGS, Prev: PART 4 COMMANDS, Up: Top - -25 PART 5: COMMON TASKS -*********************** - -Here are some quick examples of how to do some basic tasks with hledger. - -* Menu: - -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting LEDGER_FILE:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: - - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS - -25.1 Getting help -================= - -Here's how to list commands and view options and command docs: - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version's manual in several formats by -using the help command. Eg: - -$ hledger help # show the hledger manual with info, man or $PAGER (best available) -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit -https://hledger.org. Chat and mail list support and discussion archives -can be found at https://hledger.org/support. - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS - -25.2 Constructing command lines -=============================== - -hledger has a flexible command line interface. We strive to keep it -simple and ergonomic, but if you run into one of the sharp edges -described in OPTIONS, here are some tips that might help: - - * command-specific options must go after the command (it's fine to - put common options there too: 'hledger CMD OPTS ARGS') - * running add-on executables directly simplifies command line parsing - ('hledger-ui OPTS ARGS') - * enclose "problematic" args in single quotes - * if needed, also add a backslash to hide regular expression - metacharacters from the shell - * to see how a misbehaving command line is being parsed, add - '--debug=2'. - - -File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: PART 5 COMMON TASKS - -25.3 Starting a journal file -============================ - -hledger looks for your accounting data in a journal file, -'$HOME/.hledger.journal' by default: - -$ hledger stats -The hledger journal file "/Users/simon/.hledger.journal" was not found. -Please create it first, eg with "hledger add" or a text editor. -Or, specify an existing journal file with -f or LEDGER_FILE. - - You can override this by setting the 'LEDGER_FILE' environment -variable (see below). 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 2023.journal -$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile -$ source ~/.profile -$ hledger stats -Main file : /Users/simon/finance/2023.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 LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: PART 5 COMMON TASKS - -25.4 Setting LEDGER_FILE -======================== - -How to set 'LEDGER_FILE' permanently depends on your setup: - - On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: - -$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile -$ source ~/.profile - - When correctly configured, in a new terminal window 'env | grep -LEDGER_FILE' will show your file, and so will 'hledger files'. - - On mac, this additional step might be helpful for GUI applications -(like Emacs started from the dock): add an entry to -'~/.MacOSX/environment.plist' like - -{ - "LEDGER_FILE" : "~/finance/2023.journal" -} - - and then run 'killall Dock' in a terminal window (or restart the -machine). - - On Windows, see https://www.java.com/en/download/help/path.html, or -try running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): - -> CD -> MKDIR finance -> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: PART 5 COMMON TASKS - -25.5 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: - - 2023-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/2023.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 [2023-02-07]: 2023-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): . - 2023-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 [2023-01-01]: . - - If you're using version control, this could be a good time to commit -the journal. Eg: - -$ git commit -m 'initial balances' 2023.journal - - -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS - -25.6 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: - -2023/1/10 * gift received - assets:cash $20 - income:gifts - -2023.1.12 * farmers market - expenses:food $13 - assets:cash - -2023-01-15 paycheck - income:salary - assets:bank:checking $1000 - - -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS - -25.7 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: - - 2023-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 '2023-01-15' and 'paycheck' - - If you're using version control, this can be another good time to -commit: - -$ git commit -m 'txns' 2023.journal - - -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS - -25.8 Reporting -============== - -Here are some basic reports. - - Show all transactions: - -$ hledger print -2023-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -2023-01-10 * gift received - assets:cash $20 - income:gifts - -2023-01-12 * farmers market - expenses:food $13 - assets:cash - -2023-01-15 * paycheck - income:salary - assets:bank:checking $1000 - -2023-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - -$ hledger accounts --tree -assets - bank - checking - savings - cash -equity - opening/closing balances -expenses - food - misc -income - gifts - salary -liabilities - creditcard - - Show all account totals: - -$ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard --------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to -depth 2: - -$ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard --------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple -balance sheet: - -$ hledger bs -2 -Balance Sheet 2023-01-16 - - || 2023-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 2023-01-01-2023-01-16 - - || 2023-01-01-2023-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 -2023-01-01 opening balances assets:cash $100 $100 -2023-01-10 gift received assets:cash $20 $120 -2023-01-12 farmers market assets:cash $-13 $107 -2023-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - -$ hledger activity -W -2019-12-30 ***** -2023-01-06 **** -2023-01-13 **** - - -File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS - -25.9 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: BUGS, Prev: PART 5 COMMON TASKS, Up: Top - -26 BUGS -******* - -We welcome bug reports in the hledger issue tracker (shortcut: -http://bugs.hledger.org), or on the #hledger chat or hledger mail list -(https://hledger.org/support). - - Some known issues and limitations: - - The need to precede add-on command options with '--' when invoked -from hledger is awkward. (See Command options, Constructing command -lines.) - - A UTF-8-aware system locale must be configured to work with non-ascii -data. (See Unicode characters, Troubleshooting.) - - On Microsoft Windows, depending whether you are running in a CMD -window or a Cygwin/MSYS/Mintty window and how you installed hledger, -non-ascii characters and colours may not be supported, and the tab key -may not be supported by 'hledger add'. (Running in a WSL window should -resolve these.) - - When processing large data files, hledger uses more memory than -Ledger. - -* Menu: - -* Troubleshooting:: - - -File: hledger.info, Node: Troubleshooting, Up: BUGS - -26.1 Troubleshooting -==================== - -Here are some common issues you might encounter when you run hledger, -and how to resolve them (and remember also you can usually get quick -Support): - - *PATH issues: I get an error like "No command 'hledger' found"* -Depending how you installed hledger, the executables may not be in your -shell's PATH. Eg on unix systems, stack installs hledger in -'~/.local/bin' and cabal installs it in '~/.cabal/bin'. You may need to -add one of these directories to your shell's PATH, and/or open a new -terminal window. - - *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not -using it* - - * 'LEDGER_FILE' should be a real environment variable, not just a - shell variable. Eg on unix, the command 'env | grep LEDGER_FILE' - should show it. You may need to use 'export' (see - https://stackoverflow.com/a/7411509). - * You may need to force your shell to see the new configuration. A - simple way is to close your terminal window and open a new one. - - *LANG issues: I get 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 -the system locale to be UTF-8-aware, or they will fail when they -encounter non-ascii characters. To fix it, set the LANG environment -variable to a locale which supports UTF-8 and which is installed on your -system. - - On unix, 'locale -a' lists the installed locales. Look for one which -mentions 'utf8', 'UTF-8' or similar. Some examples: 'C.UTF-8', -'en_US.utf-8', 'fr_FR.utf8'. If necessary, use your system package -manager to install one. Then select it by setting the 'LANG' -environment variable. Note, exact spelling and capitalisation of the -locale name may be important: Here's one common way to configure this -permanently for your shell: - -$ echo "export LANG=en_US.utf8" >>~/.profile -# close and re-open terminal window - - If you are using Nix (not NixOS) for GHC and Hledger, you might need -to set the 'LOCALE_ARCHIVE' variable: - -$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile -# close and re-open terminal window - - *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file* -Not all of Ledger's journal file syntax or feature set is supported. -See hledger and Ledger for full details. - - -Tag Table: -Node: Top210 -Node: PART 1 USER INTERFACE3820 -Ref: #part-1-user-interface3959 -Node: Input3959 -Ref: #input4069 -Node: Data formats5018 -Ref: #data-formats5131 -Node: Standard input6493 -Ref: #standard-input6633 -Node: Multiple files6860 -Ref: #multiple-files6999 -Node: Strict mode7597 -Ref: #strict-mode7707 -Node: Commands8431 -Ref: #commands8533 -Node: Add-on commands9600 -Ref: #add-on-commands9702 -Node: Options10818 -Ref: #options10930 -Node: General help options11258 -Ref: #general-help-options11404 -Node: General input options11686 -Ref: #general-input-options11868 -Node: General reporting options12570 -Ref: #general-reporting-options12731 -Node: Command line tips16121 -Ref: #command-line-tips16251 -Node: Option repetition16510 -Ref: #option-repetition16654 -Node: Special characters16758 -Ref: #special-characters16931 -Node: Single escaping shell metacharacters17094 -Ref: #single-escaping-shell-metacharacters17335 -Node: Double escaping regular expression metacharacters17938 -Ref: #double-escaping-regular-expression-metacharacters18249 -Node: Triple escaping for add-on commands18775 -Ref: #triple-escaping-for-add-on-commands19035 -Node: Less escaping19679 -Ref: #less-escaping19833 -Node: Unicode characters20157 -Ref: #unicode-characters20332 -Node: Regular expressions21744 -Ref: #regular-expressions21917 -Node: hledger's regular expressions25013 -Ref: #hledgers-regular-expressions25172 -Node: Argument files26558 -Ref: #argument-files26694 -Node: Output27191 -Ref: #output27303 -Node: Output destination27430 -Ref: #output-destination27561 -Node: Output format27986 -Ref: #output-format28132 -Node: CSV output29729 -Ref: #csv-output29845 -Node: HTML output29948 -Ref: #html-output30086 -Node: JSON output30180 -Ref: #json-output30318 -Node: SQL output31240 -Ref: #sql-output31356 -Node: Commodity styles32091 -Ref: #commodity-styles32231 -Node: Colour32830 -Ref: #colour32948 -Node: Box-drawing33352 -Ref: #box-drawing33470 -Node: Paging33760 -Ref: #paging33874 -Node: Debug output34827 -Ref: #debug-output34933 -Node: Environment35596 -Ref: #environment35720 -Node: PART 2 DATA FORMATS36264 -Ref: #part-2-data-formats36407 -Node: Journal36407 -Ref: #journal36516 -Node: Journal cheatsheet37173 -Ref: #journal-cheatsheet37312 -Node: About journal format41297 -Ref: #about-journal-format41457 -Node: Comments43073 -Ref: #comments43203 -Node: Transactions44019 -Ref: #transactions44142 -Node: Dates45156 -Ref: #dates45263 -Node: Simple dates45308 -Ref: #simple-dates45424 -Node: Posting dates45924 -Ref: #posting-dates46042 -Node: Status47011 -Ref: #status47112 -Node: Code48820 -Ref: #code48923 -Node: Description49155 -Ref: #description49286 -Node: Payee and note49606 -Ref: #payee-and-note49712 -Node: Transaction comments50047 -Ref: #transaction-comments50200 -Node: Postings50563 -Ref: #postings50696 -Node: Account names51691 -Ref: #account-names51821 -Node: Amounts53495 -Ref: #amounts53610 -Node: Decimal marks digit group marks54595 -Ref: #decimal-marks-digit-group-marks54770 -Node: Commodity55629 -Ref: #commodity55816 -Node: Directives influencing number parsing and display56768 -Ref: #directives-influencing-number-parsing-and-display57027 -Node: Commodity display style57479 -Ref: #commodity-display-style57685 -Node: Rounding59095 -Ref: #rounding59213 -Node: Costs59663 -Ref: #costs59779 -Node: Other cost/lot notations61975 -Ref: #other-costlot-notations62107 -Node: Balance assertions64696 -Ref: #balance-assertions64847 -Node: Assertions and ordering65930 -Ref: #assertions-and-ordering66119 -Node: Assertions and multiple included files66819 -Ref: #assertions-and-multiple-included-files67079 -Node: Assertions and multiple -f files67579 -Ref: #assertions-and-multiple--f-files67830 -Node: Assertions and commodities68227 -Ref: #assertions-and-commodities68449 -Node: Assertions and prices69629 -Ref: #assertions-and-prices69835 -Node: Assertions and subaccounts70262 -Ref: #assertions-and-subaccounts70483 -Node: Assertions and virtual postings70807 -Ref: #assertions-and-virtual-postings71045 -Node: Assertions and auto postings71177 -Ref: #assertions-and-auto-postings71407 -Node: Assertions and precision72052 -Ref: #assertions-and-precision72234 -Node: Posting comments72501 -Ref: #posting-comments72647 -Node: Tags73024 -Ref: #tags73138 -Node: Tag values74331 -Ref: #tag-values74420 -Node: Directives75179 -Ref: #directives75306 -Node: Directives and multiple files76636 -Ref: #directives-and-multiple-files76814 -Node: Directive effects77581 -Ref: #directive-effects77735 -Node: account directive80748 -Ref: #account-directive80904 -Node: Account comments82302 -Ref: #account-comments82452 -Node: Account subdirectives82960 -Ref: #account-subdirectives83151 -Node: Account error checking83293 -Ref: #account-error-checking83491 -Node: Account display order84680 -Ref: #account-display-order84868 -Node: Account types85969 -Ref: #account-types86110 -Node: alias directive89737 -Ref: #alias-directive89898 -Node: Basic aliases90948 -Ref: #basic-aliases91079 -Node: Regex aliases91823 -Ref: #regex-aliases91980 -Node: Combining aliases92870 -Ref: #combining-aliases93048 -Node: Aliases and multiple files94324 -Ref: #aliases-and-multiple-files94528 -Node: end aliases directive95107 -Ref: #end-aliases-directive95326 -Node: Aliases can generate bad account names95475 -Ref: #aliases-can-generate-bad-account-names95723 -Node: Aliases and account types96308 -Ref: #aliases-and-account-types96500 -Node: commodity directive97196 -Ref: #commodity-directive97370 -Node: Commodity directive syntax98555 -Ref: #commodity-directive-syntax98740 -Node: Commodity error checking100119 -Ref: #commodity-error-checking100300 -Node: decimal-mark directive100594 -Ref: #decimal-mark-directive100776 -Node: include directive101173 -Ref: #include-directive101337 -Node: P directive102249 -Ref: #p-directive102394 -Node: payee directive103283 -Ref: #payee-directive103432 -Node: tag directive103748 -Ref: #tag-directive103903 -Node: Periodic transactions104371 -Ref: #periodic-transactions104536 -Node: Periodic rule syntax106242 -Ref: #periodic-rule-syntax106420 -Node: Periodic rules and relative dates107065 -Ref: #periodic-rules-and-relative-dates107331 -Node: Two spaces between period expression and description!107842 -Ref: #two-spaces-between-period-expression-and-description108119 -Node: Auto postings108803 -Ref: #auto-postings108951 -Node: Auto postings and multiple files111388 -Ref: #auto-postings-and-multiple-files111552 -Node: Auto postings and dates111953 -Ref: #auto-postings-and-dates112201 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions112376 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112732 -Node: Auto posting tags113235 -Ref: #auto-posting-tags113517 -Node: Auto postings on forecast transactions only114153 -Ref: #auto-postings-on-forecast-transactions-only114399 -Node: Other syntax114646 -Ref: #other-syntax114762 -Node: Balance assignments115389 -Ref: #balance-assignments115545 -Node: Balance assignments and prices116918 -Ref: #balance-assignments-and-prices117133 -Node: Balance assignments and multiple files117344 -Ref: #balance-assignments-and-multiple-files117575 -Node: Bracketed posting dates117768 -Ref: #bracketed-posting-dates117952 -Node: D directive118466 -Ref: #d-directive118634 -Node: apply account directive120234 -Ref: #apply-account-directive120414 -Node: Y directive121101 -Ref: #y-directive121261 -Node: Secondary dates122089 -Ref: #secondary-dates122243 -Node: Star comments123057 -Ref: #star-comments123217 -Node: Valuation expressions123749 -Ref: #valuation-expressions123926 -Node: Virtual postings124048 -Ref: #virtual-postings124225 -Node: Other Ledger directives125662 -Ref: #other-ledger-directives125825 -Node: CSV126391 -Ref: #csv126484 -Node: CSV rules cheatsheet128564 -Ref: #csv-rules-cheatsheet128693 -Node: source130491 -Ref: #source130614 -Node: separator131494 -Ref: #separator131607 -Node: skip132147 -Ref: #skip132255 -Node: date-format132799 -Ref: #date-format132920 -Node: timezone133644 -Ref: #timezone133767 -Node: newest-first134772 -Ref: #newest-first134910 -Node: intra-day-reversed135487 -Ref: #intra-day-reversed135641 -Node: decimal-mark136089 -Ref: #decimal-mark136230 -Node: fields list136569 -Ref: #fields-list136708 -Node: Field assignment138379 -Ref: #field-assignment138523 -Node: Field names139600 -Ref: #field-names139731 -Node: date field140934 -Ref: #date-field141052 -Node: date2 field141100 -Ref: #date2-field141241 -Node: status field141297 -Ref: #status-field141440 -Node: code field141489 -Ref: #code-field141634 -Node: description field141679 -Ref: #description-field141839 -Node: comment field141898 -Ref: #comment-field142053 -Node: account field142346 -Ref: #account-field142496 -Node: amount field143066 -Ref: #amount-field143215 -Node: currency field145907 -Ref: #currency-field146060 -Node: balance field146317 -Ref: #balance-field146449 -Node: if block146821 -Ref: #if-block146942 -Node: Matchers148350 -Ref: #matchers148464 -Node: Match groups150048 -Ref: #match-groups150149 -Node: if table150896 -Ref: #if-table151018 -Node: balance-type152580 -Ref: #balance-type152709 -Node: include153409 -Ref: #include153536 -Node: Working with CSV153980 -Ref: #working-with-csv154127 -Node: Rapid feedback154534 -Ref: #rapid-feedback154667 -Node: Valid CSV155119 -Ref: #valid-csv155265 -Node: File Extension155997 -Ref: #file-extension156170 -Node: Reading CSV from standard input156734 -Ref: #reading-csv-from-standard-input156958 -Node: Reading multiple CSV files157122 -Ref: #reading-multiple-csv-files157353 -Node: Reading files specified by rule157594 -Ref: #reading-files-specified-by-rule157822 -Node: Valid transactions158993 -Ref: #valid-transactions159192 -Node: Deduplicating importing159820 -Ref: #deduplicating-importing160015 -Node: Setting amounts161051 -Ref: #setting-amounts161222 -Node: Amount signs163580 -Ref: #amount-signs163750 -Node: Setting currency/commodity164647 -Ref: #setting-currencycommodity164851 -Node: Amount decimal places166025 -Ref: #amount-decimal-places166231 -Node: Referencing other fields166543 -Ref: #referencing-other-fields166756 -Node: How CSV rules are evaluated167653 -Ref: #how-csv-rules-are-evaluated167870 -Node: Well factored rules169323 -Ref: #well-factored-rules169491 -Node: CSV rules examples169815 -Ref: #csv-rules-examples169950 -Node: Bank of Ireland170015 -Ref: #bank-of-ireland170152 -Node: Coinbase171614 -Ref: #coinbase171752 -Node: Amazon172799 -Ref: #amazon172924 -Node: Paypal174643 -Ref: #paypal174751 -Node: Timeclock182395 -Ref: #timeclock182500 -Node: Timedot184678 -Ref: #timedot184801 -Node: Timedot examples187906 -Ref: #timedot-examples188012 -Node: PART 3 REPORTING CONCEPTS190183 -Ref: #part-3-reporting-concepts190365 -Node: Amount formatting parseability190365 -Ref: #amount-formatting-parseability190562 -Node: Time periods192767 -Ref: #time-periods192906 -Node: Report start & end date193024 -Ref: #report-start-end-date193176 -Node: Smart dates194835 -Ref: #smart-dates194988 -Node: Report intervals196856 -Ref: #report-intervals197011 -Node: Date adjustment197429 -Ref: #date-adjustment197589 -Node: Period expressions198440 -Ref: #period-expressions198581 -Node: Period expressions with a report interval200345 -Ref: #period-expressions-with-a-report-interval200579 -Node: More complex report intervals200793 -Ref: #more-complex-report-intervals201038 -Node: Multiple weekday intervals202839 -Ref: #multiple-weekday-intervals203028 -Node: Depth203850 -Ref: #depth203952 -Node: Queries204248 -Ref: #queries204350 -Node: Query types205475 -Ref: #query-types205596 -Node: Combining query terms208932 -Ref: #combining-query-terms209109 -Node: Queries and command options210377 -Ref: #queries-and-command-options210576 -Node: Queries and valuation210825 -Ref: #queries-and-valuation211020 -Node: Querying with account aliases211249 -Ref: #querying-with-account-aliases211460 -Node: Querying with cost or value211590 -Ref: #querying-with-cost-or-value211767 -Node: Pivoting212068 -Ref: #pivoting212182 -Node: Generating data213959 -Ref: #generating-data214091 -Node: Forecasting215674 -Ref: #forecasting215799 -Node: --forecast216330 -Ref: #forecast216461 -Node: Inspecting forecast transactions217507 -Ref: #inspecting-forecast-transactions217709 -Node: Forecast reports218839 -Ref: #forecast-reports219012 -Node: Forecast tags219948 -Ref: #forecast-tags220108 -Node: Forecast period in detail220568 -Ref: #forecast-period-in-detail220762 -Node: Forecast troubleshooting221656 -Ref: #forecast-troubleshooting221824 -Node: Budgeting222727 -Ref: #budgeting222847 -Node: Cost reporting223284 -Ref: #cost-reporting223418 -Node: Recording costs224079 -Ref: #recording-costs224215 -Node: Reporting at cost225806 -Ref: #reporting-at-cost225981 -Node: Equity conversion postings226571 -Ref: #equity-conversion-postings226785 -Node: Inferring equity conversion postings229216 -Ref: #inferring-equity-conversion-postings229479 -Node: Combining costs and equity conversion postings230231 -Ref: #combining-costs-and-equity-conversion-postings230541 -Node: Requirements for detecting equity conversion postings231529 -Ref: #requirements-for-detecting-equity-conversion-postings231851 -Node: Infer cost and equity by default ?233051 -Ref: #infer-cost-and-equity-by-default233280 -Node: Value reporting233488 -Ref: #value-reporting233630 -Node: -V Value234404 -Ref: #v-value234536 -Node: -X Value in specified commodity234731 -Ref: #x-value-in-specified-commodity234932 -Node: Valuation date235081 -Ref: #valuation-date235258 -Node: Finding market price236041 -Ref: #finding-market-price236252 -Node: --infer-market-prices market prices from transactions237421 -Ref: #infer-market-prices-market-prices-from-transactions237703 -Node: Valuation commodity240465 -Ref: #valuation-commodity240684 -Node: Simple valuation examples241897 -Ref: #simple-valuation-examples242101 -Node: --value Flexible valuation242760 -Ref: #value-flexible-valuation242970 -Node: More valuation examples244614 -Ref: #more-valuation-examples244829 -Node: Interaction of valuation and queries246099 -Ref: #interaction-of-valuation-and-queries246346 -Node: Effect of valuation on reports246818 -Ref: #effect-of-valuation-on-reports247021 -Node: PART 4 COMMANDS254718 -Ref: #part-4-commands254867 -Node: Commands overview255246 -Ref: #commands-overview255380 -Node: DATA ENTRY255559 -Ref: #data-entry255683 -Node: DATA CREATION255882 -Ref: #data-creation256036 -Node: DATA MANAGEMENT256154 -Ref: #data-management256319 -Node: REPORTS FINANCIAL256440 -Ref: #reports-financial256615 -Node: REPORTS VERSATILE256920 -Ref: #reports-versatile257093 -Node: REPORTS BASIC257346 -Ref: #reports-basic257498 -Node: HELP258007 -Ref: #help258129 -Node: ADD-ONS258239 -Ref: #add-ons258345 -Node: accounts258924 -Ref: #accounts259057 -Node: activity260944 -Ref: #activity261063 -Node: add261437 -Ref: #add261547 -Node: aregister264358 -Ref: #aregister264479 -Node: aregister and posting dates267367 -Ref: #aregister-and-posting-dates267512 -Node: balance268268 -Ref: #balance268394 -Node: balance features269379 -Ref: #balance-features269519 -Node: Simple balance report271485 -Ref: #simple-balance-report271670 -Node: Balance report line format273295 -Ref: #balance-report-line-format273497 -Node: Filtered balance report275655 -Ref: #filtered-balance-report275847 -Node: List or tree mode276174 -Ref: #list-or-tree-mode276342 -Node: Depth limiting277687 -Ref: #depth-limiting277853 -Node: Dropping top-level accounts278454 -Ref: #dropping-top-level-accounts278654 -Node: Showing declared accounts278964 -Ref: #showing-declared-accounts279163 -Node: Sorting by amount279694 -Ref: #sorting-by-amount279861 -Node: Percentages280531 -Ref: #percentages280690 -Node: Multi-period balance report281238 -Ref: #multi-period-balance-report281438 -Node: Balance change end balance283713 -Ref: #balance-change-end-balance283922 -Node: Balance report types285350 -Ref: #balance-report-types285531 -Node: Calculation type286029 -Ref: #calculation-type286184 -Node: Accumulation type286733 -Ref: #accumulation-type286913 -Node: Valuation type287815 -Ref: #valuation-type288003 -Node: Combining balance report types289004 -Ref: #combining-balance-report-types289198 -Node: Budget report291036 -Ref: #budget-report291198 -Node: Budget report start date296852 -Ref: #budget-report-start-date297030 -Node: Budgets and subaccounts298362 -Ref: #budgets-and-subaccounts298569 -Node: Selecting budget goals302009 -Ref: #selecting-budget-goals302208 -Node: Budget vs forecast303243 -Ref: #budget-vs-forecast303402 -Node: Balance report layout305032 -Ref: #balance-report-layout305212 -Node: Useful balance reports313397 -Ref: #useful-balance-reports313557 -Node: balancesheet314642 -Ref: #balancesheet314787 -Node: balancesheetequity316114 -Ref: #balancesheetequity316272 -Node: cashflow317668 -Ref: #cashflow317799 -Node: check319234 -Ref: #check319348 -Node: Default checks320152 -Ref: #default-checks320278 -Node: Strict checks320775 -Ref: #strict-checks320920 -Node: Other checks321400 -Ref: #other-checks321542 -Node: Custom checks322075 -Ref: #custom-checks322232 -Node: More about specific checks322649 -Ref: #more-about-specific-checks322811 -Node: close323517 -Ref: #close323628 -Node: close and balance assertions327093 -Ref: #close-and-balance-assertions327271 -Node: Example retain earnings328422 -Ref: #example-retain-earnings328639 -Node: Example migrate balances to a new file329071 -Ref: #example-migrate-balances-to-a-new-file329336 -Node: Example excluding closing/opening transactions329912 -Ref: #example-excluding-closingopening-transactions330161 -Node: codes331379 -Ref: #codes331496 -Node: commodities332360 -Ref: #commodities332488 -Node: demo332558 -Ref: #demo332679 -Node: descriptions333595 -Ref: #descriptions333725 -Node: diff334016 -Ref: #diff334131 -Node: files335173 -Ref: #files335282 -Node: help335423 -Ref: #help-1335532 -Node: import336905 -Ref: #import337028 -Node: Deduplication338136 -Ref: #deduplication338261 -Node: Import testing340280 -Ref: #import-testing340445 -Node: Importing balance assignments341288 -Ref: #importing-balance-assignments341494 -Node: Commodity display styles342143 -Ref: #commodity-display-styles342316 -Node: incomestatement342445 -Ref: #incomestatement342587 -Node: notes343915 -Ref: #notes344037 -Node: payees344399 -Ref: #payees344514 -Node: prices345033 -Ref: #prices345148 -Node: print345801 -Ref: #print345916 -Node: print explicitness346892 -Ref: #print-explicitness347035 -Node: print amount style347814 -Ref: #print-amount-style347984 -Node: print parseability349036 -Ref: #print-parseability349208 -Node: print other features349957 -Ref: #print-other-features350136 -Node: print output format350657 -Ref: #print-output-format350805 -Node: register353924 -Ref: #register354046 -Node: Custom register output359077 -Ref: #custom-register-output359208 -Node: rewrite360552 -Ref: #rewrite360670 -Node: Re-write rules in a file362568 -Ref: #re-write-rules-in-a-file362731 -Node: Diff output format363880 -Ref: #diff-output-format364063 -Node: rewrite vs print --auto365155 -Ref: #rewrite-vs.-print---auto365315 -Node: roi365871 -Ref: #roi365978 -Node: Spaces and special characters in --inv and --pnl367790 -Ref: #spaces-and-special-characters-in---inv-and---pnl368030 -Node: Semantics of --inv and --pnl368518 -Ref: #semantics-of---inv-and---pnl368757 -Node: IRR and TWR explained370607 -Ref: #irr-and-twr-explained370767 -Node: stats374020 -Ref: #stats374128 -Node: tags375515 -Ref: #tags-1375622 -Node: test376631 -Ref: #test376724 -Node: PART 5 COMMON TASKS377466 -Ref: #part-5-common-tasks377612 -Node: Getting help377910 -Ref: #getting-help378051 -Node: Constructing command lines378811 -Ref: #constructing-command-lines379012 -Node: Starting a journal file379669 -Ref: #starting-a-journal-file379871 -Node: Setting LEDGER_FILE381073 -Ref: #setting-ledger_file381265 -Node: Setting opening balances382222 -Ref: #setting-opening-balances382423 -Node: Recording transactions385564 -Ref: #recording-transactions385753 -Node: Reconciling386309 -Ref: #reconciling386461 -Node: Reporting388718 -Ref: #reporting388867 -Node: Migrating to a new file392852 -Ref: #migrating-to-a-new-file393009 -Node: BUGS393308 -Ref: #bugs393398 -Node: Troubleshooting394277 -Ref: #troubleshooting394377 + This manual is for hledger's command line interface, version 1.32.1. +It also describes the common options, file formats and concepts used by +all hledger programs. It might accidentally teach you some +bookkeeping/accounting as well! You don't need to know everything in +here to use hledger productively, but when you have a question about +functionality, this doc should answer it. It is detailed, so do skip +ahead or skim when needed. You can read it on hledger.org, or as an +info manual or man page on your system. You can also get it from +hledger itself with +'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'. + + The main function of the hledger CLI is to read plain text files +describing financial transactions, crunch the numbers, and print a +useful report on the terminal (or save it as HTML, CSV, JSON or SQL). +Many reports are available, as subcommands. hledger will also detect +other 'hledger-*' executables as extra subcommands. + + hledger usually reads from (and appends to) a journal file specified +by the 'LEDGER_FILE' environment variable (defaulting to +'$HOME/.hledger.journal'); or you can specify files with '-f' options. +It can also read timeclock files, timedot files, or any CSV/SSV/TSV file +with a date field. + + Here is a small journal file describing one transaction: + +2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more +_accounts_: bank accounts, your wallet, revenue/expense categories, +people, etc. You can choose any account names you wish, using ':' to +indicate subaccounts. There must be at least two spaces between account +name and amount. Positive amounts are inflow to that account (_debit_), +negatives are outflow from it (_credit_). (Some reports show revenue, +liability and equity account balances as negative numbers as a result; +this is normal.) + + hledger's add command can help you add transactions, or you can +install other data entry UIs like hledger-web or hledger-iadd. For more +extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM ++ vim-ledger, or VS Code + hledger-vscode are some good choices (see +https://hledger.org/editors.html). + + To get started, run 'hledger add' and follow the prompts, or save +some entries like the above in '$HOME/.hledger.journal', then try +commands like: +'hledger print -x' +'hledger aregister assets' +'hledger balance' +'hledger balancesheet' +'hledger incomestatement'. +Run 'hledger' to list the commands. See also the "Starting a journal +file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +* Menu: + +* PART 1 USER INTERFACE:: +* Input:: +* Commands:: +* Options:: +* Command line tips:: +* Output:: +* Environment:: +* PART 2 DATA FORMATS:: +* Journal:: +* CSV:: +* Timeclock:: +* Timedot:: +* PART 3 REPORTING CONCEPTS:: +* Amount formatting parseability:: +* Time periods:: +* Depth:: +* Queries:: +* Pivoting:: +* Generating data:: +* Forecasting:: +* Budgeting:: +* Cost reporting:: +* Value reporting:: +* PART 4 COMMANDS:: +* PART 5 COMMON TASKS:: +* BUGS:: + + +File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: Top + +1 PART 1: USER INTERFACE +************************ + + +File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top + +2 Input +******* + +hledger reads one or more data files, each time you run it. You can +specify a file with '-f', like so + +$ hledger -f FILE print + + Files are most often in hledger's journal format, with the '.journal' +file extension ('.hledger' or '.j' also work); these files describe +transactions, like an accounting general journal. + + When no file is specified, hledger looks for '.hledger.journal' in +your home directory. + + But most people prefer to keep financial files in a dedicated folder, +perhaps with version control. Also, starting a new journal file each +year is common (it's not required, but helps keep things fast and +organised). So we usually configure a different journal file, by +setting the 'LEDGER_FILE' environment variable, to something like +'~/finance/2023.journal'. For more about how to do that on your system, +see Common tasks > Setting LEDGER_FILE. + +* Menu: + +* Data formats:: +* Standard input:: +* Multiple files:: +* Strict mode:: + + +File: hledger.info, Node: Data formats, Next: Standard input, Up: Input + +2.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 '.journal' '.j' '.hledger' + some Ledger journals, for '.ledger' + transactions +'timeclock' timeclock files, for precise '.timeclock' + time logging +'timedot' timedot files, for '.timedot' + approximate time logging +'csv' CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv' + values, for data import '.csv.rules' '.ssv.rules' + '.tsv.rules' + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions +shown above. If it can't recognise the file extension, it assumes +'journal' format. So for non-journal files, it's important to use a +recognised file extension, so as to either read successfully or to show +relevant error messages. + + You can also force a specific reader/format by prefixing the file +path with the format and a colon. Eg, to read a .dat file as csv +format: + +$ hledger -f csv:/some/csv-file.dat stats + + +File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input + +2.2 Standard input +================== + +The file name '-' means standard input: + +$ cat FILE | hledger -f- print + + If reading non-journal data in this way, you'll need to add a file +format prefix, like: + +$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- + + +File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input + +2.3 Multiple files +================== + +You can specify multiple '-f' options, to read multiple files as one big +journal. When doing this, note that certain features (described below) +will be affected: + + * Balance assertions will not see the effect of transactions in + previous files. (Usually this doesn't matter as each file will set + the corresponding opening balances.) + * Some directives will not affect previous or subsequent files. + + If needed, you can work around these by using a single parent file +which includes the others, or concatenating the files into one, eg: 'cat +a.journal b.journal | hledger -f- CMD'. + + +File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input + +2.4 Strict mode +=============== + +hledger checks input files for valid data. By default, the most +important errors are detected, while still accepting easy journal files +without a lot of declarations: + + * Are the input files parseable, with valid syntax ? + * Are all transactions balanced ? + * Do all balance assertions pass ? + + With the '-s'/'--strict' flag, additional checks are performed: + + * Are all accounts posted to, declared with an 'account' directive ? + (Account error checking) + * Are all commodities declared with a 'commodity' directive ? + (Commodity error checking) + * Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks - the ones +listed above and some more. + + +File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top + +3 Commands +********** + +hledger provides various subcommands for getting things done. Most of +these commands do not change the journal file; they just read it and +output a report. A few commands assist with adding data and file +management. + + To show the commands list, run 'hledger' with no arguments. The +commands are described in detail in PART 4: COMMANDS, below. + + To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', + + * CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + * CMDOPTS are command-specific options, if any. Command-specific + options must be written after the command name. Eg: 'hledger print + -x'. + + * CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit + the data in some way. Eg: 'hledger reg assets:checking'. + + To list a command's options, arguments, and documentation in the +terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. + +* Menu: + +* Add-on commands:: + + +File: hledger.info, Node: Add-on commands, Up: Commands + +3.1 Add-on commands +=================== + +In addition to the built-in commands, you can install _add-on commands_: +programs or scripts named "hledger-SOMETHING", which will also appear in +hledger's commands list. If you used the hledger-install script, you +will have several add-ons installed already. Some more can be found in +hledger's bin/ directory, documented at +https://hledger.org/scripts.html. + + More precisely, add-on commands are programs or scripts in your +shell's PATH, whose name starts with "hledger-" and ends with no +extension or a recognised extension (".bat", ".com", ".exe", ".hs", +".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), +and (on unix and mac) which has executable permission for the current +user. + + You can run add-on commands using hledger, much like built-in +commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'. But note +the double hyphen argument, required before add-on-specific options. +Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'. If this causes +difficulty, you can always run the add-on directly, without using +'hledger': 'hledger-ui --watch' or 'hledger-web --serve'. + + +File: hledger.info, Node: Options, Next: Command line tips, Prev: Commands, Up: Top + +4 Options +********* + +Run 'hledger -h' to see general command line help, and general options +which are common to most hledger commands. These options can be written +anywhere on the command line. They can be grouped into help, input, and +reporting options: + +* Menu: + +* General help options:: +* General input options:: +* General reporting options:: + + +File: hledger.info, Node: General help options, Next: General input options, Up: Options + +4.1 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) + + +File: hledger.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: Options + +4.2 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) + + +File: hledger.info, Node: General reporting options, Prev: General input options, Up: Options + +4.3 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-equity' + + infer conversion equity postings from costs +'--infer-costs' + + infer costs from conversion equity postings +'--infer-market-prices' + + use costs as additional market prices, as if they were P directives +'--forecast' + + generate transactions from periodic rules, between the latest + recorded txn and 6 months from today, or during the specified + PERIOD (= is required). Auto posting rules will be applied to + these transactions as well. Also, in hledger-ui make future-dated + transactions visible. +'--auto' + + generate extra postings by applying auto posting rules to all txns + (not just forecast txns) +'--verbose-tags' + + add visible tags indicating transactions or postings which have + been generated/modified +'--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 line tips, Next: Output, Prev: Options, Up: Top + +5 Command line tips +******************* + +Here are some details useful to know about for hledger command lines +(and elsewhere). Feel free to skip this section until you need it. + +* Menu: + +* Option repetition:: +* Special characters:: +* Unicode characters:: +* Regular expressions:: +* Argument files:: + + +File: hledger.info, Node: Option repetition, Next: Special characters, Up: Command line tips + +5.1 Option repetition +===================== + +If options are repeated in a command line, hledger will generally use +the last (right-most) occurence. + + +File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Option repetition, Up: Command line tips + +5.2 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 + +5.2.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 + +5.2.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 + +5.2.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 + +5.2.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: Command line tips + +5.3 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, Next: Argument files, Prev: Unicode characters, Up: Command line tips + +5.4 Regular expressions +======================= + +A regular expression (regexp) is a small piece of text where certain +characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have +special meanings, forming a tiny language for matching text precisely - +very useful in hledger and elsewhere. To learn all about them, visit +regular-expressions.info. + + hledger supports regexps whenever you are entering a pattern to match +something, eg in query arguments, account aliases, CSV if rules, +hledger-web's search form, hledger-ui's '/' search, etc. You may need +to wrap them in quotes, especially at the command line (see Special +characters above). Here are some examples: + + Account name queries (quoted for command line use): + +Regular expression: Matches: +------------------- ------------------------------------------------------------ +bank assets:bank, assets:bank:savings, expenses:art:banksy, ... +:bank assets:bank:savings, expenses:art:banksy +:bank: assets:bank:savings +'^bank' none of those ( ^ matches beginning of text ) +'bank$' assets:bank ( $ matches end of text ) +'big \$ bank' big $ bank ( \ disables following character's special meaning ) +'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) +'(sav|check)ing' saving or checking ( (|) matches either alternative ) +'saving|checking' saving or checking ( outer parentheses are not needed ) +'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) +'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) +'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) +'b.nk' bank, bonk, b nk, ... ( . matches any character ) + + Some other queries: + +desc:'amazon|amzn|audible' Amazon transactions +cur:EUR amounts with commodity symbol containing EUR +cur:'\$' amounts with commodity symbol containing $ +cur:'^\$$' only $ amounts, not eg AU$ or CA$ +cur:....? amounts with 4-or-more-character symbols +tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 + + Account name aliases: accept '.' instead of ':' as account separator: + +alias /\./=: replaces all periods in account names with colons + + Show multiple top-level accounts combined as one: + +--alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) + + Show accounts with the second-level part removed: + +--alias '/^([^:]+):[^:]+/ = \1' + match a top-level account and a second-level account + and replace those with just the top-level account + ( \1 in the replacement text means "whatever was matched + by the first parenthesised part of the regexp" + + CSV rules: match CSV records containing dining-related MCC codes: + +if \?MCC581[124] + + Match CSV records with a specific amount around the end/start of +month: + +if %amount \b3\.99 +& %date (29|30|31|01|02|03)$ + +* Menu: + +* hledger's regular expressions:: + + +File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions + +5.4.1 hledger's regular expressions +----------------------------------- + +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. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the + replacement string to reference capturing groups in the search + regexp. Otherwise, if you write '\1', it will match the digit '1'. + 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: Argument files, Prev: Regular expressions, Up: Command line tips + +5.5 Argument files +================== + +You can save a set of command line options and arguments in a file, and +then reuse them by writing '@FILENAME' as a command line argument. Eg: +'hledger bal @foo.args'. + + Inside the argument file, each line should contain just one option or +argument. Don't use spaces except inside quotes (or you'll see a +confusing error); write '=' (or nothing) between a flag and its +argument. For the special characters mentioned above, use one less +level of quoting than you would at the command prompt. + + +File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips, Up: Top + +6 Output +******** + +* Menu: + +* Output destination:: +* Output format:: +* Commodity styles:: +* Colour:: +* Box-drawing:: +* Paging:: +* Debug output:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: Output + +6.1 Output destination +====================== + +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: + +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the '-o/--output-file' option, which does the same thing without +needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) + + +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output + +6.2 Output format +================= + +Some commands offer other kinds of output, not just text on the +terminal. Here are those commands and the formats currently supported: + +- txt csv/tsv html json sql +------------------------------------------------------------------------------- +aregister Y Y Y Y +balance Y _1_ Y _1_ Y _1,2_ Y +balancesheet Y _1_ Y _1_ Y _1_ Y +balancesheetequityY _1_ Y _1_ Y _1_ Y +cashflow Y _1_ Y _1_ Y _1_ Y +incomestatement Y _1_ Y _1_ Y _1_ Y +print Y Y Y Y +register Y Y Y + + * _1 Also affected by the balance commands' '--layout' option._ + * _2 'balance' does not support html output without a report interval + or with '--budget'._ + + The output format is selected by the '-O/--output-format=FMT' option: + +$ hledger print -O csv # print CSV on stdout + + or by the filename extension of an output file specified with the +'-o/--output-file=FILE.FMT' option: + +$ hledger balancesheet -o foo.csv # write CSV to foo.csv + + The '-O' option can be combined with '-o' to override the file +extension, if needed: + +$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt + + Some notes about the various output formats: + +* Menu: + +* CSV output:: +* HTML output:: +* JSON output:: +* SQL output:: + + +File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format + +6.2.1 CSV output +---------------- + + * In CSV output, digit group marks (such as thousands separators) are + disabled automatically. + + +File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format + +6.2.2 HTML output +----------------- + + * HTML output can be styled by an optional 'hledger.css' file in the + same directory. + + +File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format + +6.2.3 JSON output +----------------- + + * This is not yet much used; real-world feedback is welcome. + + * Our JSON is rather large and verbose, since it is a faithful + representation of hledger's internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + + * hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction + prices), and would break most JSON consumers. So in JSON, we show + quantities as simple Numbers with at most 10 decimal places. We + don't limit the number of integer digits, but that part is under + your control. We hope this approach will not cause problems in + practice; if you find otherwise, please let us know. (Cf #1195) + + +File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format + +6.2.4 SQL output +---------------- + + * This is not yet much used; real-world feedback is welcome. + + * SQL output is expected to work at least with SQLite, MySQL and + Postgres. + + * For SQLite, it will be more useful if you modify the generated 'id' + field to be a PRIMARY KEY. Eg: + + $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... + + * SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables + created via SQL output of hledger, you would probably want to + either clear tables of existing data (via 'delete' or 'truncate' + SQL statements) or drop tables completely as otherwise your + postings will be duped. + + +File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output + +6.3 Commodity styles +==================== + +When displaying amounts, hledger infers a standard display style for +each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a '-c/--commodity-style' option +(except for cost amounts and amounts displayed by the 'print' command, +which are always displayed with all decimal digits). For example, the +following will force dollar amounts to be displayed as shown: + +$ hledger print -c '$1.000,0' + + This option can repeated to set the display style for multiple +commodities/currencies. Its argument is as described in the commodity +directive. + + +File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output + +6.4 Colour +========== + +In terminal output, some commands can produce colour when the terminal +supports it: + + * if the '--color/--colour' option is given a value of 'yes' or + 'always' (or 'no' or 'never'), colour will (or will not) be used; + * otherwise, if the 'NO_COLOR' environment variable is set, colour + will not be used; + * otherwise, colour will be used if the output (terminal or file) + supports it. + + +File: hledger.info, Node: Box-drawing, Next: Paging, Prev: Colour, Up: Output + +6.5 Box-drawing +=============== + +In terminal output, you can enable unicode box-drawing characters to +render prettier tables: + + * if the '--pretty' option is given a value of 'yes' or 'always' (or + 'no' or 'never'), unicode characters will (or will not) be used; + * otherwise, unicode characters will not be used. + + +File: hledger.info, Node: Paging, Next: Debug output, Prev: Box-drawing, Up: Output + +6.6 Paging +========== + +When showing long output in the terminal, hledger will try to use the +pager specified by the 'PAGER' environment variable, or 'less', or +'more'. (A pager is a helper program that shows one page at a time +rather than scrolling everything off screen). Currently it does this +only for help output, not for reports; specifically, + + * when listing commands, with 'hledger' + * when showing help with 'hledger [CMD] --help', + * when viewing manuals with 'hledger help' or 'hledger --man'. + + Note the pager is expected to handle ANSI codes, which hledger uses +eg for bold emphasis. For the common pager 'less' (and its 'more' +compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment +variables to make this work. If you use a different pager, you might +need to configure it similarly, to avoid seeing junk on screen (let us +know). Otherwise, you can set the 'NO_COLOR' environment variable to 1 +to disable all ANSI output (see Colour). + + +File: hledger.info, Node: Debug output, Prev: Paging, Up: Output + +6.7 Debug output +================ + +We intend hledger to be relatively easy to troubleshoot, introspect and +develop. You can add '--debug[=N]' to any hledger command line to see +additional debug output. N ranges from 1 (least output, the default) to +9 (maximum output). Typically you would start with 1 and increase until +you are seeing enough. Debug output goes to stderr, and is not affected +by '-o/--output-file' (unless you redirect stderr to stdout, eg: +'2>&1'). It will be interleaved with normal output, which can help +reveal when parts of the code are evaluated. To capture debug output in +a log file instead, you can usually redirect stderr, eg: + +hledger bal --debug=3 2>hledger.log + + +File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top + +7 Environment +************* + +These environment variables affect hledger: + + *COLUMNS* This is normally set by your terminal; some hledger +commands ('register') will format their output to this width. If not +set, they will try to use the available terminal width. + + *LEDGER_FILE* The main journal file to use when not specified with +'-f/--file'. Default: '$HOME/.hledger.journal'. + + *NO_COLOR* If this environment variable is set (with any value), +hledger will not use ANSI color codes in terminal output, unless +overridden by an explicit '--color/--colour' option. + + +File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top + +8 PART 2: DATA FORMATS +********************** + + +File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top + +9 Journal +********* + +hledger's default file format, representing a General Journal. Here's a +cheatsheet/mini-tutorial, or you can skip ahead to About journal format. + +* Menu: + +* Journal cheatsheet:: +* About journal format:: +* Comments:: +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Transaction comments:: +* Postings:: +* Account names:: +* Amounts:: +* Costs:: +* Balance assertions:: +* Posting comments:: +* Tags:: +* Directives:: +* account directive:: +* alias directive:: +* commodity directive:: +* decimal-mark directive:: +* include directive:: +* P directive:: +* payee directive:: +* tag directive:: +* Periodic transactions:: +* Auto postings:: +* Other syntax:: + + +File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal + +9.1 Journal cheatsheet +====================== + +# Here is the main syntax of hledger's journal format +# (omitting extra Ledger compatibility syntax). +# hledger journals contain comments, directives, and transactions, in any order: + +############################################################################### +# 1. Comment lines are for notes or temporarily disabling things. +# They begin with #, ;, or a line containing the word "comment". + +# hash comment line +; semicolon comment line +comment +These lines +are commented. +end comment + +# Some but not all hledger entries can have same-line comments attached to them, +# from ; (semicolon) to end of line. + +############################################################################### +# 2. Directives modify parsing or reports in some way. +# They begin with a word or letter (or symbol). + +account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. +account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) +alias chkg = assets:checking +commodity $0.00 +decimal-mark . +include /dev/null +payee Whole Foods +P 2022-01-01 AAAA $1.40 +~ monthly budget goals ; <- 2+ spaces between period expression and description + expenses:food $400 + expenses:home $1000 + budgeted + +############################################################################### +# 3. Transactions are what it's all about; they are dated events, +# usually describing movements of money. +# They begin with a date. + +# DATE DESCRIPTION ; This is a transaction comment. +# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. +# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. +# ; ^^ At least 2 spaces between account and amount. +# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). + +2022-01-01 opening balances are declared this way + assets:checking $1000 ; Account names can be anything. lower case is easy to type. + assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. + assets:cash:wallet $100 ; : indicates subaccounts. + liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. + equity ; One amount can be left blank; $-1900 is inferred here. + +2022-04-15 * (#12345) pay taxes + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a transaction code (text in parentheses) after the date/status. + ; Amounts' sign represents direction of flow, or credit/debit: + assets:checking $-500 ; minus means removed from this account (credit) + expenses:tax:us:2021 $500 ; plus means added to this account (debit) + ; revenue/expense categories are also "accounts" + +2022-01-01 ; The description is optional. + ; Any currency/commodity symbols are allowed, on either side. + assets:cash:wallet GBP -10 + expenses:clothing GBP 10 + assets:gringotts -10 gold + assets:pouch 10 gold + revenues:gifts -2 "Liquorice Wands" ; Complex symbols + assets:bag 2 "Liquorice Wands" ; must be double-quoted. + +2022-01-01 Cost in another commodity can be noted with @ or @@ + assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments 3.0 AAAA @@ $4 ; @@ means total cost + assets:checking $-7.00 + +2022-01-02 assert balances + ; Balances can be asserted for extra error checking, in any transaction. + assets:investments 0 AAAA = 5.0 AAAA + assets:pouch 0 gold = 10 gold + assets:savings $0 = $1000 + +1999-12-31 Ordering transactions by date is recommended but not required. + ; Postings are not required. + +2022.01.01 These date +2022/1/1 formats are +12/31 also allowed (but consistent YYYY-MM-DD is recommended). + + +File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal + +9.2 About journal format +======================== + +hledger's usual data source is a plain text file containing journal +entries in hledger journal format. This file represents a standard +accounting general journal. I use file names ending in '.journal', but +that's not required. The journal file contains a number of transaction +entries, each describing a transfer of money (or any commodity) between +two or more named accounts, in a simple format readable by both hledger +and humans. + + hledger's journal format is compatible with most of Ledger's journal +format, but not all of it. The differences and interoperation tips are +described at hledger and Ledger. With some care, and by avoiding +incompatible features, you can keep your hledger journal readable by +Ledger and vice versa. This can useful eg for comparing the behaviour +of one app against the other. + + You can use hledger without learning any more about this file; just +use the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and +track changes with a version control system such as git. Editor addons +such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and +hledger-vscode for Visual Studio Code, make this easier, adding colour, +formatting, tab completion, and useful commands. See Editor +configuration at hledger.org for the full list. + + Here's a description of each part of the file format (and hledger's +data model). + + A hledger journal file can contain three kinds of thing: file +comments, transactions, and/or directives (counting periodic transaction +rules and auto posting rules as directives). + + +File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal + +9.3 Comments +============ + +Lines in the journal will be ignored if they begin with a hash ('#') or +a semicolon (';'). (See also Other syntax.) hledger will also ignore +regions beginning with a 'comment' line and ending with an 'end comment' +line (or file end). Here's a suggestion for choosing between them: + + * '#' for top-level notes + * ';' for commenting out things temporarily + * 'comment' for quickly commenting large regions (remember it's + there, or you might get confused) + + Eg: + +# a comment line +; another commentline +comment +A multi-line comment block, +continuing until "end comment" directive +or the end of the current file. +end comment + + Some hledger entries can have same-line comments attached to them, +from ; (semicolon) to end of line. See Transaction comments, Posting +comments, and Account comments below. + + +File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal + +9.4 Transactions +================ + +Transactions are the main unit of information in a journal file. They +represent events, typically a movement of some quantity of commodities +between two or more named accounts. + + Each transaction is recorded as a journal entry, beginning with a +simple date in column 0. This can be followed by any of the following +optional fields, separated by spaces: + + * a status character (empty, '!', or '*') + * a code (any short number or text, enclosed in parentheses) + * a description (any remaining text until end of line or a semicolon) + * a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + * 0 or more indented _posting_ lines, describing what was transferred + and the accounts involved (indented comment lines are also allowed, + but not blank lines or non-indented lines). + + Here's a simple journal file containing one transaction: + +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + +File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal + +9.5 Dates +========= + +* Menu: + +* Simple dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates + +9.5.1 Simple dates +------------------ + +Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or +'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may +be omitted, in which case it will be inferred from the context: the +current transaction, the default year set with a 'Y' directive, or the +current date when the command is run. Some examples: '2010-01-31', +'2010/01/31', '2010.1.31', '1/31'. + + (The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.) + + +File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates + +9.5.2 Posting dates +------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like 'date:DATE'. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction's date. +The 'date:' tag must have a valid simple date value if it is present, eg +a 'date:' tag with no value is not allowed. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal + +9.6 Status +========== + +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +'!' pending +'*' cleared + + When reporting, you can filter by status with the '-U/--unmarked', +'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', +and 'status:*' queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" +state is called "uncleared". As of hledger 1.3 we have renamed it to +unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching +pending, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here's one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use '-PC' to see the current balance at +your bank, '-U' to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal + +9.7 Code +======== + +After the status mark, but before the description, you can optionally +write a transaction "code", enclosed in parentheses. This is a good +place to record a check number, or some other important transaction id +or reference number. + + +File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal + +9.8 Description +=============== + +A transaction's description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +9.8.1 Payee and note +-------------------- + +You can optionally include a '|' (pipe) character in descriptions to +subdivide the description into separate fields for payee/payer name on +the left (up to the first '|') and an additional note field on the right +(after the first '|'). This may be worthwhile if you need to do more +precise querying and pivoting by payee or by note. + + +File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal + +9.9 Transaction comments +======================== + +Text following ';', after a transaction description, and/or on indented +lines immediately below it, form comments for that transaction. They +are reproduced by 'print' but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal + +9.10 Postings +============= + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + * (optional) a status character (empty, '!', or '*'), followed by a + space + * (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + * (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, one amount may be left blank; it will be inferred so as to +balance the transaction. + + Be sure to note the unusual two-space delimiter between account name +and amount. This makes it easy to write account names containing +spaces. But if you accidentally leave only one space (or tab) before +the amount, the amount will be considered part of the account name. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal + +9.11 Account names +================== + +Accounts are the main way of categorising things in hledger. As in +Double Entry Bookkeeping, they can represent real world accounts (such +as a bank account), or more abstract categories such as "money borrowed +from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the +traditional accounting categories, which in english are 'assets', +'liabilities', 'equity', 'revenues', 'expenses'. (You might see these +referred to as A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts +into more detailed subaccounts, by writing a full colon between account +name parts. For example, from the account names 'assets:bank:checking' +and 'expenses:food', hledger will infer this hierarchy of five accounts: + +assets +assets:bank +assets:bank:checking +expenses +expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + +assets + bank + checking +expenses + food + + hledger reports can summarise the account tree to any depth, so you +can go as deep as you like with subcategories, but keeping your account +names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, +numbers, symbols, or single spaces. Note, when an account name and an +amount are written on the same line, they must be separated by *two or +more spaces* (or tabs). + + Parentheses or brackets enclosing the full account name indicate +virtual postings, described below. Parentheses or brackets internal to +the account name have no special meaning. + + Account names can be altered temporarily or permanently by account +aliases. + + +File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal + +9.12 Amounts +============ + +After the account name, there is usually an amount. (Important: between +account name and amount, there must be *two or more spaces*.) + + hledger's amount format is flexible, supporting several international +formats. Here are some examples. Amounts have a number (the +"quantity"): + +1 + + ..and usually a currency symbol or commodity name (more on this +below), to the left or right of the quantity, with or without a +separating space: + +$1 +4000 AAPL +3 "green apples" + + Amounts can be preceded by a minus sign (or a plus sign, though plus +is the default), The sign can be written before or after a left-side +commodity symbol: + +-$1 +$-1 + + One or more spaces between the sign and the number are acceptable +when parsing (but they won't be displayed in output): + ++ $1 +$- 1 + + Scientific E notation is allowed: + +1E-6 +EUR 1E3 + +* Menu: + +* Decimal marks digit group marks:: +* Commodity:: +* Directives influencing number parsing and display:: +* Commodity display style:: +* Rounding:: + + +File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts + +9.12.1 Decimal marks, digit group marks +--------------------------------------- + +A _decimal mark_ can be written as a period or a comma: + +1.23 +1,23 + + 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 + + hledger is not biased towards period or comma decimal marks, so a +number containing just one period or comma, like '1,000' or '1.000', is +ambiguous. In such cases hledger assumes it is a decimal mark, parsing +both of these as 1. + + To disambiguate these and ensure accurate number parsing, especially +if you use digit group marks, we recommend declaring the decimal mark. +You can declare it for each file with 'decimal-mark' directives, or for +each commodity with 'commodity' directives (described below). + + +File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts + +9.12.2 Commodity +---------------- + +Amounts in hledger have both a "quantity", which is a signed decimal +number, and a "commodity", which is a currency symbol, stock ticker, or +any word or phrase describing something you are tracking. + + If the commodity name contains non-letters (spaces, numbers, or +punctuation), you must always write it inside double quotes ('"green +apples"', '"ABC123"'). + + If you write just a bare number, that too will have a commodity, with +name '""'; we call that the "no-symbol commodity". + + Actually, hledger combines these single-commodity amounts into more +powerful multi-commodity amounts, which are what it works with most of +the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 +TSLA'. In practice, you will only see multi-commodity amounts in +hledger's output; you can't write them directly in the journal file. + + (If you are writing scripts or working with hledger's internals, +these are the 'Amount' and 'MixedAmount' types.) + + +File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts + +9.12.3 Directives influencing number parsing and display +-------------------------------------------------------- + +You can add 'decimal-mark' and 'commodity' directives to the journal, to +declare and control these things more explicitly and precisely. These +are described below, but here's a quick example: + +# the decimal mark character used by all amounts in this file (all commodities) +decimal-mark . + +# display styles for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 + + +File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts + +9.12.4 Commodity display style +------------------------------ + +For the amounts in each commodity, hledger chooses a consistent display +style (symbol placement, decimal mark and digit group marks, number of +decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a 'D' directive declaring a default commodity, that +commodity symbol and amount format is applied to all no-symbol amounts +in the journal. + + Then each commodity's display style is determined from its +'commodity' directive. We recommend always declaring commodities with +'commodity' directives, since they help ensure consistent display styles +and precisions, and bring other benefits such as error checking for +commodity symbols. + + But if a 'commodity' directive is not present, hledger infers a +commodity's display styles from its amounts as they are written in the +journal (excluding cost amounts and amounts in periodic transaction +rules or auto posting rules). It uses + + * the symbol placement and decimal mark of the first amount seen + * the digit group marks of the first amount with digit group marks + * and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a +default style, like '$1000.00' (symbol on the left with no space, period +as decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the +'-c/--commodity-style' command line option. + + +File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts + +9.12.5 Rounding +--------------- + +Amounts are stored internally as decimal numbers with up to 255 decimal +places. They are displayed with their original journal precisions by +print and print-like reports, and rounded to their display precision +(the number of decimal digits specified by the commodity display style) +by other reports. When rounding, hledger uses banker's rounding (it +rounds to the nearest even digit). So eg 0.5 displayed with zero +decimal digits appears as "0". + + +File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal + +9.13 Costs +========== + +After a posting amount, you can note its cost (when buying) or selling +price (when selling) in another commodity, by writing either '@ +UNITPRICE' or '@@ TOTALPRICE' after it. This indicates a conversion +transaction, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, +discussions, or code; that term was directionally neutral and reminded +that it is a price specific to a transaction, but we now just call it +"cost", with the understanding that the transaction could be a purchase +or a sale.) + + Costs are usually written explicitly with '@' or '@@', but can also +be inferred automatically for simple multi-commodity transactions. +Note, if costs are inferred, the order of postings is significant; the +first posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign +currency in hledger, using the cost notation either explicitly or +implicitly: + + 1. Write the price per unit, as '@ UNITPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as '@@ TOTALPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction. + Note the effect of posting order: the price is added to first + posting, making it '€100 @@ $135', as in example 2: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the '-B/--cost' +flag; this is discussed more in the Cost reporting section. + + Note that the cost normally should be a positive amount, though it's +not required to be. This can be a little confusing, see discussion at +-infer-market-prices: market prices from transactions. + +* Menu: + +* Other cost/lot notations:: + + +File: hledger.info, Node: Other cost/lot notations, Up: Costs + +9.13.1 Other cost/lot notations +------------------------------- + +A slight digression for Ledger and Beancount users. Ledger has a number +of cost/lot-related notations: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a conversion rate, as in hledger + * when buying, also creates a lot than can be selected at + selling time + + * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) + * like the above, but also means "this cost was exceptional, + don't use it when inferring market prices". + + Currently, hledger treats the above like '@' and '@@'; the +parentheses are ignored. + + * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) + * when buying, means "this cost is also the fixed price, don't + let it fluctuate in value reports" + + * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) + * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', + also creates a lot + * when selling, combined with '@ ...', specifies an investment + lot by its cost basis; does not check if that lot is present + + * and related: '[YYYY/MM/DD]' (lot date) + * when buying, attaches this acquisition date to the lot + * when selling, selects a lot by its acquisition date + + * '(SOME TEXT)' (lot note) + * when buying, attaches this note to the lot + * when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after +the posting amount, but ignores them. (This can break transaction +balancing.) + + For Beancount users, the notation and behaviour is different: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a cost without creating a lot, as in hledger + * when buying (augmenting) or selling (reducing) a lot, combined + with '{...}': documents the cost/selling price (not used for + transaction balancing) + + * '{UNITCOST}' and '{{TOTALCOST}}' + * when buying (augmenting), expresses the cost for transaction + balancing, and also creates a lot with this cost basis + attached + * when selling (reducing), + * selects a lot by its cost basis + * raises an error if that lot is not present or can not be + selected unambiguously (depending on booking method + configured) + * expresses the selling price for transaction balancing + + Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation +but ignores it. + + * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, + "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. + + Currently, hledger rejects these. + + +File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal + +9.14 Balance assertions +======================= + +hledger supports Ledger-style balance assertions in journal files. +These look like, for example, '= EXPECTEDBALANCE' following a posting's +amount. Eg here we assert the expected dollar balance in accounts a and +b after each posting: + +2013/1/1 + a $1 =$1 + b =$-1 + +2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the '-I/--ignore-assertions' flag, which can be useful for +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, described below). + +* Menu: + +* Assertions and ordering:: +* Assertions and multiple included files:: +* Assertions and multiple -f files:: +* Assertions and commodities:: +* Assertions and prices:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: +* Assertions and auto postings:: +* Assertions and precision:: + + +File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions + +9.14.1 Assertions and ordering +------------------------------ + +hledger sorts an account's postings and assertions first by date and +then (for postings on the same day) by parse order. Note this is +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder +differently-dated transactions within the journal. But if you reorder +same-dated transactions or postings, assertions might break and require +updating. This order dependence does bring an advantage: precise +control over the order of postings and assertions within a day, so you +can assert intra-day balances. + + +File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions + +9.14.2 Assertions and multiple included files +--------------------------------------------- + +Multiple files included with the 'include' directive are processed as if +concatenated into one file, preserving their order and the posting order +within each file. It means that balance assertions in later files will +see balance from earlier files. + + And if you have multiple postings to an account on the same day, +split across multiple files, and you want to assert the account's +balance on that day, you'll need to put the assertion in the right file +- the last one in the sequence, probably. + + +File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions + +9.14.3 Assertions and multiple -f files +--------------------------------------- + +Unlike 'include', when multiple files are specified on the command line +with multiple '-f/--file' options, balance assertions will not see +balance from earlier files. This can be useful when you do not want +problems in earlier files to disrupt valid assertions in later files. + + If you do want assertions to see balance from earlier files, use +'include', or concatenate the files temporarily. + + +File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions + +9.14.4 Assertions and commodities +--------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity's balance within the +(possibly multi-commodity) account balance. This is how assertions work +in Ledger also. We could call this a "partial" balance assertion. + + To assert the balance of more than one commodity in an account, you +can write multiple postings, each asserting one commodity's balance. + + You can make a stronger "total" balance assertion by writing a double +equals sign ('== EXPECTEDBALANCE'). This asserts that there are no +other commodities in the account besides the asserted one (or at least, +that their balance is 0). + +2013/1/1 + a $1 + a 1€ + b $-1 + c -1€ + +2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1€ + b 0 == $-1 + c 0 == -1€ + +2013/1/3 ; This assertion fails as 'a' also contains 1€ + a 0 == $1 + + It's not yet possible to make a complete assertion about a balance +that has multiple commodities. One workaround is to isolate each +commodity into its own subaccount: + +2013/1/1 + a:usd $1 + a:euro 1€ + b + +2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1€ + + +File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions + +9.14.5 Assertions and prices +---------------------------- + +Balance assertions ignore costs, and should normally be written without +one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below). + + +File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions + +9.14.6 Assertions and subaccounts +--------------------------------- + +The balance assertions above ('=' and '==') do not count the balance +from subaccounts; they check the account's exclusive balance only. You +can assert the balance including subaccounts by writing '=*' or '==*', +eg: + +2019/1/1 + equity:opening balances + checking:a 5 + checking:b 5 + checking 1 ==* 11 + + +File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions + +9.14.7 Assertions and virtual postings +-------------------------------------- + +Balance assertions always consider both real and virtual postings; they +are not affected by the '--real/-R' flag or 'real:' query. + + +File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions + +9.14.8 Assertions and auto postings +----------------------------------- + +Balance assertions _are_ affected by the '--auto' flag, which generates +auto postings, which can alter account balances. Because auto postings +are optional in hledger, accounts affected by them effectively have two +balances. But balance assertions can only test one or the other of +these. So to avoid making fragile assertions, either: + + * assert the balance calculated with '--auto', and always use + '--auto' with that file + * or assert the balance calculated without '--auto', and never use + '--auto' with that file + * or avoid balance assertions on accounts affected by auto postings + (or avoid auto postings entirely). + + +File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions + +9.14.9 Assertions and precision +------------------------------- + +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. Eg a commodity directive may limit the +display precision, but this will not affect balance assertions. Balance +assertion failure messages show exact amounts. + + +File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal + +9.15 Posting comments +===================== + +Text following ';', at the end of a posting line, and/or on indented +lines immediately below it, form comments for that posting. They are +reproduced by 'print' but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + +File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal + +9.16 Tags +========= + +Tags are a way to add extra labels or labelled data to transactions, +postings, or accounts, which you can then search or pivot on. + + They are written as a word (optionally hyphenated) immediately +followed by a full colon, in a transaction or posting or account +directive's comment. (This is an exception to the usual rule that +things in comments are ignored.) Eg, here four different tags are +recorded: one on the checking account, two on the transaction, and one +on the expenses posting: + +account assets:checking ; accounttag: + +2017/1/16 bought groceries ; transactiontag-1: + ; transactiontag-2: + assets:checking $-1 + expenses:food $1 ; postingtag: + + Postings also inherit tags from their transaction and their account. +And transactions also acquire tags from their postings (and postings' +accounts). So in the example above, the expenses posting effectively +has all four tags (by inheriting from account and transaction), and the +transaction also has all four tags (by acquiring from the expenses +posting). + + You can list tag names with 'hledger tags [NAMEREGEX]', or match by +tag name with a 'tag:NAMEREGEX' query. + +* Menu: + +* Tag values:: + + +File: hledger.info, Node: Tag values, Up: Tags + +9.16.1 Tag values +----------------- + +Tags can have a value, which is any text after the colon up until a +comma or end of line (with surrounding whitespace removed). Note this +means that hledger tag values can not contain commas. Eg in the +following posting, the three tags' values are "value 1", "value 2", and +"" (empty) respectively: + + expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz + + Note that tags can be repeated, and are additive rather than +overriding: when the same tag name is seen again with a new value, the +new name:value pair is added to the tags. (It is not possible to +override a tag's value or remove a tag.) + + You can list a tag's values with 'hledger tags TAGNAME --values', or +match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query. + + +File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal + +9.17 Directives +=============== + +Besides transactions, there is something else you can put in a 'journal' +file: directives. These are declarations, beginning with a keyword, +that modify hledger's behaviour. Some directives can have more specific +subdirectives, indented below them. hledger's directives are similar to +Ledger's in many cases, but there are also many differences. Directives +are not required, but can be useful. Here are the main directives: + +purpose directive +-------------------------------------------------------------------------- +*READING DATA:* +Rewrite account names 'alias' +Comment out sections of the file 'comment' +Declare file's decimal mark, to help 'decimal-mark' +parse amounts accurately +Include other data files 'include' +*GENERATING DATA:* +Generate recurring transactions or '~' +budget goals +Generate extra postings on existing '=' +transactions +*CHECKING FOR ERRORS:* +Define valid entities to provide more 'account', 'commodity', +error checking 'payee', 'tag' +*REPORTING:* +Declare accounts' type and display 'account' +order +Declare commodity display styles 'commodity' +Declare market prices 'P' + +* Menu: + +* Directives and multiple files:: +* Directive effects:: + + +File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives + +9.17.1 Directives and multiple files +------------------------------------ + +Directives vary in their scope, ie which journal entries and which input +files they affect. Most often, a directive will affect the following +entries and included files if any, until the end of the current file - +and no further. You might find this inconvenient! For example, 'alias' +directives do not affect parent or sibling files. But there are usually +workarounds; for example, put 'alias' directives in your top-most file, +before including other files. + + The restriction, though it may be annoying at first, is in a good +cause; it allows reports to be stable and deterministic, independent of +the order of input. Without it, reports could show different numbers +depending on the order of -f options, or the positions of include +directives in your files. + + +File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives + +9.17.2 Directive effects +------------------------ + +Here are all hledger's directives, with their effects and scope +summarised - nine main directives, plus four others which we consider +non-essential: + +directivewhat it does ends + at + file + end? +--------------------------------------------------------------------------- +*'account'*Declares an account, for checking all entries in all files; andN + its display order and type. Subdirectives: any text, ignored. +*'alias'*Rewrites account names, in following entries until end of Y + current file or 'end aliases'. Command line equivalent: + '--alias' +*'comment'*Ignores part of the journal file, until end of current file orY + 'end comment'. +*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N + all amounts in all files 2. the decimal mark for parsing + amounts of this commodity, in the following entries until end of + current file (if there is no 'decimal-mark' directive) 3. and + the display style for amounts of this commodity 4. which is + also the precision to use for balanced-transaction checking in + this commodity. Takes precedence over 'D'. Subdirectives: + 'format' (Ledger-compatible syntax). Command line equivalent: + '-c/--commodity-style' +*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y + commodities in following entries until next 'decimal-mark' or + end of current file. Included files can override. Takes + precedence over 'commodity' and 'D'. +*'include'*Includes entries and directives from another file, as if theyN + were written inline. Command line alternative: multiple + '-f/--file' +*'payee'*Declares a payee name, for checking all entries in all files. N +*'P'*Declares the market price of a commodity on some date, for value N + reports. +*'~'*Declares a periodic transaction rule that generates future N +(tilde)transactions with '--forecast' and budget goals with 'balance + --budget'. +Other +syntax: +*'applyPrepends a common parent account to all account names, in Y +account'*following entries until end of current file or 'end apply + account'. +*'D'*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no 'commodity' directive for this commodity: its + decimal mark, balancing precision, and display style, as above. +*'Y'*Sets a default year to use for any yearless dates, in following Y + entries until end of current file. +*'='*Declares an auto posting rule that generates extra postings on partly +(equals)matched transactions with '--auto', in current, parent, and + child files (but not sibling files, see #1212). +*OtherOther directives from Ledger's file format are accepted but +Ledgerignored. +directives* + + +File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal + +9.18 'account' directive +======================== + +'account' directives can be used to declare accounts (ie, the places +that amounts are transferred from and to). Though not required, these +declarations can provide several benefits: + + * They can document your intended chart of accounts, providing a + reference. + * In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + * They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + * They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + * They can store additional account information as comments, or as + tags which can be used to filter or pivot reports. + * They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), affecting reports like balancesheet and + incomestatement. + + They are written as the word 'account' followed by a hledger-style +account name, eg: + +account assets:bank:checking + + Note, however, that accounts declared in account directives are not +allowed to have surrounding brackets and parentheses, unlike accounts +used in postings. So the following journal will not parse: + +account (assets:bank:checking) + +* Menu: + +* Account comments:: +* Account subdirectives:: +* Account error checking:: +* Account display order:: +* Account types:: + + +File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive + +9.18.1 Account comments +----------------------- + +Text following *two or more spaces* and ';' at the end of an account +directive line, and/or following ';' on indented lines immediately below +it, form comments for that account. They are ignored except they may +contain tags, which are not ignored. + + The two-space requirement for same-line account comments is because +';' is allowed in account names. + +account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + +File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive + +9.18.2 Account subdirectives +---------------------------- + +Ledger-style indented subdirectives are also accepted, but currently +ignored: + +account assets:bank:checking + format subdirective is ignored + + +File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive + +9.18.3 Account error checking +----------------------------- + +By default, accounts need not be declared; they come into existence when +a posting references them. This is convenient, but it means hledger +can't warn you when you mis-spell an account name in the journal. +Usually you'll find that error later, as an extra account in balance +reports, or an incorrect balance when reconciling. + + In strict mode, enabled with the '-s'/'--strict' flag, hledger will +report an error if any transaction uses an account name that has not +been declared by an account directive. Some notes: + + * The declaration is case-sensitive; transactions must use the + correct account name capitalisation. + * The account directive's scope is "whole file and below" (see + directives). This means it affects all of the current file, and + any files it includes, but not parent or sibling files. The + position of account directives within the file does not matter, + though it's usual to put them at the top. + * Accounts can only be declared in 'journal' files, but will affect + included files of all types. + * It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + +File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive + +9.18.4 Account display order +---------------------------- + +The order in which account directives are written influences the order +in which accounts appear in reports, hledger-ui, hledger-web etc. By +default accounts appear in alphabetical order, but if you add these +account directives to the journal file: + +account assets +account liabilities +account equity +account revenues +account expenses + + those accounts will be displayed in declaration order: + +$ hledger accounts -1 +assets +liabilities +equity +revenues +expenses + + Any undeclared accounts are displayed last, in alphabetical order. + + Sorting is done at each level of the account tree, within each group +of sibling accounts under the same parent. And currently, this +directive: + +account other:zoo + + would influence the position of 'zoo' among 'other''s subaccounts, +but not the position of 'other' among the top-level accounts. This +means: + + * you will sometimes declare parent accounts (eg 'account other' + above) that you don't intend to post to, just to customize their + display order + * sibling accounts stay together (you couldn't display 'x:y' in + between 'a:b' and 'a:c'). + + +File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive + +9.18.5 Account types +-------------------- + +hledger knows that accounts come in several types: assets, liabilities, +expenses and so on. This enables easy reports like balancesheet and +incomestatement, and filtering by account type with the 'type:' query. + + As a convenience, hledger will detect these account types +automatically if you are using common english-language top-level account +names (described below). But generally we recommend you declare types +explicitly, by adding a 'type:' tag to your top-level account +directives. Subaccounts will inherit the type of their parent. The +tag's value should be one of the five main account types: + + * 'A' or 'Asset' (things you own) + * 'L' or 'Liability' (things you owe) + * 'E' or 'Equity' (investment/ownership; balanced counterpart of + assets & liabilities) + * 'R' or 'Revenue' (what you received money from, AKA income; + technically part of Equity) + * 'X' or 'Expense' (what you spend money on; technically part of + Equity) + + or, it can be (these are used less often): + + * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the + cashflow report) + * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost + reporting).) + + Here is a typical set of account type declarations: + +account assets ; type: A +account liabilities ; type: L +account equity ; type: E +account revenues ; type: R +account expenses ; type: X + +account assets:bank ; type: C +account assets:cash ; type: C + +account equity:conversion ; type: V + + Here are some tips for working with account types. + + * The rules for inferring types from account names are as follows. + These are just a convenience that sometimes help new users get + going; if they don't work for you, just ignore them and declare + your account types. See also Regular expressions. + + If account's name contains this (CI) regular expression: | its type is: + --------------------------------------------------------------------|------------- + ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash + ^assets?(:|$) | Asset + ^(debts?|liabilit(y|ies))(:|$) | Liability + ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion + ^equity(:|$) | Equity + ^(income|revenue)s?(:|$) | Revenue + ^expenses?(:|$) | Expense + + * If you declare any account types, it's a good idea to declare an + account for all of the account types, because a mixture of declared + and name-inferred types can disrupt certain reports. + + * Certain uses of account aliases can disrupt account types. See + Rewriting accounts > Aliases and account types. + + * As mentioned above, subaccounts will inherit a type from their + parent account. More precisely, an account's type is decided by + the first of these that exists: + + 1. A 'type:' declaration for this account. + 2. A 'type:' declaration in the parent accounts above it, + preferring the nearest. + 3. An account type inferred from this account's name. + 4. An account type inferred from a parent account's name, + preferring the nearest parent. + 5. Otherwise, it will have no type. + + * For troubleshooting, you can list accounts and their types with: + + $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] + + +File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal + +9.19 'alias' directive +====================== + +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. This can be useful for: + + * expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + * adapting old journals to your current chart of accounts + * experimenting with new account organisations, like a new hierarchy + * combining two accounts into one, eg to see their sum or difference + on one line + * customising reports + + Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger-web. + + Account aliases are very powerful. They are generally easy to use +correctly, but you can also generate invalid account names with them; +more on this below. + + See also Rewrite account names. + +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Combining aliases:: +* Aliases and multiple files:: +* end aliases directive:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive + +9.19.1 Basic aliases +-------------------- + +To set an account alias, use the 'alias' directive in your journal file. +This affects all subsequent journal entries in the current file or its +included files (but note: not sibling or parent files). The spaces +around the = are optional: + +alias OLD = NEW + + Or, you can use the '--alias 'OLD=NEW'' option on the command line. +This affects all entries. It's useful for trying out aliases +interactively. + + OLD and NEW are case sensitive full account names. hledger will +replace any occurrence of the old account name with the new one. +Subaccounts are also affected. Eg: + +alias checking = assets:bank:wells fargo:checking +; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + +File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive + +9.19.2 Regex aliases +-------------------- + +There is also a more powerful variant that uses a regular expression, +indicated by wrapping the pattern in forward slashes. (This is the only +place where hledger requires forward slashes around a regular +expression.) + + Eg: + +alias /REGEX/ = REPLACEMENT + + or: + +$ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by +REPLACEMENT. REGEX is case-insensitive as usual. + + If you need to match a forward slash, escape it with a backslash, eg +'/\/=:'. + + If REGEX contains parenthesised match groups, these can be referenced +by the usual backslash and number in REPLACEMENT: + +alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 +; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + REPLACEMENT continues to the end of line (or on command line, to end +of option argument), so it can contain trailing whitespace. + + +File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive + +9.19.3 Combining aliases +------------------------ + +You can define as many aliases as you like, using journal directives +and/or command line options. + + Recursive aliases - where an account name is rewritten by one alias, +then by another alias, and so on - are allowed. Each alias sees the +effect of previously applied aliases. + + In such cases it can be important to understand which aliases will be +applied and in which order. For (each account name in) each journal +entry, we apply: + + 1. 'alias' directives preceding the journal entry, most recently + parsed first (ie, reading upward from the journal entry, bottom to + top) + 2. '--alias' options, in the order they appeared on the command line + (left to right). + + In other words, for (an account name in) a given journal entry: + + * the nearest alias declaration before/above the entry is applied + first + * the next alias before/above that will be be applied next, and so on + * aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps +provide semantic stability - aliases will keep working the same way +independent of which files are being read and in which order. + + In case of trouble, adding '--debug=6' to the command line will show +which aliases are being applied when. + + +File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive + +9.19.4 Aliases and multiple files +--------------------------------- + +As explained at Directives and multiple files, 'alias' directives do not +affect parent or sibling files. Eg in this command, + +hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn't work either: + +include a.aliases + +2023-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 + +2023-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected + + +File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive + +9.19.5 'end aliases' directive +------------------------------ + +You can clear (forget) all currently defined aliases (seen in the +journal so far, or defined on the command line) with this directive: + +end aliases + + +File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive + +9.19.6 Aliases can generate bad account names +--------------------------------------------- + +Be aware that account aliases can produce malformed account names, which +could cause confusing reports or invalid 'print' output. For example, +you could erase all account names: + +2021-01-01 + a:aa 1 + b + +$ hledger print --alias '/.*/=' +2021-01-01 + 1 + + The above 'print' output is not a valid journal. Or you could insert +an illegal double space, causing 'print' output that would give a +different journal when reparsed: + +2021-01-01 + old 1 + other + +$ hledger print --alias old="new USD" | hledger -f- print +2021-01-01 + new USD 1 + other + + +File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive + +9.19.7 Aliases and account types +-------------------------------- + +If an account with a type declaration (see Declaring accounts > Account +types) is renamed by an alias, normally the account type remains in +effect. + + However, renaming in a way that reshapes the account tree (eg +renaming parent accounts but not their children, or vice versa) could +prevent child accounts from inheriting the account type of their +parents. + + Secondly, if an account's type is being inferred from its name, +renaming it by an alias could prevent or alter that. + + If you are using account aliases and the 'type:' query is not +matching accounts as you expect, try troubleshooting with the accounts +command, eg something like: + +$ hledger accounts --alias assets=bassetts type:a + + +File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal + +9.20 'commodity' directive +========================== + +The 'commodity' directive performs several functions: + + 1. It declares which commodity symbols may be used in the journal, + enabling useful error checking with strict mode or the check + command. (See Commodity error checking below.) + + 2. It declares the precision with which this commodity's amounts + should be compared when checking for balanced transactions. + + 3. It declares how this commodity's amounts should be displayed, eg + their symbol placement, digit group mark if any, digit group sizes, + decimal mark (period or comma), and the number of decimal places. + (See Commodity display style above.) + + 4. It sets which decimal mark (period or comma) to expect when parsing + subsequent amounts in this commodity (if there is no 'decimal-mark' + directive in effect. See Decimal marks, digit group marks above. + For related dev discussion, see #793.) + + Declaring commodities solves several common parsing/display problems, +so we recommend it. Generally you should put 'commodity' directives at +the top of your journal file (because function 4 is position-sensitive). + +* Menu: + +* Commodity directive syntax:: +* Commodity error checking:: + + +File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive + +9.20.1 Commodity directive syntax +--------------------------------- + +A commodity directive is normally the word 'commodity' followed by a +sample amount (and optionally a comment). Only the amount's symbol and +format is significant. Eg: + +commodity $1000.00 +commodity 1.000,00 EUR +commodity 1 000 000.0000 ; the no-symbol commodity + + Commodities do not have tags (tags in the comment will be ignored). + + A commodity directive's sample amount must always include a period or +comma decimal mark (this rule helps disambiguate decimal marks and digit +group marks). If you don't want to show any decimal digits, write the +decimal mark at the end: + +commodity 1000. AAAA ; show AAAA with no decimals + + Commodity symbols containing spaces, numbers, or punctuation must be +enclosed in double quotes, as usual: + +commodity 1.0000 "AAAA 2023" + + Commodity directives normally include a sample amount, but can +declare only a symbol (ie, just function 1 above): + +commodity $ +commodity INR +commodity "AAAA 2023" +commodity "" ; the no-symbol commodity + + Commodity directives may also be written with an indented 'format' +subdirective, as in Ledger. The symbol is repeated and must be the same +in both places. Other subdirectives are currently ignored: + +; 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 + an unsupported subdirective ; ignored by hledger + + +File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive + +9.20.2 Commodity error checking +------------------------------- + +In strict mode ('-s'/'--strict') (or when you run 'hledger check +commodities'), hledger will report an error if an undeclared commodity +symbol is used. (With one exception: zero amounts are always allowed to +have no commodity symbol.) It works like account error checking +(described above). + + +File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal + +9.21 'decimal-mark' directive +============================= + +You can use a 'decimal-mark' directive - usually one per file, at the +top of the file - to declare which character represents a decimal mark +when parsing amounts in this file. It can look like + +decimal-mark . + + or + +decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we +recommend it, especially if the file contains digit group marks (eg +thousands separators). + + +File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal + +9.22 'include' directive +======================== + +You can pull in the content of additional files by writing an include +directive, like this: + +include FILEPATH + + Only journal files can include, and only journal, timeclock or +timedot files can be included (not CSV files, currently). + + If the file path does not begin with a slash, it is relative to the +current file's folder. + + A tilde means home directory, eg: 'include ~/main.journal'. + + The path may contain glob patterns to match multiple files, eg: +'include *.journal'. + + There is limited support for recursive wildcards: '**/' (the slash is +required) matches 0 or more subdirectories. It's not super convenient +since you have to avoid include cycles and including directories, but +this can be done, eg: 'include */**/*.journal'. + + The path may also be prefixed to force a specific file format, +overriding the file extension (as described in Data formats): 'include +timedot:~/notes/2023*.md'. + + +File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal + +9.23 'P' directive +================== + +The 'P' directive declares a market price, which is a conversion rate +between two commodities on a certain date. This allows value reports to +convert amounts of one commodity to their value in another, on or after +that date. These prices are often obtained from a stock exchange, +cryptocurrency exchange, the or foreign exchange market. + + The format is: + +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the +commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and +quantity) of commodity 2 that one unit of commodity 1 is worth on this +date. Examples: + +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 € $1.35 + +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 € $1.40 + + The '-V', '-X' and '--value' flags use these market prices to show +amount values in another commodity. See Value reporting. + + +File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal + +9.24 'payee' directive +====================== + +'payee PAYEE NAME' + + This directive can be used to declare a limited set of payees which +may appear in transaction descriptions. The "payees" check will report +an error if any transaction refers to a payee that has not been +declared. Eg: + +payee Whole Foods ; a comment + + Payees do not have tags (tags in the comment will be ignored). + + To declare the empty payee name, use '""'. + +payee "" + + Ledger-style indented subdirectives, if any, are currently ignored. + + +File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal + +9.25 'tag' directive +==================== + +'tag TAGNAME' + + This directive can be used to declare a limited set of tag names +allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + +tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is +used. It is quite easy to accidentally create a tag through normal use +of colons in comments(#comments]; if you want to prevent this, you can +declare and check your tags . + + +File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal + +9.26 Periodic transactions +========================== + +The '~' directive declares recurring transactions. Such directives +allow hledger to generate temporary future transactions (visible in +reports, not in the journal file) to help with forecasting or budgeting. + + Periodic transactions can be a little tricky, so before you use them, +read this whole section, or at least these tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + 2. For troubleshooting, show the generated transactions with 'hledger + print --forecast tag:generated' or 'hledger register --forecast + tag:generated'. + 3. Forecasted transactions will begin only after the last + non-forecasted transaction's date. + 4. Forecasted transactions will end 6 months from today, by default. + See below for the exact start/end rules. + 5. period expressions can be tricky. Their documentation needs + improvement, but is worth studying. + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in 'weekly from DATE', DATE + must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give + an error. + 7. Other period expressions with an interval are automatically + expanded to cover a whole number of that interval. (This is done + to improve reports, but it also affects periodic transactions. + Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th + day of month from 2023/01', which is equivalent to '~ every 10th + day of month from 2023/01/01', will be adjusted to start on + 2019/12/10. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +9.26.1 Periodic rule syntax +--------------------------- + +A periodic transaction rule looks like a normal journal entry, with the +date replaced by a tilde ('~') followed by a period expression +(mnemonic: '~' looks like a recurring sine wave.): + +# every first of month +~ monthly + expenses:rent $2000 + assets:bank:checking + +# every 15th of month in 2023's first quarter: +~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying +multi-period reports, just interpreted differently; there, it specifies +report periods; here it specifies recurrence dates (the periods' start +dates). + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +9.26.2 Periodic rules and relative dates +---------------------------------------- + +Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', +'next quarter') are usually not recommended in periodic rules, since the +results will change as time passes. If used, they will be interpreted +relative to, in order of preference: + + 1. the first day of the default year specified by a recent 'Y' + directive + 2. or the date specified with '--today' + 3. or the date on which you are running the report. + + They will not be affected at all by report period or forecast period +dates. + + +File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions + +9.26.3 Two spaces between period expression and description! +------------------------------------------------------------ + +If the period expression is followed by a transaction description, these +must be separated by *two or more spaces*. This helps hledger know +where the period expression ends, so that descriptions can not +accidentally alter their meaning, as in this example: + +; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" +; || +; vv +~ every 2 months in 2023, 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: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal + +9.27 Auto postings +================== + +The '=' directive declares a rule for generating temporary extra +postings on transactions. Wherever the rule matches an existing +posting, it can add one or more companion postings below that one, +optionally influenced by the matched posting's amount. This can be +useful for generating tax postings with a standard percentage, for +example. + + Note that depending on generated data is not ideal for financial +records (it's less portable, less future-proof, less auditable by +others, and less robust, since other features like balance assertions +will depend on using or not using '--auto'). + + 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:: + + +File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings + +9.27.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). + +* Menu: + +* Auto postings and dates:: +* Auto postings and transaction balancing / inferred amounts / balance assertions:: +* Auto posting tags:: +* Auto postings on forecast transactions only:: + + +File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files + +9.27.1.1 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 and multiple files + +9.27.1.2 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, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files + +9.27.1.3 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: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files + +9.27.1.4 Auto postings on forecast transactions only +.................................................... + +Tip: you can can make auto postings that will apply to forecast +transactions but not recorded transactions, by adding +'tag:_generated-transaction' to their QUERY. This can be useful when +generating new journal entries to be saved in the journal. + + +File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal + +9.28 Other syntax +================= + +hledger journal format supports quite a few other features, mainly to +make interoperating with or converting from Ledger easier. Note some of +the features below are powerful and can be useful in special cases, but +in general, features in this section are considered less important or +even not recommended for most users. Downsides are mentioned to help +you decide if you want to use them. + +* Menu: + +* Balance assignments:: +* Bracketed posting dates:: +* D directive:: +* apply account directive:: +* Y directive:: +* Secondary dates:: +* Star comments:: +* Valuation expressions:: +* Virtual postings:: +* Other Ledger directives:: + + +File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax + +9.28.1 Balance assignments +-------------------------- + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). + + Downsides: using balance assignments makes your journal less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. Also balance +assignments' forcing of balances can hide errors. These things make +your financial data less portable, less future-proof, and less +trustworthy in an audit. + +* Menu: + +* Balance assignments and prices:: +* Balance assignments and multiple files:: + + +File: hledger.info, Node: Balance assignments and prices, Next: Balance assignments and multiple files, Up: Balance assignments + +9.28.1.1 Balance assignments and prices +....................................... + +A cost in a balance assignment will cause the calculated amount to have +that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019-01-01 + (a) $1 @ €2 = $1 @ €2 + + +File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and prices, Up: Balance assignments + +9.28.1.2 Balance assignments and multiple files +............................................... + +Balance assignments handle multiple files like balance assertions. They +see balance from other files previously included from the current file, +but not from previous sibling or parent files. + + +File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax + +9.28.2 Bracketed posting dates +------------------------------ + +For setting posting dates and secondary posting dates, Ledger's +bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or +'[=DATE2]' in posting comments. hledger will attempt to parse any +square-bracketed sequence of the '0123456789/-.=' characters in this +way. With this syntax, DATE infers its year from the transaction and +DATE2 infers its year from DATE. + + Downsides: another syntax to learn, redundant with hledger's +'date:'/'date2:' tags, and confusingly similar to Ledger's lot date +syntax. + + +File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax + +9.28.3 'D' directive +-------------------- + +'D AMOUNT' + + This directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. This effect lasts until the next 'D' directive, or the end +of the journal. + + For compatibility/historical reasons, 'D' also acts like a +'commodity' directive (setting the commodity's decimal mark for parsing +and display style for output). So its argument is not just a commodity +symbol, but a full amount demonstrating the style. The amount must +include a decimal mark (either period or comma). Eg: + +; commodity-less amounts should be treated as dollars +; (and displayed with the dollar sign on the left, thousands separators and two decimal places) +D $1,000.00 + +1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity's display style, a 'commodity' directive has +highest priority, then a 'D' directive. + + For detecting a commodity's decimal mark during parsing, +'decimal-mark' has highest priority, then 'commodity', then 'D'. + + For checking commodity symbols with the check command, a 'commodity' +directive is required ('hledger check commodities' ignores 'D' +directives). + + Downsides: omitting commodity symbols makes your financial data less +explicit, less portable, and less trustworthy in an audit. It is +usually an unsustainable shortcut; sooner or later you will want to +track multiple commodities. D is overloaded with functions redundant +with 'commodity' and 'decimal-mark'. And it works differently from +Ledger's 'D'. + + +File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax + +9.28.4 'apply account' directive +-------------------------------- + +This directive sets a default parent account, which will be prepended to +all accounts in following entries, until an 'end apply account' +directive or end of current file. Eg: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + 'account' directives are also affected, and so is any 'include'd +content. + + Account names entered via hledger add or hledger-web are not +affected. + + Account aliases, if any, are applied after the parent account is +prepended. + + Downsides: this can make your financial data less explicit, less +portable, and less trustworthy in an audit. + + +File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax + +9.28.5 'Y' directive +-------------------- + +'Y YEAR' + + or (deprecated backward-compatible forms): + + 'year YEAR' 'apply year YEAR' + + The space is optional. This sets a default year to be used for +subsequent dates which don't specify a year. Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +year 2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at +least) makes your financial data less explicit, less portable, and less +trustworthy in an audit. Such dates can get separated from their +corresponding Y directive, eg when evaluating a region of the journal in +your editor. A missing Y directive makes reports dependent on today's +date. + + +File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax + +9.28.6 Secondary dates +---------------------- + +A secondary date is written after the primary date, following an equals +sign. If the year is omitted, the primary date's year is assumed. When +running reports, the primary (left) date is used by default, but with +the '--date2' flag (or '--aux-date' or '--effective'), the secondary +(right) date will be used instead. + + The meaning of secondary dates is up to you, but it's best to follow +a consistent rule. Eg "primary = the bank's clearing date, secondary = +date the transaction was initiated, if different". + + Downsides: makes your financial data more complicated, less portable, +and less trustworthy in an audit. Keeping the meaning of the two dates +consistent requires discipline, and you have to remember which reporting +mode is appropriate for a given report. Posting dates are simpler and +better. + + +File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax + +9.28.7 Star comments +-------------------- + +Lines beginning with '*' (star/asterisk) are also comment lines. This +feature allows Emacs users to insert org headings in their journal, +allowing them to fold/unfold/navigate it like an outline when viewed +with org mode. + + Downsides: another, unconventional comment syntax to learn. +Decreases your journal's portability. And switching to Emacs org mode +just for folding/unfolding meant losing the benefits of ledger mode; +nowadays you can add outshine mode to ledger mode to get folding without +losing ledger mode's features. + + +File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax + +9.28.8 Valuation expressions +---------------------------- + +Ledger allows a valuation function or value to be written in double +parentheses after an amount. hledger ignores these. + + +File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax + +9.28.9 Virtual postings +----------------------- + +A posting with parentheses around the account name ('(some:account)') is +called a _unbalanced virtual posting_. Such postings do not participate +in transaction balancing. (And if you write them without an amount, a +zero amount is always inferred.) These can occasionally be convenient +for special circumstances, but they violate double entry bookkeeping and +make your data less portable across applications, so many people avoid +using them at all. + + A posting with brackets around the account name ('[some:account]') is +called a _balanced virtual posting_. The balanced virtual postings in a +transaction must add up to zero, just like ordinary postings, but +separately from them. These are not part of double entry bookkeeping +either, but they are at least balanced. An example: + +2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Ordinary postings, whose account names are neither parenthesised nor +bracketed, are called _real postings_. You can exclude virtual postings +from reports with the '-R/--real' flag or a 'real:1' query. + + +File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax + +9.28.10 Other Ledger directives +------------------------------- + +These other Ledger directives are currently accepted but ignored. This +allows hledger to read more Ledger files, but be aware that hledger's +reports may differ from Ledger's if you use these. + +apply fixed COMM AMT +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR +end apply fixed +end apply tag +end apply year +end tag +eval / expr EXPR +python + PYTHONCODE +tag NAME +value EXPR +--command-line-flags + + See also https://hledger.org/ledger.html for a detailed +hledger/Ledger syntax comparison. + + +File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top + +10 CSV +****** + +hledger can read CSV files (Character Separated Value - usually comma, +semicolon, or tab) containing dated records, automatically converting +each record into a transaction. + + (To learn about _writing_ CSV, see CSV output.) + + For best error messages when reading CSV/TSV/SSV files, make sure +they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use +a hledger file prefix (see File Extension below). + + Each CSV file must be described by a corresponding _rules file_. +This contains rules describing the CSV data (header line, fields layout, +date format etc.), how to construct hledger transactions from it, and +how to categorise transactions based on description or other attributes. + + By default hledger looks for a rules file named like the CSV file +with an extra '.rules' extension, in the same directory. Eg when asked +to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'. You can +specify a different rules file with the '--rules-file' option. If no +rules file is found, hledger will create a sample rules file, which +you'll need to adjust. + + At minimum, the rules file must identify the date and amount fields, +and often it also specifies the date format and how many header lines +there are. Here's a simple CSV file and a rules file for it: + +Date, Description, Id, Amount +12/11/2019, Foo, 123, 10.23 + +# basic.csv.rules +skip 1 +fields date, description, , amount +date-format %d/%m/%Y + +$ hledger print -f basic.csv +2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There's an introductory Importing CSV data tutorial on hledger.org, +and more CSV rules examples below, and a larger collection at +https://github.com/simonmichael/hledger/tree/master/examples/csv. + +* Menu: + +* CSV rules cheatsheet:: +* source:: +* separator:: +* skip:: +* date-format:: +* timezone:: +* newest-first:: +* intra-day-reversed:: +* decimal-mark:: +* fields list:: +* Field assignment:: +* Field names:: +* if block:: +* Matchers:: +* if table:: +* balance-type:: +* include:: +* Working with CSV:: +* CSV rules examples:: + + +File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV + +10.1 CSV rules cheatsheet +========================= + +The following kinds of rule can appear in the rules file, in any order. +(Blank lines and lines beginning with '#' or ';' or '*' are ignored.) + +*'source'* optionally declare which file to read data + from +*'separator'* declare the field separator, instead of + relying on file extension +*'skip'* skip one or more header lines at start of file +*'date-format'* declare how to parse CSV dates/date-times +*'timezone'* declare the time zone of ambiguous CSV + date-times +*'newest-first'* improve txn order when: there are multiple + records, newest first, all with the same date +*'intra-day-reversed'* improve txn order when: same-day txns are in + opposite order to the overall file +*'decimal-mark'* declare the decimal mark used in CSV amounts, + when ambiguous +*'fields' list* name CSV fields for easy reference, and + optionally assign their values to hledger + fields +*Field assignment* assign a CSV value or interpolated text value + to a hledger field +*'if' block* conditionally assign values to hledger fields, + or 'skip' a record or 'end' (skip rest of + file) +*'if' table* conditionally assign values to hledger fields, + using compact syntax +*'balance-type'* select which type of balance + assertions/assignments to generate +*'include'* inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are +evaluated. + + +File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV + +10.2 'source' +============= + +If you tell hledger to read a csv file with '-f foo.csv', it will look +for rules in 'foo.csv.rules'. Or, you can tell it to read the rules +file, with '-f foo.csv.rules', and it will look for data in 'foo.csv' +(since 1.30). + + These are mostly equivalent, but the second method provides some +extra features. For one, the data file can be missing, without causing +an error; it is just considered empty. And, you can specify a different +data file by adding a "source" rule: + +source ./Checking1.csv + + If you specify just a file name with no path, hledger will look for +it in your system's downloads directory ('~/Downloads', currently): + +source Checking1.csv + + And if you specify a glob pattern, hledger will read the most recent +of the matched files (useful with repeated downloads): + +source Checking1*.csv + + See also "Working with CSV > Reading files specified by rule". + + +File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV + +10.3 'separator' +================ + +You can use the 'separator' rule to read other kinds of +character-separated data. The argument is any single separator +character, or the words 'tab' or 'space' (case insensitive). Eg, for +comma-separated values (CSV): + +separator , + + or for semicolon-separated values (SSV): + +separator ; + + or for tab-separated values (TSV): + +separator TAB + + If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a +'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be +inferred automatically, and you won't need this rule. + + +File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV + +10.4 'skip' +=========== + +skip N + + The word 'skip' followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines at the start of the input +data. You'll need this whenever your CSV data contains header lines. +Note, empty and blank lines are skipped automatically, so you don't need +to count those. + + 'skip' has a second meaning: it can be used inside if blocks +(described below), to skip one or more records whenever the condition is +true. Records skipped in this way are ignored, except they are still +required to be valid CSV. + + +File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV + +10.5 'date-format' +================== + +date-format DATEFMT + + This is a helper for the 'date' (and 'date2') fields. If your CSV +dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD', +you'll need to add a date-format rule describing them with a +strptime-style date parsing pattern - see +https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. +The pattern must parse the CSV date value completely. Some examples: + +# MM/DD/YY +date-format %m/%d/%y + +# D/M/YYYY +# The - makes leading zeros optional. +date-format %-d/%-m/%Y + +# YYYY-Mmm-DD +date-format %Y-%h-%d + +# M/D/YYYY HH:MM AM some other junk +# Note the time and junk must be fully parsed, though only the date is used. +date-format %-m/%-d/%Y %l:%M %p some other junk + + +File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV + +10.6 'timezone' +=============== + +timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone +other than yours, but containing no explicit time zone information, you +can use this rule to declare the CSV's native time zone, which helps +prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don't +need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ', +'%Ez'; see the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware +conversion, localising the CSV date-times to your current system time +zone. If you prefer to localise to some other time zone, eg for +reproducibility, you can (on unix at least) set the output timezone with +the TZ environment variable, eg: + +$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + 'timezone' currently does not understand timezone names, except +"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". +For others, use numeric format: +HHMM or -HHMM. + + +File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV + +10.7 'newest-first' +=================== + +hledger tries to ensure that the generated transactions will be ordered +chronologically, including same-day transactions. Usually it can +auto-detect how the CSV records are ordered. But if it encounters CSV +where all records are on the same date, it assumes that the records are +oldest first. If in fact the CSV's records are normally newest first, +like: + +2022-10-01, txn 3... +2022-10-01, txn 2... +2022-10-01, txn 1... + + you can add the 'newest-first' rule to help hledger generate the +transactions in correct order. + +# same-day CSV records are newest first +newest-first + + +File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV + +10.8 'intra-day-reversed' +========================= + +If CSV records within a single day are ordered opposite to the overall +record order, you can add the 'intra-day-reversed' rule to improve the +order of journal entries. Eg, here the overall record order is newest +first, but same-day records are oldest first: + +2022-10-02, txn 3... +2022-10-02, txn 4... +2022-10-01, txn 1... +2022-10-01, txn 2... + +# transactions within each day are reversed with respect to the overall date order +intra-day-reversed + + +File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV + +10.9 'decimal-mark' +=================== + +decimal-mark . + + or: + +decimal-mark , + + hledger automatically accepts either period or comma as a decimal +mark when parsing numbers (cf Amounts). However if any numbers in the +CSV contain digit group marks, such as thousand-separating commas, you +should declare the decimal mark explicitly with this rule, to avoid +misparsed numbers. + + +File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV + +10.10 'fields' list +=================== + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word 'fields' followed by comma-separated field +names) is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say + '%SomeField' instead of remembering '%13'. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and + build a transaction. + + Here's an example that says "use the 1st, 2nd and 4th fields as the +transaction's date, description and amount; name the last two fields for +later reference; and ignore the others": + +fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to +the CSV file's separator. Also: + + * There must be least two items in the list (at least one comma). + * Field names may not contain spaces. Spaces before/after field + names are optional. + * Field names may contain '_' (underscore) or '-' (hyphen). + * Fields you don't care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it's convenient to use these for +your field names, suitably modified (eg lower-cased with spaces replaced +by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning +to a hledger field with the same name. Eg you could call the CSV's +"balance" field 'balance_' to avoid directly setting hledger's 'balance' +field (and generating a balance assertion). + + +File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV + +10.11 Field assignment +====================== + +HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to +hledger fields. They can be used instead of or in addition to a fields +list (see above). + + To assign a value to a hledger field, write the field name (any of +the standard hledger field/pseudo-field names, defined below), a space, +followed by a text value on the same line. This text value may +interpolate CSV fields, referenced either by their 1-based position in +the CSV record ('%N') or by the name they were given in the fields list +('%CSVFIELD'), and regular expression match groups ('\N'). + + Some examples: + +# set the amount to the 4th CSV field, with " USD" appended +amount %4 USD + +# combine three fields to make a comment, containing note: and date: tags +comment note: %somefield - %anotherfield, date: %1 + + Tips: + + * Interpolation strips outer whitespace (so a CSV value like '" 1 "' + becomes '1' when interpolated) (#1051). + * Interpolations always refer to a CSV field - you can't interpolate + a hledger field. (See Referencing other fields below). + + +File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV + +10.12 Field names +================= + +Note the two kinds of field names mentioned here, and used only in +hledger CSV rules files: + + 1. *CSV field names* ('CSVFIELD' in these docs): you can optionally + name the CSV columns for easy reference (since hledger doesn't yet + automatically recognise column headings in a CSV file), by writing + arbitrary names in a 'fields' list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you + must set at least some of these to generate the hledger transaction + from a CSV record, by writing them as the left hand side of a field + assignment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a 'fields' list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what +happens when you assign values to them: + +* Menu: + +* date field:: +* date2 field:: +* status field:: +* code field:: +* description field:: +* comment field:: +* account field:: +* amount field:: +* currency field:: +* balance field:: + + +File: hledger.info, Node: date field, Next: date2 field, Up: Field names + +10.12.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 + +10.12.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 + +10.12.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 + +10.12.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 + +10.12.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 + +10.12.6 comment field +--------------------- + +'comment' sets the transaction's comment, if any. + + 'commentN', where N is a number, sets the Nth posting's comment. + + You can assign multi-line comments by writing literal '\n' in the +code. A comment starting with '\n' will begin on a new line. + + Comments can contain tags, as usual. + + +File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names + +10.12.7 account field +--------------------- + +Assigning to 'accountN', where N is 1 to 99, sets the account name of +the Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you'll want to set 'account1' +and 'account2'. Typically 'account1' is associated with the CSV file, +and is set once with a top-level assignment, while 'account2' is set +based on each transaction's description, in conditional rules. + + If a posting's account name is left unset but its amount is set (see +below), a default account name will be chosen (like "expenses:unknown" +or "income:unknown"). + + +File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names + +10.12.8 amount field +-------------------- + +There are several ways to set posting amounts from CSV, useful in +different situations. + + 1. *'amount'* is the oldest and simplest. Assigning to this sets the + amount of the first and second postings. In the second posting, + the amount will be negated; also, if it has a cost attached, it + will be converted to cost. + + 2. *'amount-in'* and *'amount-out'* work exactly like the above, but + should be used when the CSV has two amount fields (such as "Debit" + and "Credit", or "Inflow" and "Outflow"). Whichever field has a + non-zero value will be used as the amount of the first and second + postings. Here are some tips to avoid confusion: + + * It's not "amount-in for posting 1 and amount-out for posting + 2", it is "extract a single amount from the amount-in or + amount-out field, and use that for posting 1 and (negated) for + posting 2". + * Don't use both 'amount' and 'amount-in'/'amount-out' in the + same rules file; choose based on whether the amount is in a + single CSV field or spread across two fields. + * In each record, at most one of the two CSV fields should + contain a non-zero amount; the other field must contain a zero + or nothing. + * hledger assumes both CSV fields contain unsigned numbers, and + it automatically negates the amount-out values. + * If the data doesn't fit these requirements, you'll probably + need an if rule (see below). + + 3. *'amountN'* (where N is a number from 1 to 99) sets the amount of + only a single posting: the Nth posting in the transaction. You'll + usually need at least two such assignments to make a balanced + transaction. You can also generate more than two postings, to + represent more complex transactions. The posting numbers don't + have to be consecutive; with if rules, higher posting numbers can + be useful to ensure a certain order of postings. + + 4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but + should be used when the CSV has two amount fields. This is + analogous to 'amount-in' and 'amount-out', and those tips also + apply here. + + 5. Remember that a 'fields' list can also do assignments. So in a + fields list if you name a CSV field "amount", that counts as + assigning to 'amount'. (If you don't want that, call it something + else in the fields list, like "amount_".) + + 6. The above don't handle every situation; if you need more + flexibility, use an 'if' rule to set amounts conditionally. See + "Working with CSV > Setting amounts" below for more on this and on + amount-setting generally. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +10.12.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 + +10.12.10 balance field +---------------------- + +'balanceN' sets a balance assertion amount (or if the posting amount is +left empty, a balance assignment) on posting N. + + 'balance' is a compatibility spelling for hledger <1.17; it is +equivalent to 'balance1'. + + You can adjust the type of assertion/assignment with the +'balance-type' rule (see below). + + See Tips below for more about setting amounts and currency. + + +File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV + +10.13 'if' block +================ + +Rules can be applied conditionally, depending on patterns in the CSV +data. This allows flexibility; in particular, it is how you can +categorise transactions, selecting an appropriate account name based on +their description (for example). There are two ways to write +conditional rules: "if blocks", described here, and "if tables", +described below. + + An if block is the word 'if' and one or more "matcher" expressions +(can be a word or phrase), one per line, starting either on the same or +next line; followed by one or more indented rules. Eg, + +if MATCHER + RULE + + or + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be +applied. They are usually field assignments, but the following special +rules may also be used within an if block: + + * 'skip' - skips the matched CSV record (generating no transaction + from it) + * 'end' - skips the rest of the current CSV file. + + Some examples: + +# if the record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the record contains any of these phrases, set account2 and a transaction comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + +# if an empty record is seen (assuming five fields), ignore the rest of the CSV file +if ,,,, + end + + +File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV + +10.14 Matchers +============== + +There are two kinds: + + 1. A record matcher is a word or single-line text fragment or regular + expression ('REGEX'), which hledger will try to match + case-insensitively anywhere within the CSV record. + Eg: 'whole foods' + + 2. A field matcher is preceded with a percent sign and CSV field name + ('%CSVFIELD REGEX'). hledger will try to match these just within + the named CSV field. + Eg: '%date 2023' + + The regular expression is (as usual in hledger) a POSIX extended +regular expression, that also supports GNU word boundaries ('\b', '\B', +'\<', '\>'), and nothing else. If you have trouble, see "Regular +expressions" in the hledger manual +(https://hledger.org/hledger.html#regular-expressions). + +* Menu: + +* What matchers match:: +* Combining matchers:: +* Match groups:: + + +File: hledger.info, Node: What matchers match, Next: Combining matchers, Up: Matchers + +10.14.1 What matchers match +--------------------------- + +With record matchers, it's important to know that the record matched is +not the original CSV record, but a modified one: separators will be +converted to commas, and enclosing double quotes (but not enclosing +whitespace) are removed. So for example, when reading an SSV file, if +the original record was: + +2023-01-01; "Acme, Inc."; 1,000 + + the regex would see, and try to match, this modified record text: + +2023-01-01,Acme, Inc., 1,000 + + +File: hledger.info, Node: Combining matchers, Next: Match groups, Prev: What matchers match, Up: Matchers + +10.14.2 Combining matchers +-------------------------- + +When an if block has multiple matchers, they are combined as follows: + + * By default they are OR'd (any one of them can match) + * When a matcher is preceded by ampersand ('&') it will be AND'ed + with the previous matcher (both of them must match) + * When a matcher is preceded by an exclamation mark ('!'), the + matcher is negated (it may not match). + + Currently there is a limitation: you can't use both '&' and '!' on +the same line (you can't AND a negated matcher). + + +File: hledger.info, Node: Match groups, Prev: Combining matchers, Up: Matchers + +10.14.3 Match groups +-------------------- + +Matchers can define match groups: parenthesised portions of the regular +expression which are available for reference in field assignments. +Groups are enclosed in regular parentheses ('(' and ')') and can be +nested. Each group is available in field assignments using the token +'\N', where N is an index into the match groups for this conditional +block (e.g. '\1', '\2', etc.). + + Example: Warp credit card payment postings to the beginning of the +billing period (Month start), to match how they are presented in +statements, using posting dates: + +if %date (....-..)-.. + comment2 date:\1-01 + + Another example: Read the expense account from the CSV field, but +throw away a prefix: + +if %account1 liabilities:family:(expenses:.*) + account1 \1 + + +File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV + +10.15 'if' table +================ + +"if tables" are an alternative to if blocks; they can express many +matchers and field assignments in a more compact tabular format, like +this: + +if,HLEDGERFIELD1,HLEDGERFIELD2,... +MATCHERA,VALUE1,VALUE2,... +MATCHERB,VALUE1,VALUE2,... +MATCHERC,VALUE1,VALUE2,... + + + The first character after 'if' is taken to be this if table's field +separator. It is unrelated to the separator used in the CSV file. It +should be a non-alphanumeric character like ',' or '|' that does not +appear anywhere else in the table (it should not be used in field names +or matchers or values, and it cannot be escaped with a backslash). + + Each line must contain the same number of separators; empty values +are allowed. Whitespace can be used in the matcher lines for +readability (but not in the if line, currently). The table must be +terminated by an empty line (or end of file). + + An if table like the above is interpreted as follows: try all of the +matchers; whenever a matcher succeeds, assign all of the values on that +line to the corresponding hledger fields; later lines can overrider +earlier ones. It is equivalent to this sequence of if blocks: + +if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERB + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + +if,account2,comment +atm transaction fee,expenses:business:banking,deductible? check it +%description groceries,expenses:groceries, +2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + +File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV + +10.16 'balance-type' +==================== + +Balance assertions generated by assigning to balanceN are of the simple +'=' type by default, which is a single-commodity, subaccount-excluding +assertion. You may find the subaccount-including variants more useful, +eg if you have created some virtual subaccounts of checking to help with +budgeting. You can select a different type of assertion with the +'balance-type' rule: + +# balance assertions will consider all commodities and all subaccounts +balance-type ==* + + Here are the balance assertion types for quick reference: + += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts + + +File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV + +10.17 'include' +=============== + +include RULESFILE + + This includes the contents of another CSV rules file at this point. +'RULESFILE' is an absolute file path or a path relative to the current +file's directory. This can be useful for sharing common rules between +several rules files, eg: + +# someaccount.csv.rules + +## someaccount-specific rules +fields date,description,amount +account1 assets:someaccount +account2 expenses:misc + +## common rules +include categorisation.rules + + +File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV + +10.18 Working with CSV +====================== + +Some tips: + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading CSV from standard input:: +* Reading multiple CSV files:: +* Reading files specified by rule:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Amount signs:: +* Setting currency/commodity:: +* Amount decimal places:: +* Referencing other fields:: +* How CSV rules are evaluated:: +* Well factored rules:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV + +10.18.1 Rapid feedback +---------------------- + +It's a good idea to get rapid feedback while creating/troubleshooting +CSV rules. Here's a good way, using entr from eradman.com/entrproject: + +$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions +of interest. "bash -c" is used to run multiple commands, so we can echo +a separator each time the command re-runs, making it easier to read the +output. + + +File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV + +10.18.2 Valid CSV +----------------- + +Note that hledger will only accept valid CSV conforming to RFC 4180, and +equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab +as separators). This means, eg: + + * Values may be enclosed in double quotes, or not. Enclosing in + single quotes is not allowed. (Eg ''A','B'' is rejected.) + * When values are enclosed in double quotes, spaces outside the + quotes are not allowed. (Eg '"A", "B"' is rejected.) + * When values are not enclosed in quotes, they may not contain double + quotes. (Eg 'A"A, B' is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you'll need to +transform it before reading with hledger. Try using sed, or a more +permissive CSV parser like python's csv lib. + + +File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV + +10.18.3 File Extension +---------------------- + +To help hledger choose the CSV file reader and show the right error +messages (and choose the right field separator character by default), +it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv' +filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV +reader (and the default field separator) by prefixing the file path with +'csv:', 'ssv:' or 'tsv:': Eg: + +$ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator +rule if needed. + + +File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV + +10.18.4 Reading CSV from standard input +--------------------------------------- + +You'll need the file format prefix when reading CSV from stdin also, +since hledger assumes journal format by default. Eg: + +$ cat foo.dat | hledger -f ssv:- print + + +File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV + +10.18.5 Reading multiple CSV files +---------------------------------- + +If you use multiple '-f' options to read multiple CSV files at once, +hledger will look for a correspondingly-named rules file for each CSV +file. But if you use the '--rules-file' option, that rules file will be +used for all the CSV files. + + +File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV + +10.18.6 Reading files specified by rule +--------------------------------------- + +Instead of specifying a CSV file in the command line, you can specify a +rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will +read data from foo.csv in the same directory, but you can add a source +rule to specify a different data file, perhaps located in your web +browser's download directory. + + This feature was added in hledger 1.30, so you won't see it in most +CSV rules examples. But it helps remove some of the busywork of +managing CSV downloads. Most of your financial institutions's default +CSV filenames are different and can be recognised by a glob pattern. So +you can put a rule like 'source Checking1*.csv' in +foo-checking.csv.rules, and then periodically follow a workflow like: + + 1. Download CSV from Foo's website, using your browser's defaults + 2. Run 'hledger import foo-checking.csv.rules' to import any new + transactions + + After import, you can: discard the CSV, or leave it where it is for a +while, or move it into your archives, as you prefer. If you do nothing, +next time your browser will save something like Checking1-2.csv, and +hledger will use that because of the '*' wild card and because it is the +most recent. + + +File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV + +10.18.7 Valid transactions +-------------------------- + +After reading a CSV file, hledger post-processes and validates the +generated journal entries as it would for a journal file - balancing +them, applying balance assignments, and canonicalising amount styles. +Any errors at this stage will be reported in the usual way, displaying +the problem entry. + + There is one exception: balance assertions, if you have generated +them, will not be checked, since normally these will work only when the +CSV data is part of the main journal. If you do need to check balance +assertions generated from CSV right away, pipe into another hledger: + +$ hledger -f file.csv print | hledger -f- print + + +File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV + +10.18.8 Deduplicating, importing +-------------------------------- + +When you download a CSV file periodically, eg to get your latest bank +transactions, the new file may overlap with the old one, containing some +of the same records. + + The import command will (a) detect the new transactions, and (b) +append just those transactions to your main journal. It is idempotent, +so you don't have to remember how many times you ran it or with which +version of the CSV. (It keeps state in a hidden '.latest.FILE.csv' +file.) This is the easiest way to import CSV data. Eg: + +# download the latest CSV files, then run this command. +# Note, no -f flags needed here. +$ hledger import *.csv [--dry] + + This method works for most CSV files. (Where records have a stable +chronological order, and new records appear only at the new end.) + + A number of other tools and workflows, hledger-specific and +otherwise, exist for converting, deduplicating, classifying and managing +CSV data. See: + + * https://hledger.org/cookbook.html#setups-and-workflows + * https://plaintextaccounting.org -> data import/conversion + + +File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV + +10.18.9 Setting amounts +----------------------- + +Continuing from amount field above, here are more tips for +amount-setting: + + 1. *If the amount is in a single CSV field:* + + a. *If its sign indicates direction of flow:* + Assign it to 'amountN', to set the Nth posting's amount. N is + usually 1 or 2 but can go up to 99. + + b. *If another field indicates direction of flow:* + Use one or more conditional rules to set the appropriate + amount sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. *If the amount is in two CSV fields (such as Debit and Credit, or + In and Out):* + + a. *If both fields are unsigned:* + Assign one field to 'amountN-in' and the other to + 'amountN-out'. hledger will automatically negate the "out" + field, and will use whichever field value is non-zero as + posting N's amount. + + b. *If either field is signed:* + You will probably need to override hledger's sign for one or + the other field, as in the following example: + + # Negate the -out value, but only if it is not empty: + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields can contain a non-zero value (or both can be + empty):* + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such + as '1' and 'none'. For such cases, use conditional rules to + help select the amount. Eg, to handle the above you could + select the value containing non-zero digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. *If you want posting 2's amount converted to cost:* + Use the unnumbered 'amount' (or 'amount-in' and 'amount-out') + syntax. + + 4. *If the CSV has only balance amounts, not transaction amounts:* + Assign to 'balanceN', to set a balance assignment on the Nth + posting, causing the posting's amount to be calculated + automatically. 'balance' with no number is equivalent to + 'balance1'. In this situation hledger is more likely to guess the + wrong default account name, so you may need to set that explicitly. + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV + +10.18.10 Amount signs +--------------------- + +There is some special handling making it easier to parse and to reverse +amount signs. (This only works for whole amounts, not for cost amounts +such as COST in 'amount1 AMT @ COST'): + + * *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 '""'. + + It's not possible (without preprocessing the CSV) to set an amount to +its absolute value, ie discard its sign. + + +File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV + +10.18.11 Setting currency/commodity +----------------------------------- + +If the currency/commodity symbol is included in the CSV's amount +field(s): + +2023-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 + +2023-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + +2023-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 + +2023-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 + +2023-01-01 foo + expenses:unknown 123.00 USD + income:unknown -123.00 USD + + Note we used a temporary field name ('cur') that is not 'currency' - +that would trigger the prepending effect, which we don't want here. + + +File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV + +10.18.12 Amount decimal places +------------------------------ + +Like amounts in a journal file, the amounts generated by CSV rules like +'amount1' influence commodity display styles, such as the number of +decimal places displayed in reports. + + The original amounts as written in the CSV file do not affect display +style (because we don't yet reliably know their commodity). + + +File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV + +10.18.13 Referencing other fields +--------------------------------- + +In field assignments, you can interpolate only CSV fields, not hledger +fields. In the example below, there's both a CSV field and a hledger +field named amount1, but %amount1 always means the CSV field, not the +hledger field: + +# Name the third CSV field "amount1" +fields date,description,amount1 + +# Set hledger's amount1 to the CSV amount1 field followed by USD +amount1 %amount1 USD + +# Set comment to the CSV amount1 (not the amount1 assigned above) +comment %amount1 + + Here, since there's no CSV amount1 field, %amount1 will produce a +literal "amount1": + +fields date,description,csvamount +amount1 %csvamount USD +# Can't interpolate amount1 here +comment %amount1 + + When there are multiple field assignments to the same hledger field, +only the last one takes effect. Here, comment's value will be be B, or +C if "something" is matched, but never A: + +comment A +comment B +if something + comment C + + +File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV + +10.18.14 How CSV rules are evaluated +------------------------------------ + +Here's how to think of CSV rules being evaluated (if you really need +to). First, + + * 'include' - all includes are inlined, from top to bottom, depth + first. (At each include point the file is inlined and scanned for + further includes, recursively, before proceeding.) + + Then "global" rules are evaluated, top to bottom. If a rule is +repeated, the last one wins: + + * 'skip' (at top level) + * 'date-format' + * 'newest-first' + * 'fields' - names the CSV fields, optionally sets up initial + assignments to hledger fields + + Then for each CSV record in turn: + + * test all 'if' blocks. If any of them contain a 'end' rule, skip + all remaining CSV records. Otherwise if any of them contain a + 'skip' rule, skip that many CSV records. If there are multiple + matched 'skip' rules, the first one wins. + * collect all field assignments at top level and in matched 'if' + blocks. When there are multiple assignments for a field, keep only + the last one. + * compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELD references), or a + default + * generate a hledger transaction (journal entry) from these values. + + This is all part of the CSV reader, one of several readers hledger +can use to parse input files. When all files have been read +successfully, the transactions are passed as input to whichever hledger +command the user specified. + + +File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV + +10.18.15 Well factored rules +---------------------------- + +Some things than can help reduce duplication and complexity in rules +files: + + * Extracting common rules usable with multiple CSV files into a + 'common.rules', and adding 'include common.rules' to each CSV's + rules file. + + * Splitting if blocks into smaller if blocks, extracting the + frequently used parts. + + +File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV + +10.19 CSV rules examples +======================== + +* Menu: + +* Bank of Ireland:: +* Coinbase:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples + +10.19.1 Bank of Ireland +----------------------- + +Here's a CSV with two amount fields (Debit and Credit), and a balance +field, which we can use to add balance assertions, which is not +necessary but provides extra error checking: + +Date,Details,Debit,Credit,Balance +07/12/2012,LODGMENT 529898,,10.0,131.21 +07/12/2012,PAYMENT,5,,126 + +# bankofireland-checking.csv.rules + +# skip the header line +skip + +# name the csv fields, and assign some of them as journal entry fields +fields date, description, amount-out, amount-in, balance + +# We generate balance assertions by assigning to "balance" +# above, but you may sometimes need to remove these because: +# +# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience +# +# - it is sometimes calculated based on non-chronological ordering, +# eg when multiple transactions clear on the same day + +# date is in UK/Ireland format +date-format %d/%m/%Y + +# set the currency +currency EUR + +# set the base account for all txns +account1 assets:bank:boi:checking + +$ hledger -f bankofireland-checking.csv print +2012-12-07 LODGMENT 529898 + assets:bank:boi:checking EUR10.0 = EUR131.2 + income:unknown EUR-10.0 + +2012-12-07 PAYMENT + assets:bank:boi:checking EUR-5.0 = EUR126.0 + expenses:unknown EUR5.0 + + The balance assertions don't raise an error above, because we're +reading directly from CSV, but they will be checked if these entries are +imported into a journal file. + + +File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples + +10.19.2 Coinbase +---------------- + +A simple example with some CSV from Coinbase. The spot price is +recorded using cost notation. The legacy 'amount' field name +conveniently sets amount 2 (posting 2's amount) to the total cost. + +# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes +# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + +# coinbase.csv.rules +skip 1 +fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes +date %Timestamp +date-format %Y-%m-%dT%T%Z +description %Notes +account1 assets:coinbase:cc +amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + +$ hledger print -f coinbase.csv +2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + +File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples + +10.19.3 Amazon +-------------- + +Here we convert amazon.com order history, and use an if block to +generate a third posting if there's a fee. (In practice you'd probably +get this data from your bank instead, but it's an example.) + +"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" +"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" +"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" + +# amazon-orders.csv.rules + +# skip one header line +skip 1 + +# name the csv fields, and assign the transaction's date, amount and code. +# Avoided the "status" and "amount" hledger field names to prevent confusion. +fields date, _, toorfrom, name, amzstatus, amzamount, fees, code + +# how to parse the date +date-format %b %-d, %Y + +# combine two fields to make the description +description %toorfrom %name + +# save the status as a tag +comment status:%amzstatus + +# set the base account for all transactions +account1 assets:amazon +# leave amount1 blank so it can balance the other(s). +# I'm assuming amzamount excludes the fees, don't remember + +# set a generic account2 +account2 expenses:misc +amount2 %amzamount +# and maybe refine it further: +#include categorisation.rules + +# add a third posting for fees, but only if they are non-zero. +if %fees [1-9] + account3 expenses:fees + amount3 %fees + +$ hledger -f amazon-orders.csv print +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed + assets:amazon + expenses:misc $20.00 + +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed + assets:amazon + expenses:misc $25.00 + expenses:fees $1.00 + + +File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples + +10.19.4 Paypal +-------------- + +Here's a real-world rules file for (customised) Paypal CSV, with some +Paypal-specific rules, and a second rules file included: + +"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" +"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" +"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" +"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" +"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" +"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" +"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" +"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" + +# paypal-custom.csv.rules + +# Tips: +# Export from Activity -> Statements -> Custom -> Activity download +# Suggested transaction type: "Balance affecting" +# Paypal's default fields in 2018 were: +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" +# This rules file assumes the following more detailed fields, configured in "Customize report fields": +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" + +fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note + +skip 1 + +date-format %-m/%-d/%Y + +# ignore some paypal events +if +In Progress +Temporary Hold +Update to + skip + +# add more fields to the description +description %description_ %itemtitle + +# save some other fields as tags +comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ + +# convert to short currency symbols +if %currency USD + currency $ +if %currency EUR + currency E +if %currency GBP + currency P + +# generate postings + +# the first posting will be the money leaving/entering my paypal account +# (negative means leaving my account, in all amount fields) +account1 assets:online:paypal +amount1 %netamount + +# the second posting will be money sent to/received from other party +# (account2 is set below) +amount2 -%grossamount + +# if there's a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] + account3 expenses:banking:paypal + amount3 -%feeamount + comment3 business: + +# choose an account for the second posting + +# override the default account names: +# if the amount is positive, it's income (a debit) +if %grossamount ^[^-] + account2 income:unknown +# if negative, it's an expense (a credit) +if %grossamount ^- + account2 expenses:unknown + +# apply common rules for setting account2 & other tweaks +include common.rules + +# apply some overrides specific to this csv + +# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case. +if +Bank Account +Bank Deposit to PP Account + description %type for %referencetxnid %itemtitle + account2 assets:bank:wf:pchecking + account1 assets:online:paypal + +# Currency conversions +if Currency Conversion + account2 equity:currency conversion + +# common.rules + +if +darcs +noble benefactor + account2 revenues:foss donations:darcshub + comment2 business: + +if +Calm Radio + account2 expenses:online:apps + +if +electronic frontier foundation +Patreon +wikimedia +Advent of Code + account2 expenses:dues + +if Google + account2 expenses:online:apps + description google | music + +$ hledger -f paypal-custom.csv print +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed + assets:online:paypal $-6.99 = $-6.99 + expenses:online:apps $6.99 + +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $6.99 = $0.00 + assets:bank:wf:pchecking $-6.99 + +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed + assets:online:paypal $-7.00 = $-7.00 + expenses:dues $7.00 + +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $7.00 = $0.00 + assets:bank:wf:pchecking $-7.00 + +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed + assets:online:paypal $-2.00 = $-2.00 + expenses:dues $2.00 + expenses:banking:paypal ; business: + +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $2.00 = $0.00 + assets:bank:wf:pchecking $-2.00 + +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed + assets:online:paypal $9.41 = $9.41 + revenues:foss donations:darcshub $-10.00 ; business: + expenses:banking:paypal $0.59 ; business: + + +File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top + +11 Timeclock +************ + +The time logging format of timeclock.el, as read by hledger. + + hledger can read time logs in timeclock format. As with Ledger, +these are (a subset of) timeclock.el's format, containing clock-in and +clock-out entries as in the example below. The date is a simple date. +The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are +optional. The timezone, if present, must be four digits and is ignored +(currently the time is always interpreted as a local time). Lines +beginning with '#' or ';' or '*', and blank lines, are ignored. + +i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: +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 2 spaces ; optional comment, tags: + (some account) 0.33h + +2015-03-31 * 22:21-23:59 + (another:account) 1.64h + +2015-04-01 * 00:00-02:00 + (another:account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + +$ hledger -f sample.timeclock balance # current time balances +$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + * use emacs and the built-in timeclock.el, or the extended + timeclock-x.el and perhaps the extras in ledgerutils.el + + * at the command line, use these bash aliases: 'shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' + + * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + +File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top + +12 Timedot +********** + +'timedot' format is hledger's human-friendly time logging format. +Compared to 'timeclock' format, it is more convenient for quick, +approximate, and retroactive time logging, and more human-readable (you +can see at a glance where time was spent). A quick example: + +2023-05-01 +hom:errands .... .... ; two hours; the space is ignored +fos:hledger:timedot .. ; half an hour +per:admin:finance ; no time spent yet + + hledger reads this as a transaction on this day with three +(unbalanced) postings, where each dot represents "0.25". No commodity +symbol is assumed, but we typically interpret it as hours. + +$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required +2023-05-01 * + (hom:errands) 2.00 ; two hours + (fos:hledger:timedot) 0.50 ; half an hour + (per:admin:finance) 0 + + A timedot file contains a series of transactions (usually one per +day). Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D), +optionally be followed on the same line by a transaction description, +and/or a transaction comment following a semicolon. + + After the date line are zero or more time postings, consisting of: + + * *An account name* - any hledger-style account name, optionally + indented. + + * *Two or more spaces* - required if there is an amount (as in + journal format). + + * *A timedot amount*, which can be + + * empty (representing zero) + + * a number, optionally followed by a unit 's', 'm', 'h', 'd', + 'w', 'mo', or 'y', representing a precise number of seconds, + minutes, hours, days weeks, months or years (hours is assumed + by default), which will be converted to hours according to 60s + = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. + + * one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can + be used for grouping/alignment. + + * one or more letters. These are like dots but they also + generate a tag 't:' (short for "type") with the letter as its + value, and a separate posting for each of the values. This + provides a second dimension of categorisation, viewable in + reports with '--pivot t'. + + * *An optional comment* following a semicolon (a hledger-style + posting comment). + + There is some flexibility to help with keeping time log data and +notes in the same file: + + * Blank lines and lines beginning with '#' or ';' are ignored. + + * After the first date line, lines which do not contain a double + space are parsed as postings with zero amount. (hledger's register + reports will show these if you add -E). + + * Before the first date line, lines beginning with '*' (eg org + headings) are ignored. And from the first date line onward, Emacs + org mode heading prefixes at the start of lines (one or more '*''s + followed by a space) will be ignored. This means the time log can + also be a org outline. + +* Menu: + +* Timedot examples:: + + +File: hledger.info, Node: Timedot examples, Up: Timedot + +12.1 Timedot examples +===================== + +Numbers: + +2016/2/3 +inc:client1 4 +fos:hledger 3h +biz:research 60m + + Dots: + +# 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 . + +$ 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 + + Letters: + +# Activity types: +# c cleanup/catchup/repair +# e enhancement +# s support +# l learning/research + +2023-11-01 +work:adm ccecces + +$ hledger -f a.timedot print +2023-11-01 + (work:adm) 1 ; t:c + (work:adm) 0.5 ; t:e + (work:adm) 0.25 ; t:s + +$ hledger -f a.timedot bal + 1.75 work:adm +-------------------- + 1.75 + +$ hledger -f a.timedot bal --pivot t + 1.00 c + 0.50 e + 0.25 s +-------------------- + 1.75 + + Org: + +* 2023 Work Diary +** Q1 +*** 2023-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 + + Using '.' as account name separator: + +2016/2/4 +fos.hledger.timedot 4h +fos.ledger .. + +$ hledger -f a.timedot --alias '/\./=:' bal -t + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +-------------------- + 4.50 + + +File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Amount formatting parseability, Prev: Timedot, Up: Top + +13 PART 3: REPORTING CONCEPTS +***************************** + + +File: hledger.info, Node: Amount formatting parseability, Next: Time periods, Prev: PART 3 REPORTING CONCEPTS, Up: Top + +14 Amount formatting, parseability +********************************** + +If you're wondering why your 'print' report sometimes shows trailing +decimal marks, with no decimal digits; it does this when showing amounts +that have digit group marks but no decimal digits, to disambiguate them +and allow them to be re-parsed reliably (see also Decimal marks, digit +group marks. Eg: + +commodity $1,000.00 + +2023-01-02 + (a) $1000 + +$ hledger print +2023-01-02 + (a) $1,000. + + If this is a problem (eg when exporting to Ledger), you can avoid it +by disabling digit group marks, eg with -c/-commodity (for each affected +commodity): + +$ hledger print -c '$1000.00' +2023-01-02 + (a) $1000 + + or by forcing print to always show decimal digits, with -round: + +$ hledger print -c '$1,000.00' --round=soft +2023-01-02 + (a) $1,000.00 + + More generally: hledger output falls into three rough categories, +which format amounts a little bit differently to suit different +consumers: + + *1. "hledger-readable output" - should be readable by hledger (and +by humans)* + + * This is produced by reports that show full journal entries: + 'print', 'import', 'close', 'rewrite' etc. + * It shows amounts with their original journal precisions, which may + not be consistent. + * It adds a trailing decimal mark when needed to avoid showing + ambiguous amounts. + * It can be parsed reliably (by hledger and ledger2beancount at + least, but perhaps not by Ledger..) + + *2. "human-readable output" - usually for humans* + + * This is produced by all other reports. + * It shows amounts with standard display precisions, which will be + consistent within each commodity. + * It shows ambiguous amounts unmodified. + * It can be parsed reliably in the context of a known report (when + you know decimals are consistently not being shown, you can assume + a single mark is a digit group mark). + + *3. "machine-readable output" - usually for other software* + + * This is produced by all reports when an output format like 'csv', + 'tsv', 'json', or 'sql' is selected. + * It shows amounts as 1 or 2 do, but without digit group marks. + * It can be parsed reliably (if needed, the decimal mark can be + changed with -c/-commodity-style). + + +File: hledger.info, Node: Time periods, Next: Depth, Prev: Amount formatting parseability, Up: Top + +15 Time periods +*************** + +* Menu: + +* Report start & end date:: +* Smart dates:: +* Report intervals:: +* Date adjustment:: +* Period expressions:: + + +File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods + +15.1 Report start & end date +============================ + +By default, most hledger reports will show the full span of time +represented by the journal. The report start date will be the earliest +transaction or posting date, and the report end date will be the latest +transaction, posting, or market price date. + + Often you will want to see a shorter time span, such as the current +month. You can specify a start and/or end date using '-b/--begin', +'-e/--end', '-p/--period' or a 'date:' query (described below). All of +these accept the smart date syntax (below). + + Some notes: + + * End dates are exclusive, as in Ledger, so you should write the date + _after_ the last day you want to see in the report. + * As noted in reporting options: among start/end dates specified with + _options_, the last (i.e. right-most) option takes precedence. + * The effective report start and end dates are the intersection of + the start/end dates from options and that from 'date:' queries. + That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January + 2019, the smallest common time span. + * In some cases a report interval will adjust start/end dates to fall + on interval boundaries (see below). + + Examples: + +'-b begin on St. Patrick's day 2016 +2016/3/17' +'-e 12/1' end at the start of december 1st of the current year + (11/30 will be the last date included) +'-b all transactions on or after the 1st of the current month +thismonth' +'-p all transactions in the current month +thismonth' +'date:2016/3/17..'the above written as queries instead ('..' can also be + replaced with '-') +'date:..12/1' +'date:thismonth..' +'date:thismonth' + + +File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods + +15.2 Smart dates +================ + +hledger's user interfaces accept a "smart date" syntax for added +convenience. Smart dates optionally can be relative to today's date, be +written with english words, and have less-significant parts omitted +(missing parts are inferred as 1). Some examples: + +'2004/10/1', exact date, several separators allowed. Year +'2004-01-01', is 4+ digits, month is 1-12, day is 1-31 +'2004.9.1' +'2004' start of year +'2004/10' start of month +'10/1' month and day in current year +'21' day in current month +'october, oct' start of month in current year +'yesterday, today, -1, 0, 1 days from today +tomorrow' +'last/this/next -1, 0, 1 periods from the current period +day/week/month/quarter/year' +'in n n periods from the current period +days/weeks/months/quarters/years' +'n n periods from the current period +days/weeks/months/quarters/years +ahead' +'n -n periods from the current period +days/weeks/months/quarters/years +ago' +'20181201' 8 digit YYYYMMDD with valid year month and + day +'201812' 6 digit YYYYMM with valid year and month + + Some counterexamples - malformed digit sequences might give +surprising results: + +'201813' 6 digits with an invalid month is parsed as start of + 6-digit year +'20181301' 8 digits with an invalid month is parsed as start of + 8-digit year +'20181232' 8 digits with an invalid day gives an error +'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error + + "Today's date" can be overridden with the '--today' option, in case +it's needed for testing or for recreating old reports. (Except for +periodic transaction rules, which are not affected by '--today'.) + + +File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods + +15.3 Report intervals +===================== + +A report interval can be specified so that reports like register, +balance or activity become multi-period, showing each subperiod as a +separate row or column. + + The following standard intervals can be enabled with command-line +flags: + + * '-D/--daily' + * '-W/--weekly' + * '-M/--monthly' + * '-Q/--quarterly' + * '-Y/--yearly' + + More complex intervals can be specified using '-p/--period', +described below. + + +File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods + +15.4 Date adjustment +==================== + +When there is a report interval (other than daily), report start/end +dates which have been inferred, eg from the journal, are automatically +adjusted to natural period boundaries. This is convenient for producing +simple periodic reports. More precisely: + + * an inferred start date will be adjusted earlier if needed to fall + on a natural period boundary + + * an inferred end date will be adjusted later if needed to make the + last period the same length as the others. + + By contrast, start/end dates which have been specified explicitly, +with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger +1.29). This makes it possible to specify non-standard report periods, +but it also means that if you are specifying a start date, you should +pick one that's on a period boundary if you want to see simple report +period headings. + + +File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods + +15.5 Period expressions +======================= + +The '-p/--period' option specifies a period expression, which is a +compact way of expressing a start date, end date, and/or report +interval. + + Here's a period expression with a start and end date (specifying the +first quarter of 2009): + +'-p "from 2009/1/1 to 2009/4/1"' + + Several keywords like "from" and "to" are supported for readability; +these are optional. "to" can also be written as ".." or "-". The +spaces are also optional, as long as you don't run two dates together. +So the following are equivalent to the above: + +'-p "2009/1/1 2009/4/1"' +'-p2009/1/1to2009/4/1' +'-p2009/1/1..2009/4/1' + + Dates are smart dates, so if the current year is 2009, these are also +equivalent to the above: + +'-p "1/1 4/1"' +'-p "jan-apr"' +'-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction date in the journal: + +'-p "from 2009/1/1"' everything after january 1, 2009 +'-p "since 2009/1"' the same, since is a synonym +'-p "from 2009"' the same +'-p "to 2009"' everything before january 1, 2009 + + You can also specify a period by writing a single partial or full +date: + +'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” +'-p "2009/1"' the month of january 2009; equivalent to “2009/1/1 to + 2009/2/1” +'-p the first day of 2009; equivalent to “2009/1/1 to +"2009/1/1"' 2009/1/2” + + or by using the "Q" quarter-year syntax (case insensitive): + +'-p "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to + 2009/4/1” +'-p "q4"' fourth quarter of the current year + +* Menu: + +* Period expressions with a report interval:: +* More complex report intervals:: +* Multiple weekday intervals:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +15.5.1 Period expressions with a report interval +------------------------------------------------ + +A period expression can also begin with a report interval, separated +from the start/end dates (if any) by a space or the word 'in': + +'-p "weekly from 2009/1/1 to 2009/4/1"' +'-p "monthly in 2008"' +'-p "quarterly"' + + +File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions + +15.5.2 More complex report intervals +------------------------------------ + +Some more complex intervals can be specified within period expressions, +such as: + + * 'biweekly' (every two weeks) + * 'fortnightly' + * 'bimonthly' (every two months) + * 'every day|week|month|quarter|year' + * 'every N days|weeks|months|quarters|years' + + Weekly on a custom day: + + * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted + after the number) + * 'every WEEKDAYNAME' (full or three-letter english weekday name, + case insensitive) + + Monthly on a custom day: + + * 'every Nth day [of month]' + * 'every Nth WEEKDAYNAME [of month]' + + Yearly on a custom day: + + * 'every MM/DD [of year]' (month number and day of month number) + * 'every MONTHNAME DDth [of year]' (full or three-letter english + month name, case insensitive, and day of month number) + * 'every DDth MONTHNAME [of year]' (equivalent to the above) + + Examples: + +'-p "bimonthly from +2008"' +'-p "every 2 weeks"' +'-p "every 5 months from +2009/03"' +'-p "every 2nd day of periods will go from Tue to Tue +week"' +'-p "every Tue"' same +'-p "every 15th day"' period boundaries will be on 15th of each + month +'-p "every 2nd Monday"' period boundaries will be on second Monday + of each month +'-p "every 11/05"' yearly periods with boundaries on 5th of + November +'-p "every 5th November"' same +'-p "every Nov 5th"' same + + Show historical balances at end of the 15th day of each month (N is +an end date, exclusive as always): + +$ hledger balance -H -p "every 16th day" + + Group postings from the start of wednesday to end of the following +tuesday (N is both (inclusive) start date and (exclusive) end date): + +$ hledger register checking -p "every 3rd day of week" + + +File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions + +15.5.3 Multiple weekday intervals +--------------------------------- + +This special form is also supported: + + * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english + weekday names, case insensitive) + + Also, 'weekday' and 'weekendday' are shorthand for +'mon,tue,wed,thu,fri' and 'sat,sun'. + + This is mainly intended for use with '--forecast', to generate +periodic transactions on arbitrary days of the week. It may be less +useful with '-p', since it divides each week into subperiods of unequal +length, which is unusual. (Related: #1632) + + Examples: + +'-p "every dates will be Mon, Wed, Fri; periods will be +mon,wed,fri"' Mon-Tue, Wed-Thu, Fri-Sun +'-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will +weekday"' be Mon, Tue, Wed, Thu, Fri-Sun +'-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri +weekendday"' + + +File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top + +16 Depth +******** + +With the '--depth NUM' option (short form: '-NUM'), reports will show +accounts only to the specified depth, hiding deeper subaccounts. Use +this when you want a summary with less detail. This flag has the same +effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are +equivalent. + + +File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top + +17 Queries +********** + +One of hledger's strengths is being able to quickly report on a precise +subset of your data. Most hledger commands accept optional query +arguments to restrict their scope. The syntax is as follows: + + * Zero or more space-separated query terms. These are most often + account name substrings: + + 'utilities food:groceries' + + * Terms with spaces or other special characters should be enclosed in + quotes: + + '"personal care"' + + * Regular expressions are also supported: + + '"^expenses\b"' + '"accounts (payable|receivable)"' + + * Add a query type prefix to match other parts of the data: + + 'date:202312-' + 'status:' + 'desc:amazon' + 'cur:USD' + '"amt:>0"' + + * Add a 'not:' prefix to negate: + + 'not:cur:USD' + + * Multiple unlike terms are AND-ed, multiple like terms are OR-ed + + 'date:2022 desc:amazon desc:amzn' + (all transactions with "amazon" or "amzn" in description during + 2022) + +* Menu: + +* Query types:: +* Combining query terms:: +* Queries and command options:: +* Queries and valuation:: +* Querying with account aliases:: +* Querying with cost or value:: + + +File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries + +17.1 Query types +================ + +Here are the types of query term available. Remember these can also be +prefixed with *'not:'* to convert them into a negative match. + + *'acct:REGEX', 'REGEX'* +Match account names containing this (case insensitive) regular +expression. This is the default query type when there is no prefix, and +regular expression syntax is typically not needed, so usually we just +write an account name substring, like 'expenses' or 'food'. + + *'amt:N, amt:N, amt:>=N'* +Match postings with a single-commodity amount equal to, less than, or +greater than N. (Postings with multi-commodity amounts are not tested +and will always match.) The comparison has two modes: if N is preceded +by a + or - sign (or is 0), the two signed numbers are compared. +Otherwise, the absolute magnitudes are compared, ignoring sign. + + *'code:REGEX'* +Match by transaction code (eg check number). + + *'cur:REGEX'* +Match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. (For a partial +match, use '.*REGEX.*'). Note, to match special characters which are +regex-significant, you need to escape them with '\'. And for characters +which are significant to your shell you may need one more level of +escaping. So eg to match the dollar sign: +'hledger print cur:\\$'. + + *'desc:REGEX'* +Match transaction descriptions. + + *'date:PERIODEXPR'* +Match dates (or with the '--date2' flag, secondary dates) within the +specified period. PERIODEXPR is a period expression with no report +interval. Examples: +'date:2016', 'date:thismonth', 'date:2/1-2/15', +'date:2021-07-27..nextquarter'. + + *'date2:PERIODEXPR'* +Match secondary dates within the specified period (independent of the +'--date2' flag). + + *'depth:N'* +Match (or display, depending on command) accounts at or above this +depth. + + *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg) +Match with a boolean combination of queries (which must be enclosed in +quotes). See Combining query terms below. + + *'note:REGEX'* +Match transaction notes (the part of the description right of '|', or +the whole description if there's no '|'). + + *'payee:REGEX'* +Match transaction payee/payer names (the part of the description left of +'|', or the whole description if there's no '|'). + + *'real:, real:0'* +Match real or virtual postings respectively. + + *'status:, status:!, status:*'* +Match unmarked, pending, or cleared transactions respectively. + + *'type:TYPECODES'* +Match by account type (see Declaring accounts > Account types). +'TYPECODES' is one or more of the single-letter account type codes +'ALERXCV', case insensitive. Note 'type:A' and 'type:E' will also match +their respective subtypes 'C' (Cash) and 'V' (Conversion). Certain +kinds of account alias can disrupt account types, see Rewriting accounts +> Aliases and account types. + + *'tag:REGEX[=REGEX]'* +Match by tag name, and optionally also by tag value. (To match only by +value, use 'tag:.=REGEX'.) + + When querying by tag, note that: + + * Accounts also inherit the tags of their parent accounts + * Postings also inherit the tags of their account and their + transaction + * Transactions also acquire the tags of their postings. + + (*'inacct:ACCTNAME'* +A special query term used automatically in hledger-web only: tells +hledger-web to show the transaction register for an account.) + + +File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries + +17.2 Combining query terms +========================== + +When given multiple space-separated query terms, most commands select +things which match: + + * any of the description terms AND + * any of the account terms AND + * any of the status terms AND + * all the other terms. + + The print command is a little different, showing transactions which: + + * match any of the description terms AND + * have any postings matching any of the positive account terms AND + * have no postings matching any of the negative account terms AND + * match all the other terms. + + We also support more complex boolean queries with the 'expr:' prefix. +This allows one to combine queries using one of three operators: AND, +OR, and NOT, where NOT is different syntax for 'not:'. + + Examples of such queries are: + + * Match transactions with 'cool' in the description AND with the 'A' + tag + + 'expr:"desc:cool AND tag:A"' + + * Match transactions NOT to the 'expenses:food' account OR with the + 'A' tag + + 'expr:"NOT expenses:food OR tag:A"' + + * Match transactions NOT involving the 'expenses:food' account OR + with the 'A' tag AND involving the 'expenses:drink' account. (the + AND is implicitly added by space-separation, following the rules + above) + + 'expr:"expenses:food OR (tag:A expenses:drink)"' + + +File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries + +17.3 Queries and command options +================================ + +Some queries can also be expressed as command-line options: 'depth:2' is +equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. +When you mix command options and query arguments, generally the +resulting query is their intersection. + + +File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries + +17.4 Queries and valuation +========================== + +When amounts are converted to other commodities in cost or value +reports, 'cur:' and 'amt:' match the old commodity symbol and the old +amount quantity, not the new ones (except in hledger 1.22.0 where it's +reversed, see #1625). + + +File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries + +17.5 Querying with account aliases +================================== + +When account names are rewritten with '--alias' or 'alias', note that +'acct:' will match either the old or the new account name. + + +File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries + +17.6 Querying with cost or value +================================ + +When amounts are converted to other commodities in cost or value +reports, note that 'cur:' matches the new commodity symbol, and not the +old one, and 'amt:' matches the new quantity, and not the old one. +Note: this changed in hledger 1.22, previously it was the reverse, see +the discussion at #1625. + + +File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top + +18 Pivoting +*********** + +Normally, hledger groups and sums amounts within each account. The +'--pivot FIELD' option substitutes some other transaction field for +account names, causing amounts to be grouped and summed by that field's +value instead. FIELD can be any of the transaction fields 'acct', +'status', 'code', 'desc', 'payee', 'note', or a tag name. When pivoting +on a tag and a posting has multiple values of that tag, only the first +value is displayed. Values containing 'colon:separated:parts' will be +displayed hierarchically, like account names. Multiple, colon-delimited +fields can be pivoted simultaneously, generating a hierarchical account +name. + + Some examples: + +2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe, kind: Lifetime + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + Hierarchical reports can be generated with multiple pivots: + +$ hledger balance Income:Dues --pivot kind:member + -2 EUR Lifetime:John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top + +19 Generating data +****************** + +hledger has several features for generating data, such as: + + * Periodic transaction rules can generate single or repeating + transactions following a template. These are usually dated in the + future, eg to help with forecasting. They are activated by the + '--forecast' option. + + * The balance command's '--budget' option uses these same periodic + rules to generate goals for the budget report. + + * Auto posting rules can generate extra postings on certain matched + transactions. They are always applied to forecast transactions; + with the '--auto' flag they are applied to transactions recorded in + the journal as well. + + * The '--infer-equity' flag infers missing conversion equity postings + from @/@@ costs. And the inverse '--infer-costs' flag infers + missing @/@@ costs from conversion equity postings. + + Generated data of this kind is temporary, existing only at report +time. But you can see it in the output of 'hledger print', and you can +save that to your journal, in effect converting it from temporary +generated data to permanent recorded data. This could be useful as a +data entry aid. + + If you are wondering what data is being generated and why, add the +'--verbose-tags' flag. In 'hledger print' output you will see extra +tags like 'generated-transaction', 'generated-posting', and 'modified' +on generated/modified data. Also, even without '--verbose-tags', +generated data always has equivalen hidden tags (with an underscore +prefix), so eg you could match generated transactions with +'tag:_generated-transaction'. + + +File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top + +20 Forecasting +************** + +Forecasting, or speculative future reporting, can be useful for +estimating future balances, or for exploring different future scenarios. + + The simplest and most flexible way to do it with hledger is to +manually record a bunch of future-dated transactions. You could keep +these in a separate 'future.journal' and include that with '-f' only +when you want to see them. + +* Menu: + +* --forecast:: +* Inspecting forecast transactions:: +* Forecast reports:: +* Forecast tags:: +* Forecast period in detail:: +* Forecast troubleshooting:: + + +File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting + +20.1 -forecast +============== + +There is another way: with the '--forecast' option, hledger can generate +temporary "forecast transactions" for reporting purposes, according to +periodic transaction rules defined in the journal. Each rule can +generate multiple recurring transactions, so by changing one rule you +can change many forecasted transactions. (These same rules can also +generate budget goals, described in Budgeting.) + + Forecast transactions usually start after ordinary transactions end. +By default, they begin after your latest-dated ordinary transaction, or +today, whichever is later, and they end six months from today. (The +exact rules are a little more complicated, and are given below.) + + This is the "forecast period", which need not be the same as the +report period. You can override it - eg to forecast farther into the +future, or to force forecast transactions to overlap your ordinary +transactions - by giving the -forecast option a period expression +argument, like '--forecast=..2099' or '--forecast=2023-02-15..'. Note +that the '=' is required. + + +File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting + +20.2 Inspecting forecast transactions +===================================== + +'print' is the best command for inspecting and troubleshooting forecast +transactions. Eg: + +~ monthly from 2022-12-20 rent + assets:bank:checking + expenses:rent $1000 + +$ hledger print --forecast --today=2023/4/21 +2023-05-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-06-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-07-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-08-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-09-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + Here there are no ordinary transactions, so the forecasted +transactions begin on the first occurence after today's date. (You +won't normally use '--today'; it's just to make these examples +reproducible.) + + +File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting + +20.3 Forecast reports +===================== + +Forecast transactions affect all reports, as you would expect. Eg: + +$ hledger areg rent --forecast --today=2023/4/21 +Transactions in expenses:rent and subaccounts: +2023-05-20 rent as:ba:checking $1000 $1000 +2023-06-20 rent as:ba:checking $1000 $2000 +2023-07-20 rent as:ba:checking $1000 $3000 +2023-08-20 rent as:ba:checking $1000 $4000 +2023-09-20 rent as:ba:checking $1000 $5000 + +$ hledger bal -M expenses --forecast --today=2023/4/21 +Balance changes in 2023-05-01..2023-09-30: + + || May Jun Jul Aug Sep +===============++=================================== + expenses:rent || $1000 $1000 $1000 $1000 $1000 +---------------++----------------------------------- + || $1000 $1000 $1000 $1000 $1000 + + +File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting + +20.4 Forecast tags +================== + +Forecast transactions generated by -forecast have a hidden tag, +'_generated-transaction'. So if you ever need to match forecast +transactions, you could use 'tag:_generated-transaction' (or just +'tag:generated') in a query. + + For troubleshooting, you can add the '--verbose-tags' flag. Then, +visible 'generated-transaction' tags will be added also, so you can view +them with the 'print' command. Their value indicates which periodic +rule was responsible. + + +File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting + +20.5 Forecast period, in detail +=============================== + +Forecast start/end dates are chosen so as to do something useful by +default in almost all situations, while also being flexible. Here are +(with luck) the exact rules, to help with troubleshooting: + + The forecast period starts on: + + * the later of + * the start date in the periodic transaction rule + * the start date in '--forecast''s argument + + * otherwise (if those are not available): the later of + * the report start date specified with '-b'/'-p'/'date:' + * the day after the latest ordinary transaction in the journal + + * otherwise (if none of these are available): today. + + The forecast period ends on: + + * the earlier of + * the end date in the periodic transaction rule + * the end date in '--forecast''s argument + + * otherwise: the report end date specified with '-e'/'-p'/'date:' + * otherwise: 180 days (~6 months) from today. + + +File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting + +20.6 Forecast troubleshooting +============================= + +When -forecast is not doing what you expect, one of these tips should +help: + + * Remember to use the '--forecast' option. + * Remember to have at least one periodic transaction rule in your + journal. + * Test with 'print --forecast'. + * Check for typos or too-restrictive start/end dates in your periodic + transaction rule. + * Leave at least 2 spaces between the rule's period expression and + description fields. + * Check for future-dated ordinary transactions suppressing forecasted + transactions. + * Try setting explicit report start and/or end dates with '-b', '-e', + '-p' or 'date:' + * Try adding the '-E' flag to encourage display of empty periods/zero + transactions. + * Try setting explicit forecast start and/or end dates with + '--forecast=START..END' + * Consult Forecast period, in detail, above. + * Check inside the engine: add '--debug=2' (eg). + + +File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top + +21 Budgeting +************ + +With the balance command's '--budget' report, each periodic transaction +rule generates recurring budget goals in specified accounts, and goals +and actual performance can be compared. See the balance command's doc +below. + + You can generate budget goals and forecast transactions at the same +time, from the same or different periodic transaction rules: 'hledger +bal -M --budget --forecast ...' + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Budgeting, Up: Top + +22 Cost reporting +***************** + +In some transactions - for example a currency conversion, or a purchase +or sale of stock - one commodity is exchanged for another. In these +transactions there is a conversion rate, also called the cost (when +buying) or selling price (when selling). In hledger docs we just say +"cost", for convenience; feel free to mentally translate to "conversion +rate" or "selling price" if helpful. + +* Menu: + +* Recording costs:: +* Reporting at cost:: +* Equity conversion postings:: +* Inferring equity conversion postings:: +* Combining costs and equity conversion postings:: +* Requirements for detecting equity conversion postings:: +* Infer cost and equity by default ?:: + + +File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting + +22.1 Recording costs +==================== + +We'll explore several ways of recording transactions involving costs. +These are also summarised at hledger Cookbook > Cost notation. + + Costs can be recorded explicitly in the journal, using the '@ +UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs: + + *Variant 1* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 ; $1.35 per euro (unit cost) + + *Variant 2* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 @@ $135 ; $135 total cost + + Typically, writing the unit cost (variant 1) is preferable; it can be +more effort, requiring more attention to decimal digits; but it reveals +the per-unit cost basis, and makes stock sales easier. + + Costs can also be left implicit, and hledger will infer the cost that +is consistent with a balanced transaction: + + *Variant 3* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 + + Here, hledger will attach a '@@ €100' cost to the first amount (you +can see it with 'hledger print -x'). This form looks convenient, but +there are downsides: + + * It sacrifices some error checking. For example, if you + accidentally wrote €10 instead of €100, hledger would not be able + to detect the mistake. + + * It is sensitive to the order of postings - if they were reversed, a + different entry would be inferred and reports would be different. + + * The per-unit cost basis is not easy to read. + + So generally this kind of entry is not recommended. You can make +sure you have none of these by using '-s' (strict mode), or by running +'hledger check balanced'. + + +File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting + +22.2 Reporting at cost +====================== + +Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's +-B/-basis/-cost flag), any amounts which have been annotated with costs +will be converted to their cost's commodity (in the report output). Ie +they will be displayed "at cost" or "at sale price". + + Some things to note: + + * Costs are attached to specific posting amounts in specific + transactions, and once recorded they do not change. This contrasts + with market prices, which are ambient and fluctuating. + + * Conversion to cost is performed before conversion to market value + (described below). + + +File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting + +22.3 Equity conversion postings +=============================== + +There is a problem with the entries above - they are not conventional +Double Entry Bookkeeping (DEB) notation, and because of the "magical" +transformation of one commodity into another, they cause an imbalance in +the Accounting Equation. This shows up as a non-zero grand total in +balance reports like 'hledger bse'. + + For most hledger users, this doesn't matter in practice and can +safely be ignored ! But if you'd like to learn more, keep reading. + + Conventional DEB uses an extra pair of equity postings to balance the +transaction. Of course you can do this in hledger as well: + + *Variant 4* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 + equity:conversion $135 + equity:conversion €-100 + + Now the transaction is perfectly balanced according to standard DEB, +and 'hledger bse''s total will not be disrupted. + + And, hledger can still infer the cost for cost reporting, but it's +not done by default - you must add the '--infer-costs' flag like so: + +$ hledger print --infer-costs +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 @@ €100 + assets:euros €100 + equity:conversion $135 + equity:conversion €-100 + +$ hledger bal --infer-costs -B + €-100 assets:dollars + €100 assets:euros +-------------------- + 0 + + Here are some downsides of this kind of entry: + + * The per-unit cost basis is not easy to read. + + * Instead of '-B' you must remember to type '-B --infer-costs'. + + * '--infer-costs' works only where hledger can identify the two + equity:conversion postings and match them up with the two + non-equity postings. So writing the journal entry in a particular + format becomes more important. More on this below. + + +File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting + +22.4 Inferring equity conversion postings +========================================= + +Can we go in the other direction ? Yes, if you have transactions +written with the @/@@ cost notation, hledger can infer the missing +equity postings, if you add the '--infer-equity' flag. Eg: + +2022-01-01 + assets:dollars -$135 + assets:euros €100 @ $1.35 + +$ hledger print --infer-equity +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 + equity:conversion:$-€:€ €-100 + equity:conversion:$-€:$ $135.00 + + The equity account names will be "equity:conversion:A-B:A" and +"equity:conversion:A-B:B" where A is the alphabetically first commodity +symbol. You can customise the "equity:conversion" part by declaring an +account with the 'V'/'Conversion' account type. + + +File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting + +22.5 Combining costs and equity conversion postings +=================================================== + +Finally, you can use both the @/@@ cost notation and equity postings at +the same time. This in theory gives the best of all worlds - preserving +the accounting equation, revealing the per-unit cost basis, and +providing more flexibility in how you write the entry: + + *Variant 5* + +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 @ $1.35 + + All the other variants above can (usually) be rewritten to this final +form with: + +$ hledger print -x --infer-costs --infer-equity + + Downsides: + + * This was added in hledger-1.29 and is still somewhat experimental. + + * The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it + will give a transaction balancing error. + + * The add command does not yet accept this kind of entry (#2056). + + * This is the most verbose form. + + +File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting + +22.6 Requirements for detecting equity conversion postings +========================================================== + +'--infer-costs' has certain requirements (unlike '--infer-equity', which +always works). It will infer costs only in transactions with: + + * Two non-equity postings, in different commodities. Their order is + significant: the cost will be added to the first of them. + + * Two postings to equity conversion accounts, next to one another, + which balance the two non-equity postings. This balancing is + checked to the same precision (number of decimal places) used in + the conversion posting's amount. Equity conversion accounts are: + + * any accounts declared with account type 'V'/'Conversion', or + their subaccounts + * otherwise, accounts named 'equity:conversion', 'equity:trade', + or 'equity:trading', or their subaccounts. + + And multiple such four-posting groups can coexist within a single +transaction. When '--infer-costs' fails, it does not infer a cost in +that transaction, and does not raise an error (ie, it infers costs where +it can). + + Reading variant 5 journal entries, combining cost notation and equity +postings, has all the same requirements. When reading such an entry +fails, hledger raises an "unbalanced transaction" error. + + +File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting + +22.7 Infer cost and equity by default ? +======================================= + +Should '--infer-costs' and '--infer-equity' be enabled by default ? Try +using them always, eg with a shell alias: + +alias h="hledger --infer-equity --infer-costs" + + and let us know what problems you find. + + +File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top + +23 Value reporting +****************** + +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), and/or to market value (using some market price on a +certain date). This is controlled by the '--value=TYPE[,COMMODITY]' +option, which will be described below. We also provide the simpler '-V' +and '-X COMMODITY' options, and often one of these is all you need: + +* Menu: + +* -V Value:: +* -X Value in specified commodity:: +* Valuation date:: +* Finding market price:: +* --infer-market-prices market prices from transactions:: +* Valuation commodity:: +* Simple valuation examples:: +* --value Flexible valuation:: +* More valuation examples:: +* Interaction of valuation and queries:: +* Effect of valuation on reports:: + + +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Value reporting + +23.1 -V: Value +============== + +The '-V/--market' flag converts amounts to market value in their default +_valuation commodity_, using the market prices in effect on the +_valuation date(s)_, if any. More on these in a minute. + + +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Value reporting + +23.2 -X: Value in specified commodity +===================================== + +The '-X/--exchange=COMM' option is like '-V', except you tell it which +currency you want to convert to, and it tries to convert everything to +that. + + +File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Value reporting + +23.3 Valuation date +=================== + +Market prices can change from day to day. hledger will use the prices +on a particular valuation date (or on more than one date). By default +hledger uses "end" dates for valuation. More specifically: + + * For single period reports (including normal print and register + reports): + * If an explicit report end date is specified, that is used + * Otherwise the latest transaction date or P directive date is + used (even if it's in the future) + + * For multiperiod reports, each period is valued on its last day. + + This can be customised with the -value option described below, which +can select either "then", "end", "now", or "custom" dates. (Note, this +has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key +always resets it to "end".) + + +File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting + +23.4 Finding market price +========================= + +To convert a commodity A to its market value in another commodity B, +hledger looks for a suitable market price (exchange rate) as follows, in +this order of preference: + + 1. A _declared market price_ or _inferred market price_: A's latest + market price in B on or before the valuation date as declared by a + P directive, or (with the '--infer-market-prices' flag) inferred + from costs. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 3. A _forward chain of market prices_: a synthetic price formed by + combining the shortest chain of "forward" (only 1 above) market + prices, leading from A to B. + + 4. _Any chain of market prices_: a chain of any market prices, + including both forward and reverse prices (1 and 2 above), leading + from A to B. + + There is a limit to the length of these price chains; if hledger +reaches that length without finding a complete chain or exhausting all +possibilities, it will give up (with a "gave up" message visible in +'--debug=2' output). That limit is currently 1000. + + Amounts for which no suitable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting + +23.5 -infer-market-prices: market prices from transactions +========================================================== + +Normally, market value in hledger is fully controlled by, and requires, +P directives in your journal. Since adding and updating those can be a +chore, and since transactions usually take place at close to market +value, why not use the recorded costs as additional market prices (as +Ledger does) ? Adding the '--infer-market-prices' flag to '-V', '-X' or +'--value' enables this. + + So for example, 'hledger bs -V --infer-market-prices' will get market +prices both from P directives and from transactions. If both occur on +the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Value reporting section carefully, and try adding +'--debug' or '--debug=2' to troubleshoot. + + '--infer-market-prices' can infer market prices from: + + * multicommodity transactions with explicit prices ('@'/'@@') + + * multicommodity transactions with implicit prices (no '@', two + commodities, unbalanced). (With these, the order of postings + matters. 'hledger print -x' can be useful for troubleshooting.) + + * multicommodity transactions with equity postings, if cost is + inferred with '--infer-costs'. + + There is a limitation (bug) currently: when a valuation commodity is +not specified, prices inferred with '--infer-market-prices' do not help +select a default valuation commodity, as 'P' prices would. So +conversion might not happen because no valuation commodity was detected +('--debug=2' will show this). To be safe, specify the valuation +commmodity, eg: + + * '-X EUR --infer-market-prices', not '-V --infer-market-prices' + * '--value=then,EUR --infer-market-prices', not '--value=then + --infer-market-prices' + + Signed costs and market prices can be confusing. For reference, here +is the current behaviour, since hledger 1.25. (If you think it should +work differently, see #1870.) + +2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + +2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + +2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + +2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + +2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + +2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each +day, the two transactions are considered equivalent). Here are the +market prices inferred for B: + +$ hledger -f- --infer-market-prices prices +P 2022-01-01 B A 1 +P 2022-01-01 B A 1.0 +P 2022-01-02 B A -1 +P 2022-01-02 B A -1.0 +P 2022-01-03 B A -1 +P 2022-01-03 B A -1.0 + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Value reporting + +23.6 Valuation commodity +======================== + +*When you specify a valuation commodity ('-X COMM' or '--value +TYPE,COMM'):* +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). + + *When you leave the valuation commodity unspecified ('-V' or '--value +TYPE'):* +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: + + 1. The price commodity from the latest P-declared market price for A + on or before valuation date. + + 2. The price commodity from the latest P-declared market price for A + on any date. (Allows conversion to proceed when there are inferred + prices before the valuation date.) + + 3. If there are no P directives at all (any commodity or date) and the + '--infer-market-prices' flag is used: the price commodity from the + latest transaction-inferred price for A on or before valuation + date. + + This means: + + * If you have P directives, they determine which commodities '-V' + will convert, and to what. + + * If you have no P directives, and use the '--infer-market-prices' + flag, costs determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Value reporting + +23.7 Simple valuation examples +============================== + +Here are some quick examples of '-V': + +; one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +; purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +; the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 + + How many euros do I have ? + +$ hledger -f t.j bal -N euros + €100 assets:euros + + What are they worth at end of nov 3 ? + +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date +specified, defaults to today) + +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Value reporting + +23.8 -value: Flexible valuation +=============================== + +'-V' and '-X' are special cases of the more general '--value' option: + + --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. + COMM is an optional commodity symbol. + Shows amounts converted to: + - default valuation commodity (or COMM) using market prices at posting dates + - default valuation commodity (or COMM) using market prices at period end(s) + - default valuation commodity (or COMM) using current market prices + - default valuation commodity (or COMM) using market prices at some date + + The TYPE part selects cost or value and valuation date: + +'--value=then' + + Convert amounts to their value in the default valuation commodity, + using market prices on each posting's date. +'--value=end' + + Convert amounts to their value in the default valuation commodity, + using market prices on the last day of the report period (or if + unspecified, the journal's end date); or in multiperiod reports, + market prices on the last day of each subperiod. +'--value=now' + + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). +'--value=YYYY-MM-DD' + + Convert amounts to their value in the default valuation commodity + using market prices on this date. + + To select a different valuation commodity, add the optional ',COMM' +part: a comma, then the target commodity's symbol. Eg: +*'--value=now,EUR'*. hledger will do its best to convert amounts to +this commodity, deducing market prices as described above. + + +File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting + +23.9 More valuation examples +============================ + +Here are some examples showing the effect of '--value', as seen with +'print': + +P 2000-01-01 A 1 B +P 2000-02-01 A 2 B +P 2000-03-01 A 3 B +P 2000-04-01 A 4 B + +2000-01-01 + (a) 1 A @ 5 B + +2000-02-01 + (a) 1 A @ 6 B + +2000-03-01 + (a) 1 A @ 7 B + + Show the cost of each posting: + +$ hledger -f- print --cost +2000-01-01 + (a) 5 B + +2000-02-01 + (a) 6 B + +2000-03-01 + (a) 7 B + + Show the value as of the last day of the report period (2000-02-29): + +$ hledger -f- print --value=end date:2000/01-2000/03 +2000-01-01 + (a) 2 B + +2000-02-01 + (a) 2 B + + With no report period specified, that shows the value as of the last +day of the journal (2000-03-01): + +$ hledger -f- print --value=end +2000-01-01 + (a) 3 B + +2000-02-01 + (a) 3 B + +2000-03-01 + (a) 3 B + + Show the current value (the 2000-04-01 price is still in effect +today): + +$ hledger -f- print --value=now +2000-01-01 + (a) 4 B + +2000-02-01 + (a) 4 B + +2000-03-01 + (a) 4 B + + Show the value on 2000/01/15: + +$ hledger -f- print --value=2000-01-15 +2000-01-01 + (a) 1 B + +2000-02-01 + (a) 1 B + +2000-03-01 + (a) 1 B + + +File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Value reporting + +23.10 Interaction of valuation and queries +========================================== + +When matching postings based on queries in the presence of valuation, +the following happens. + + 1. The query is separated into two parts: + 1. the currency ('cur:') or amount ('amt:'). + 2. all other parts. + + 2. The postings are matched to the currency and amount queries based + on pre-valued amounts. + 3. Valuation is applied to the postings. + 4. The postings are matched to the other parts of the query based on + post-valued amounts. + + See: 1625 + + +File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting + +23.11 Effect of valuation on reports +==================================== + +Here is a reference for how valuation is supposed to affect each part of +hledger's reports (and a glossary). (It's wide, you'll have to scroll +sideways.) It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. + +Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', +type '--cost' '--value=now' +------------------------------------------------------------------------------ +*print* +posting cost value at value at posting value at value +amounts report end date report or at + or today journal DATE/today + end +balance unchanged unchanged unchanged unchanged unchanged +assertions/assignments +*register* +starting cost value at valued at day value at value +balance report or each historical report or at +(-H) journal posting was made journal DATE/today + end end +starting cost value at valued at day value at value +balance day before each historical day before at +(-H) report or posting was made report or DATE/today +with journal journal +report start start +interval +posting cost value at value at posting value at value +amounts report or date report or at + journal journal DATE/today + end end +summary summarised value at sum of postings value at value +posting cost period in interval, period at +amounts ends valued at ends DATE/today +with interval start +report +interval +running sum/average sum/average sum/average of sum/average sum/average +total/averageof of displayed values of of + displayed displayed displayed displayed + values values values values +*balance +(bs, +bse, cf, +is)* +balance sums of value at value at posting value at value +changes costs report end date report or at + or today journal DATE/today + of sums of end of of + postings sums of sums + postings of + postings +budget like like like balance like like +amounts balance balance changes balances balance +(-budget) changes changes changes +grand sum of sum of sum of displayed sum of sum of +total displayed displayed valued displayed displayed + values values values values +*balance +(bs, +bse, cf, +is) with +report +interval* +starting sums of value at sums of values value at sums +balances costs of report of postings report of +(-H) postings start of before report start of postings + before sums of start at sums of before + report all respective all report + start postings posting dates postings start + before before + report report + start start +balance sums of same as sums of values balance value +changes costs of -value=end of postings in change in at +(bal, postings period at each DATE/today +is, bs in period respective period, of +-change, posting dates valued at sums +cf period of +-change) ends postings +end sums of same as sums of values period end value +balances costs of -value=end of postings from balances, at +(bal -H, postings before period valued at DATE/today +is -H, from start to period period of +bs, cf) before end at ends sums + report respective of + start to posting dates postings + period end +budget like like like balance like like +amounts balance balance changes/end balances balance +(-budget) changes/end changes/end balances changes/end + balances balances balances +row sums, sums, sums, averages sums, sums, +totals, averages averages of displayed averages averages +row of of values of of +averages displayed displayed displayed displayed +(-T, -A) values values values values +column sums of sums of sums of sums of sums +totals displayed displayed displayed values displayed of + values values values displayed + values +grand sum, sum, sum, average of sum, sum, +total, average of average of column totals average of average +grand column column column of +average totals totals totals column + totals + + '--cumulative' is omitted to save space, it works like '-H' but with +a zero starting balance. + + *Glossary:* + +_cost_ + + calculated using price(s) recorded in the transaction(s). +_value_ + + market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. +_report start_ + + the first day of the report period specified with -b or -p or + date:, otherwise today. +_report or journal start_ + + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. +_report end_ + + the last day of the report period specified with -e or -p or date:, + otherwise today. +_report or journal end_ + + the last day of the report period specified with -e or -p or date:, + otherwise the latest transaction date in the journal, otherwise + today. +_report interval_ + + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report's multi-period mode (whether showing one or many + subperiods). + + +File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Value reporting, Up: Top + +24 PART 4: COMMANDS +******************* + +* Menu: + +* Commands overview:: +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* demo:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* payees:: +* prices:: +* print:: +* register:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS + +24.1 Commands overview +====================== + +Here are the built-in commands: + +* Menu: + +* DATA ENTRY:: +* DATA CREATION:: +* DATA MANAGEMENT:: +* REPORTS FINANCIAL:: +* REPORTS VERSATILE:: +* REPORTS BASIC:: +* HELP:: +* ADD-ONS:: + + +File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview + +24.1.1 DATA ENTRY +----------------- + +These data entry commands are the only ones which can modify your +journal file. + + * add - add transactions using terminal prompts + * import - add new transactions from other files, eg CSV files + + +File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview + +24.1.2 DATA CREATION +-------------------- + + * close - generate balance-zeroing/restoring transactions + * rewrite - generate auto postings, like print -auto + + +File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview + +24.1.3 DATA MANAGEMENT +---------------------- + + * check - check for various kinds of error in the data + * diff - compare account transactions in two journal files + + +File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview + +24.1.4 REPORTS, FINANCIAL +------------------------- + + * aregister (areg) - show transactions in a particular account + * balancesheet (bs) - show assets, liabilities and net worth + * balancesheetequity (bse) - show assets, liabilities and equity + * cashflow (cf) - show changes in liquid assets + * incomestatement (is) - show revenues and expenses + + +File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview + +24.1.5 REPORTS, VERSATILE +------------------------- + + * balance (bal) - show balance changes, end balances, budgets, + gains.. + * print - show transactions or export journal data + * register (reg) - show postings in one or more accounts & running + total + * roi - show return on investments + + +File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview + +24.1.6 REPORTS, BASIC +--------------------- + + * accounts - show account names + * activity - show bar charts of posting counts per period + * codes - show transaction codes + * commodities - show commodity/currency symbols + * descriptions - show transaction descriptions + * files - show input file paths + * notes - show note parts of transaction descriptions + * payees - show payee parts of transaction descriptions + * prices - show market prices + * stats - show journal statistics + * tags - show tag names + * test - run self tests + + +File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview + +24.1.7 HELP +----------- + + * help - show the hledger manual with info/man/pager + * demo - show small hledger demos in the terminal + + +File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview + +24.1.8 ADD-ONS +-------------- + +And here are some typical add-on commands. Some of these are installed +by the hledger-install script. If installed, they will appear in +hledger's commands list: + + * ui - run hledger's terminal UI + * web - run hledger's web UI + * iadd - add transactions using a TUI (currently hard to build) + * interest - generate interest transactions + * stockquotes - download market prices from AlphaVantage + * Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + pijul, plot, and more.. + + Next, each command is described in detail, in alphabetical order. + + +File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS + +24.2 accounts +============= + +Show account names. + + This command lists account names. By default it shows all known +accounts, either used in transactions or declared with account +directives. + + With query arguments, only matched account names and account names +referenced by matched postings are shown. + + Or it can show just the used accounts ('--used'/'-u'), the declared +accounts ('--declared'/'-d'), the accounts declared but not used +('--unused'), the accounts used but not declared ('--undeclared'), or +the first account matched by an account name pattern, if any ('--find'). + + It shows a flat list by default. With '--tree', it uses indentation +to show the account hierarchy. In flat mode you can add '--drop N' to +omit the first few account name components. Account names can be +depth-clipped with 'depth:N' or '--depth N' or '-N'. + + With '--types', it also shows each account's type, if it's known. +(See Declaring accounts > Account types.) + + With '--positions', it also shows the file and line number of each +account's declaration, if any, and the account's overall declaration +order; these may be useful when troubleshooting account display order. + + With '--directives', it adds the 'account' keyword, showing valid +account directives which can be pasted into a journal file. This is +useful together with '--undeclared' when updating your account +declarations to satisfy 'hledger check accounts'. + + The '--find' flag can be used to look up a single account name, in +the same way that the 'aregister' command does. It returns the +alphanumerically-first matched account name, or if none can be found, it +fails with a non-zero exit code. + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + +$ hledger accounts --undeclared --directives >> $LEDGER_FILE +$ hledger check accounts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS + +24.3 activity +============= + +Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). With query arguments, it counts only matched transactions. + + Examples: + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** + + +File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS + +24.4 add +======== + +Prompt for transactions and add them to the journal. Any arguments will +be used as default inputs for the first N prompts. + + Many hledger users edit their journals directly with a text editor, +or generate them from CSV. For more interactive data entry, there is the +'add' command, which prompts interactively on the console for new +transactions, and appends them to the main journal file (which should be +in journal format). Existing transactions are not changed. This is one +of the few hledger commands that writes to the journal file (see also +'import'). + + To use it, just run 'hledger add' and follow the prompts. You can +add as many transactions as you like; when you are finished, enter '.' +or press control-d or control-c to exit. + + Features: + + * add tries to provide useful defaults, using the most similar (by + description) recent transaction (filtered by the query, if any) as + a template. + * You can also set the initial defaults with command line arguments. + * Readline-style edit keys can be used during data entry. + * The tab key will auto-complete whenever possible - accounts, + payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If + the input area is empty, it will insert the default value. + * If the journal defines a default commodity, it will be added to any + bare numbers entered. + * A parenthesised transaction code may be entered following a date. + * Comments and tags may be entered following a description or amount. + * If you make a mistake, enter '<' at any prompt to go one step + backward. + * Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see https://hledger.org/add.html for a detailed tutorial): + +$ hledger add +Adding transactions to journal file /src/hledger/examples/sample.journal +Any command line arguments will be used as defaults. +Use tab key to complete, readline keys to edit, enter to accept defaults. +An optional (CODE) may follow transaction dates. +An optional ; COMMENT may follow descriptions or amounts. +If you make a mistake, enter < at any prompt to go one step backward. +To end a transaction, enter . when prompted. +To quit, enter . at a date prompt or press control-d or control-c. +Date [2015/05/22]: +Description: supermarket +Account 1: expenses:food +Amount 1: $10 +Account 2: assets:checking +Amount 2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): . +2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + +Save this transaction to the journal ? [y]: +Saved. +Starting the next transaction (. or ctrl-D/ctrl-C to quit) +Date [2015/05/22]: $ + + On Microsoft Windows, the add command makes sure that no part of the +file path ends with a period, as that would cause problems (#1056). + + +File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS + +24.5 aregister +============== + +(areg) + + Show the transactions and running historical balance of a single +account, with each transaction displayed as one line. + + 'aregister' shows the overall transactions affecting a particular +account (and any subaccounts). Each report line represents one +transaction in this account. Transactions before the report start date +are always included in the running balance ('--historical' mode is +always on). + + This is a more "real world", bank-like view than the 'register' +command (which shows individual postings, possibly from multiple +accounts, not necessarily in historical mode). As a quick rule of +thumb: - use 'aregister' for reviewing and reconciling real-world +asset/liability accounts - use 'register' for reviewing detailed +revenues/expenses. + + 'aregister' requires one argument: the account to report on. You can +write either the full account name, or a case-insensitive regular +expression which will select the alphabetically first matched account. + + When there are multiple matches, the alphabetically-first choice can +be surprising; eg if you have 'assets:per:checking 1' and +'assets:biz:checking 2' accounts, 'hledger areg checking' would select +'assets:biz:checking 2'. It's just a convenience to save typing, so if +in doubt, write the full account name, or a distinctive substring that +matches uniquely. + + Transactions involving subaccounts of this account will also be +shown. 'aregister' ignores depth limits, so its final total will always +match a balance report with similar arguments. + + Any additional arguments form a query which will filter the +transactions shown. Note some queries will disturb the running balance, +causing it to be different from the account's real-world running +balance. + + An example: this shows the transactions and historical running +balance during july, in the first account whose name contains +"checking": + +$ hledger areg checking date:jul + + Each 'aregister' line item shows: + + * the transaction's date (or the relevant posting's date if + different, see below) + * the names of all the other account(s) involved in this transaction + (probably abbreviated) + * the total change to this account's balance from this transaction + * the account's historical running balance after this transaction. + + Transactions making a net change of zero are not shown by default; +add the '-E/--empty' flag to show them. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +'--align-all' flag. + + This command also supports the output destination and output format +options. The output formats supported are 'txt', 'csv', 'tsv', and +'json'. + +* Menu: + +* aregister and posting dates:: + + +File: hledger.info, Node: aregister and posting dates, Up: aregister + +24.5.1 aregister and posting dates +---------------------------------- + +aregister always shows one line (and date and amount) per transaction. +But sometimes transactions have postings with different dates. Also, +not all of a transaction's postings may be within the report period. To +resolve this, aregister shows the earliest of the transaction's date and +posting dates that is in-period, and the sum of the in-period postings. +In other words it will show a combined line item with just the earliest +date, and the running balance will (temporarily, until the transaction's +last posting) be inaccurate. Use 'register -H' if you need to see the +individual postings. + + There is also a '--txn-dates' flag, which filters strictly by +transaction date, ignoring posting dates. This too can cause an +inaccurate running balance. + + +File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS + +24.6 balance +============ + +(bal) + + Show accounts and their balances. + + 'balance' is one of hledger's oldest and most versatile commands, for +listing account balances, balance changes, values, value changes and +more, during one time period or many. Generally it shows a table, with +rows representing accounts, and columns representing periods. + + Note there are some higher-level variants of the 'balance' command +with convenient defaults, which can be simpler to use: 'balancesheet', +'balancesheetequity', 'cashflow' and 'incomestatement'. When you need +more control, then use 'balance'. + +* Menu: + +* balance features:: +* Simple balance report:: +* Balance report line format:: +* Filtered balance report:: +* List or tree mode:: +* Depth limiting:: +* Dropping top-level accounts:: +* Showing declared accounts:: +* Sorting by amount:: +* Percentages:: +* Multi-period balance report:: +* Balance change end balance:: +* Balance report types:: +* Budget report:: +* Balance report layout:: +* Useful balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +24.6.1 balance features +----------------------- + +Here's a quick overview of the 'balance' command's features, followed by +more detailed descriptions and examples. Many of these work with the +higher-level commands as well. + + 'balance' can show.. + + * accounts as a list ('-l') or a tree ('-t') + * optionally depth-limited ('-[1-9]') + * sorted by declaration order and name, or by amount + + ..and their.. + + * balance changes (the default) + * or actual and planned balance changes ('--budget') + * or value of balance changes ('-V') + * or change of balance values ('--valuechange') + * or unrealised capital gain/loss ('--gain') + * or postings count ('--count') + + ..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', 'tsv', 'json', and +(multi-period reports only:) 'html'. In 'txt' output in a +colour-supporting terminal, negative amounts are shown in red. + + The '--related'/'-r' flag shows the balance of the _other_ postings +in the transactions of the postings which would normally be shown. + + +File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance + +24.6.2 Simple balance report +---------------------------- + +With no arguments, 'balance' shows a list of all accounts and their +change of balance - ie, the sum of posting amounts, both inflows and +outflows - during the entire period of the journal. ("Simple" here +means just one column of numbers, covering a single period. You can +also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end +balance at the end of the journal period; more on this below. + + Accounts are sorted by declaration order if any, and then +alphabetically by account name. For instance (using +examples/sample.journal): + +$ hledger -f examples/sample.journal bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + Accounts with a zero balance (and no non-zero subaccounts, in tree +mode - see below) are hidden by default. Use '-E/--empty' to show them +(revealing 'assets:bank:checking' here): + +$ hledger -f examples/sample.journal bal -E + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + The total of the amounts displayed is shown as the last line, unless +'-N'/'--no-total' is used. + + +File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance + +24.6.3 Balance report line format +--------------------------------- + +For single-period balance reports displayed in the terminal (only), you +can use '--format FMT' to customise the format and content of each line. +Eg: + +$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string specifies the formatting applied to each +account/balance pair. It may contain any suitable text, with data +fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance + +24.6.4 Filtered balance report +------------------------------ + +You can show fewer accounts, a different time period, totals from +cleared transactions only, etc. by using query arguments or options to +limit the postings being matched. Eg: + +$ hledger -f examples/sample.journal bal --cleared assets date:200806 + $-2 assets:cash +-------------------- + $-2 + + +File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance + +24.6.5 List or tree mode +------------------------ + +By default, or with '-l/--flat', accounts are shown as a flat list with +their full names visible, as in the examples above. + + With '-t/--tree', the account hierarchy is shown, with subaccounts' +"leaf" names indented below their parent: + +$ hledger -f examples/sample.journal balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts +-------------------- + 0 + + Notes: + + * "Boring" accounts are combined with their subaccount for more + compact output, unless '--no-elide' is used. Boring accounts have + no balance of their own and just one subaccount (eg 'assets:bank' + and 'liabilities' above). + + * All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, + which requires explanation when sharing reports with + non-plaintextaccounting-users. A tree mode report's final total is + the sum of the top-level balances shown, not of all the balances + shown. + + * Each group of sibling accounts (ie, under a common parent) is + sorted separately. + + +File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance + +24.6.6 Depth limiting +--------------------- + +With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: +'-3') balance reports will show accounts only to the specified depth, +hiding the deeper subaccounts. This can be useful for getting an +overview without too much detail. + + Account balances at the depth limit always include the balances from +any deeper subaccounts (even in list mode). Eg, limiting to depth 1: + +$ hledger -f examples/sample.journal balance -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities +-------------------- + 0 + + +File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance + +24.6.7 Dropping top-level accounts +---------------------------------- + +You can also hide one or more top-level account name parts, using +'--drop NUM'. This can be useful for hiding repetitive top-level +account names: + +$ hledger -f examples/sample.journal bal expenses --drop 1 + $1 food + $1 supplies +-------------------- + $2 + + +File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance + +24.6.8 Showing declared accounts +-------------------------------- + +With '--declared', accounts which have been declared with an account +directive will be included in the balance report, even if they have no +transactions. (Since they will have a zero balance, you will also need +'-E/--empty' to see them.) + + More precisely, _leaf_ declared accounts (with no subaccounts) will +be included, since those are usually the more useful in reports. + + The idea of this is to be able to see a useful "complete" balance +report, even when you don't have transactions in all of your declared +accounts yet. + + +File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance + +24.6.9 Sorting by amount +------------------------ + +With '-S/--sort-amount', accounts with the largest (most positive) +balances are shown first. Eg: 'hledger bal expenses -MAS' shows your +biggest averaged monthly expenses first. When more than one commodity +is present, they will be sorted by the alphabetically earliest commodity +first, and then by subsequent commodities (if an amount is missing a +commodity, it is treated as 0). + + Revenues and liability balances are typically negative, however, so +'-S' shows these in reverse order. To work around this, you can add +'--invert' to flip the signs. (Or, use one of the higher-level reports, +which flip the sign automatically. Eg: 'hledger incomestatement -MAS'). + + +File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance + +24.6.10 Percentages +------------------- + +With '-%/--percent', balance reports show each account's value expressed +as a percentage of the (column) total. + + Note it is not useful to calculate percentages if the amounts in a +column have mixed signs. In this case, make a separate report for each +sign, eg: + +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` + + Similarly, if the amounts in a column have mixed commodities, convert +them to one commodity with '-B', '-V', '-X' or '--value', or make a +separate report for each commodity: + +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ + + +File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance + +24.6.11 Multi-period balance report +----------------------------------- + +With a report interval (set by the '-D/--daily', '-W/--weekly', +'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag), +'balance' shows a tabular report, with columns representing successive +time periods (and a title): + +$ hledger -f examples/sample.journal bal --quarterly income expenses -E +Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 +===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++--------------------------------- + || $-1 $1 0 0 + + Notes: + + * The report's start/end dates will be expanded, if necessary, to + fully encompass the displayed subperiods (so that the first and + last subperiods have the same duration as the others). + * Leading and trailing periods (columns) containing all zeroes are + not shown, unless '-E/--empty' is used. + * Accounts (rows) containing all zeroes are not shown, unless + '-E/--empty' is used. + * Amounts with many commodities are shown in abbreviated form, unless + '--no-elide' is used. _(experimental)_ + * Average and/or total columns can be added with the '-A/--average' + and '-T/--row-total' flags. + * The '--transpose' flag can be used to exchange rows and columns. + * The '--pivot FIELD' option causes a different transaction field to + be used as "account name". See PIVOTING. + + Multi-period reports with many periods can be too wide for easy +viewing in the terminal. Here are some ways to handle that: + + * Hide the totals row with '-N/--no-total' + * Convert to a single currency with '-V' + * Maximize the terminal window + * Reduce the terminal's font size + * View with a pager like less, eg: 'hledger bal -D --color=yes | less + -RS' + * Output as CSV and use a CSV viewer like visidata ('hledger bal -D + -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or + a spreadsheet ('hledger bal -D -o a.csv && open a.csv') + * Output as HTML and view with a browser: 'hledger bal -D -o a.html + && open a.html' + + +File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance + +24.6.12 Balance change, end balance +----------------------------------- + +It's important to be clear on the meaning of the numbers shown in +balance reports. Here is some terminology we use: + + A *_balance change_* is the net amount added to, or removed from, an +account during some period. + + An *_end balance_* is the amount accumulated in an account as of some +date (and some time, but hledger doesn't store that; assume end of day +in your timezone). It is the sum of previous balance changes. + + We call it a *_historical end balance_* if it includes all balance +changes since the account was created. For a real world account, this +means it will match the "historical record", eg the balances reported in +your bank statements or bank web UI. (If they are correct!) + + In general, balance changes are what you want to see when reviewing +revenues and expenses, and historical end balances are what you want to +see when reviewing or reconciling asset, liability and equity accounts. + + 'balance' shows balance changes by default. To see accurate +historical end balances: + + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the + journal covers the account's full lifetime. + + 2. Include all of of the account's prior postings in the report, by + not specifying a report start date, or by using the + '-H/--historical' flag. ('-H' causes report start date to be + ignored when summing postings.) + + +File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance + +24.6.13 Balance report types +---------------------------- + +The balance command is quite flexible; here is the full detail on how to +control what it reports. If the following seems complicated, don't +worry - this is for advanced reporting, and it does take time and +experimentation to get familiar with all the report modes. + + There are three important option groups: + + 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] +...' + +* Menu: + +* Calculation type:: +* Accumulation type:: +* Valuation type:: +* Combining balance report types:: + + +File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types + +24.6.13.1 Calculation type +.......................... + +The basic calculation to perform for each table cell. It is one of: + + * '--sum' : sum the posting amounts (*default*) + * '--budget' : sum the amounts, but also show the budget goal amount + (for each account/period) + * '--valuechange' : show the change in period-end historical balance + values (caused by deposits, withdrawals, and/or market price + fluctuations) + * '--gain' : show the unrealised capital gain/loss, (the current + valued balance minus each amount's original cost) + * '--count' : show the count of postings + + +File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types + +24.6.13.2 Accumulation type +........................... + +How amounts should accumulate across report periods. Another way to say +it: which time period's postings should contribute to each cell's +calculation. It is one of: + + * '--change' : calculate with postings from column start to column + end, ie "just this column". Typically used to see + revenues/expenses. (*default for balance, incomestatement*) + + * '--cumulative' : calculate with postings from report start to + column end, ie "previous columns plus this column". Typically used + to show changes accumulated since the report's start date. Not + often used. + + * '--historical/-H' : calculate with postings from journal start to + column end, ie "all postings from before report start date until + this column's end". Typically used to see historical end balances + of assets/liabilities/equity. (*default for balancesheet, + balancesheetequity, cashflow*) + + +File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types + +24.6.13.3 Valuation type +........................ + +Which kind of value or cost conversion should be applied, if any, before +displaying the report. It is one of: + + * no valuation type : don't convert to cost or value (*default*) + * '--value=cost[,COMM]' : convert amounts to cost (then optionally to + some other commodity) + * '--value=then[,COMM]' : convert amounts to market value on + transaction dates + * '--value=end[,COMM]' : convert amounts to market value on period + end date(s) + (*default with '--valuechange', '--gain'*) + * '--value=now[,COMM]' : convert amounts to market value on today's + date + * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on + another date + + or one of the equivalent simpler flags: + + * '-B/--cost' : like -value=cost (though, note -cost and -value are + independent options which can both be used at once) + * '-V/--market' : like -value=end + * '-X COMM/--exchange COMM' : like -value=end,COMM + + See Cost reporting and Value reporting for more about these. + + +File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types + +24.6.13.4 Combining balance report types +........................................ + +Most combinations of these options should produce reasonable reports, +but if you find any that seem wrong or misleading, let us know. The +following restrictions are applied: + + * '--valuechange' implies '--value=end' + * '--valuechange' makes '--change' the default when used with the + 'balancesheet'/'balancesheetequity' commands + * '--cumulative' or '--historical' disables '--row-total/-T' + + For reference, here is what the combinations of accumulation and +valuation show: + +Valuation:>no valuation '--value= then' '--value= end' '--value= +Accumulation:v YYYY-MM-DD + /now' +----------------------------------------------------------------------------- +'--change'change in sum of period-end DATE-value + period posting-date value of of change in + market values change in period + in period period +'--cumulative'change from sum of period-end DATE-value + report start to posting-date value of of change + period end market values change from from report + from report report start start to + start to period to period end period end + end +'--historicalchange from sum of period-end DATE-value +/-H' journal start posting-date value of of change + to period end market values change from from journal + (historical end from journal journal start start to + balance) start to period to period end period end + end + + +File: hledger.info, Node: Budget report, Next: Balance report layout, Prev: Balance report types, Up: balance + +24.6.14 Budget report +--------------------- + +The '--budget' report type activates extra columns showing any budget +goals for each account and period. The budget goals are defined by +periodic transactions. This is useful for comparing planned and actual +income, expenses, time usage, etc. + + For example, you can take average monthly expenses in the common +expense categories to construct a minimal monthly budget: + +;; Budget +~ monthly + income $2000 + expenses:food $400 + expenses:bus $50 + expenses:movies $30 + assets:bank:checking + +;; Two months worth of expenses +2017-11-01 + income $1950 + expenses:food $396 + expenses:bus $49 + expenses:movies $30 + expenses:supplies $20 + assets:bank:checking + +2017-12-01 + income $2100 + expenses:food $412 + expenses:bus $53 + expenses:gifts $100 + assets:bank:checking + + You can now see a monthly budget report: + +$ hledger balance -M --budget +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + This is different from a normal balance report in several ways. +Currently: + + * Accounts with budget goals during the report period, and their + parents, are shown. + * Their subaccounts are not shown (regardless of the depth setting). + * Accounts without budget goals, if any, are aggregated and shown as + "". + * Amounts are always inclusive (subaccount-including), even in list + mode. + * After each actual amount, the corresponding goal amount and + percentage of goal reached are also shown, in square brackets. + + This means that the numbers displayed will not always add up! Eg +above, the 'expenses' actual amount includes the gifts and supplies +transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts +are not shown, as they have no budget amounts declared. + + This can be confusing. When you need to make things clearer, use the +'-E/--empty' flag, which will reveal all accounts including unbudgeted +ones, giving the full picture. Eg: + +$ hledger balance -M --budget --empty +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with '--cumulative': + +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + It's common to limit budgets/budget reports to just expenses + +hledger bal -M --budget expenses + + or just revenues and expenses (eg, using account types): + +hledger bal -M --budget type:rx + + It's also common to limit or convert them to a single currency +('cur:COMM' or '-X COMM [--infer-market-prices]'). If showing multiple +currencies, '--layout bare' or '--layout tall' can help. + + For more examples and notes, see Budgeting. + +* Menu: + +* Budget report start date:: +* Budgets and subaccounts:: +* Selecting budget goals:: +* Budget vs forecast:: + + +File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report + +24.6.14.1 Budget report start date +.................................. + +This might be a bug, but for now: when making budget reports, it's a +good idea to explicitly set the report's start date to the first day of +a reporting period, because a periodic rule like '~ monthly' generates +its transactions on the 1st of each month, and if your journal has no +regular transactions on the 1st, the default report start date could +exclude that budget goal, which can be a little surprising. Eg here the +default report period is just the day of 2020-01-15: + +~ monthly in 2020 + (expenses:food) $500 + +2020-01-15 + expenses:food $400 + assets:checking + +$ hledger bal expenses --budget +Budget performance in 2020-01-15: + + || 2020-01-15 +==============++============ + || $400 +--------------++------------ + || $400 + + To avoid this, specify the budget report's period, or at least the +start date, with '-b'/'-e'/'-p'/'date:', to ensure it includes the +budget goal transactions (periodic transactions) that you want. Eg, +adding '-b 2020/1/1' to the above: + +$ hledger bal expenses --budget -b 2020/1/1 +Budget performance in 2020-01-01..2020-01-15: + + || 2020-01-01..2020-01-15 +===============++======================== + expenses:food || $400 [80% of $500] +---------------++------------------------ + || $400 [80% of $500] + + +File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report + +24.6.14.2 Budgets and subaccounts +................................. + +You can add budgets to any account in your account hierarchy. If you +have budgets on both parent account and some of its children, then +budget(s) of the child account(s) would be added to the budget of their +parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicitly +means that budget for both 'expenses:personal' and 'expenses' is $1100. + + Transactions in 'expenses:personal:electronics' will be counted both +towards its $100 budget and $1100 of 'expenses:personal' , and +transactions in any other subaccount of 'expenses:personal' would be +counted towards only towards the budget of 'expenses:personal'. + + For example, let's consider these transactions: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + +2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + +2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + +2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in +'expenses:personal:electronics:upgrades' and 'expenses:personal:train +tickets', and since both of these accounts are without explicitly +defined budget, these transactions would be counted towards budgets of +'expenses:personal:electronics' and 'expenses:personal' accordingly: + +$ hledger balance --budget -M +Budget performance in 2019/01: + + || Jan +===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++------------------------------- + || 0 [ 0] + + And with '--empty', we can get a better picture of budget allocation +and consumption: + +$ hledger balance --budget -M --empty +Budget performance in 2019/01: + + || Jan +========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++------------------------------- + || 0 [ 0] + + +File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report + +24.6.14.3 Selecting budget goals +................................ + +The budget report evaluates periodic transaction rules to generate +special "goal transactions", which generate the goal amounts for each +account in each report subperiod. When troubleshooting, you can use +'print --forecast' to show these as forecasted transactions: + +$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated + + By default, the budget report uses all available periodic transaction +rules to generate goals. This includes rules with a different report +interval from your report. Eg if you have daily, weekly and monthly +periodic rules, all of these will contribute to the goals in a monthly +budget report. + + You can select a subset of periodic rules by providing an argument to +the '--budget' flag. '--budget=DESCPAT' will match all periodic rules +whose description contains DESCPAT, a case-insensitive substring (not a +regular expression or query). This means you can give your periodic +rules descriptions (remember that two spaces are needed), and then +select from multiple budgets defined in your journal. + + +File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report + +24.6.14.4 Budget vs forecast +............................ + +'hledger --forecast ...' and 'hledger balance --budget ...' are separate +features, though both of them use the periodic transaction rules defined +in the journal, and both of them generate temporary transactions for +reporting purposes ("forecast transactions" and "budget goal +transactions", respectively). You can use both features at the same +time if you want. Here are some differences between them, as of hledger +1.29: + + CLI: + + * -forecast is a general hledger option, usable with any command + * -budget is a 'balance' command option, usable only with that + command. + + Visibility of generated transactions: + + * forecast transactions are visible in any report, like ordinary + transactions + * budget goal transactions are invisible except for the goal amounts + they produce in -budget reports. + + Periodic transaction rules: + + * -forecast uses all available periodic transaction rules + * -budget uses all periodic rules ('--budget') or a selected subset + ('--budget=DESCPAT') + + Period of generated transactions: + + * -forecast generates forecast transactions + * from after the last regular transaction to the end of the + report period ('--forecast') + * or, during a specified period ('--forecast=PERIODEXPR') + * possibly further restricted by a period specified in the + periodic transaction rule + * and always restricted within the bounds of the report period + + * -budget generates budget goal transactions + * throughout the report period + * possibly restricted by a period specified in the periodic + transaction rule. + + +File: hledger.info, Node: Balance report layout, Next: Useful balance reports, Prev: Budget report, Up: balance + +24.6.15 Balance report layout +----------------------------- + +The '--layout' option affects how balance reports show multi-commodity +amounts and commodity symbols, which can improve readability. It can +also normalise the data for easy consumption by other programs. It has +four possible values: + + * '--layout=wide[,WIDTH]': commodities are shown on a single line, + optionally elided to WIDTH + * '--layout=tall': each commodity is shown on a separate line + * '--layout=bare': commodity symbols are in their own column, amounts + are bare numbers + * '--layout=tidy': data is normalised to easily-consumed "tidy" form, + with one row per data value + + Here are the '--layout' modes supported by each output format; note +only CSV output supports all of them: + +- txt csv html json sql +--------------------------------------- +wide Y Y Y +tall Y Y Y +bare Y Y Y +tidy Y + + Examples: + + * Wide layout. With many commodities, reports can be very wide: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + * Limited wide layout. A width limit reduces the width, but some + commodities will be hidden: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + * Tall layout. Each commodity gets a new line (may be different in + each column), and account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + * Bare layout. Commodity symbols are kept in one column, each + commodity gets its own report row, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + * Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + * Note: bare layout will sometimes display an extra row for the + no-symbol commodity, because of zero amounts (hledger treats zeroes + as commodity-less, usually). This can break 'hledger-bar' + confusingly (workaround: add a 'cur:' query to exclude the + no-symbol row). + + * Tidy layout produces normalised "tidy data", where every variable + has its own column and each row represents a single data point. + See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html + for more. This is the easiest kind of data for other software to + consume. Here's how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + +File: hledger.info, Node: Useful balance reports, Prev: Balance report layout, Up: balance + +24.6.16 Useful balance reports +------------------------------ + +Some frequently used 'balance' options/reports are: + + * 'bal -M revenues expenses' + Show revenues/expenses in each month. Also available as the + 'incomestatement' command. + + * 'bal -M -H assets liabilities' + Show historical asset/liability balances at each month end. Also + available as the 'balancesheet' command. + + * 'bal -M -H assets liabilities equity' + Show historical asset/liability/equity balances at each month end. + Also available as the 'balancesheetequity' command. + + * 'bal -M assets not:receivable' + Show changes to liquid assets in each month. Also available as the + 'cashflow' command. + + Also: + + * 'bal -M expenses -2 -SA' + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + * 'bal -M --budget expenses' + Show monthly expenses and budget goals. + + * 'bal -M --valuechange investments' + Show monthly change in market value of investment assets. + + * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert]' + Show top gainers [or losers] last week + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS + +24.7 balancesheet +================= + +(bs) + + This command displays a balance sheet, showing historical ending +balances of asset and liability accounts. (To see equity as well, use +the balancesheetequity command.) Amounts are shown with normal positive +sign, as in conventional financial statements. + + This report shows accounts declared with the 'Asset', 'Cash' or +'Liability' type (see account types). Or if no such accounts are +declared, it shows top-level accounts named 'asset' or 'liability' (case +insensitive, plurals allowed) and their subaccounts. + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance -H assets liabilities', but with +smarter account detection, and liabilities displayed with their sign +flipped. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS + +24.8 balancesheetequity +======================= + +(bse) + + This command displays a balance sheet, showing historical ending +balances of asset, liability and equity accounts. Amounts are shown +with normal positive sign, as in conventional financial statements. + + This report shows accounts declared with the 'Asset', 'Cash', +'Liability' or 'Equity' type (see account types). Or if no such +accounts are declared, it shows top-level accounts named 'asset', +'liability' or 'equity' (case insensitive, plurals allowed) and their +subaccounts. + + Example: + +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance -H assets liabilities equity', but +with smarter account detection, and liabilities/equity displayed with +their sign flipped. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS + +24.9 cashflow +============= + +(cf) + + This command displays a cashflow statement, showing the inflows and +outflows affecting "cash" (ie, liquid, easily convertible) assets. +Amounts are shown with normal positive sign, as in conventional +financial statements. + + This report shows accounts declared with the 'Cash' type (see account +types). Or if no such accounts are declared, it shows accounts + + * under a top-level account named 'asset' (case insensitive, plural + allowed) + * whose name contains some variation of 'cash', 'bank', 'checking' or + 'saving'. + + More precisely: all accounts matching this case insensitive regular +expression: + + '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)' + + and their subaccounts. + + An example cashflow report: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance assets not:fixed not:investment +not:receivable', but with smarter account detection. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS + +24.10 check +=========== + +Check for various kinds of errors in your data. + + hledger provides a number of built-in error checks to help prevent +problems in your data. Some of these are run automatically; or, you can +use this 'check' command to run them on demand, with no output and a +zero exit code if all is well. Specify their names (or a prefix) as +argument(s). + + Some examples: + +hledger check # basic checks +hledger check -s # basic + strict checks +hledger check ordereddates payees # basic + two other checks + + If you are an Emacs user, you can also configure flycheck-hledger to +run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available: + +* Menu: + +* Default checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: +* More about specific checks:: + + +File: hledger.info, Node: Default checks, Next: Strict checks, Up: check + +24.10.1 Default checks +---------------------- + +These checks are run automatically by (almost) all hledger commands: + + * *parseable* - data files are in a supported format, with no syntax + errors and no invalid include directives. + + * *autobalanced* - all transactions are balanced, after converting to + cost. Missing amounts and missing costs are inferred automatically + where possible. + + * *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: Default checks, Up: check + +24.10.2 Strict checks +--------------------- + +These additional checks are run when the '-s'/'--strict' (strict mode) +flag is used. Or, they can be run by giving their names as arguments to +'check': + + * *balanced* - all transactions are balanced after converting to + cost, without inferring missing costs. If conversion costs are + required, they must be explicit. + + * *accounts* - all account names used by transactions have been + declared + + * *commodities* - all commodity symbols used have been declared + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +24.10.3 Other checks +-------------------- + +These checks can be run only by giving their names as arguments to +'check'. They are more specialised and not desirable for everyone: + + * *ordereddates* - transactions are ordered by date within each file + + * *payees* - all payees used by transactions have been declared + + * *recentassertions* - all accounts with balance assertions have a + balance assertion within 7 days of their latest posting + + * *tags* - all tags used by transactions have been declared + + * *uniqueleafnames* - all account leaf names are unique + + +File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check + +24.10.4 Custom checks +--------------------- + +A few more checks are are available as separate add-on commands, in +https://github.com/simonmichael/hledger/tree/master/bin: + + * *hledger-check-tagfiles* - all tag values containing / (a forward + slash) exist as file paths + + * *hledger-check-fancyassertions* - more complex balance assertions + are passing + + You could make similar scripts to perform your own custom checks. +See: Cookbook -> Scripting. + + +File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check + +24.10.5 More about specific checks +---------------------------------- + +'hledger check recentassertions' will complain if any balance-asserted +account has postings more than 7 days after its latest balance +assertion. This aims to prevent the situation where you are regularly +updating your journal, but forgetting to check your balances against the +real world, then one day must dig back through months of data to find an +error. It assumes that adding a balance assertion requires/reminds you +to check the real-world balance. (That may not be true if you +auto-generate balance assertions from bank data; in that case, I +recommend to import transactions uncleared, and when you manually review +and clear them, also check the latest assertion against the real-world +balance.) + + +File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS + +24.11 close +=========== + +(equity) + + Generate transactions which transfer account balances to and/or from +another account (typically equity). This can be useful for migrating +balances to a new journal file, or for merging earnings into equity at +end of accounting period. + + By default, it prints a transaction that zeroes out ALE accounts +(asset, liability, equity accounts; this requires account types to be +configured); or if ACCTQUERY is provided, the accounts matched by that. + + _(experimental)_ + + This command has four main modes, corresponding to the most common +use cases: + + 1. With '--close' (default), it prints a "closing balances" + transaction that zeroes out ALE (asset, liability, equity) accounts + by default (this requires account types to be inferred or + declared); or, the accounts matched by the provided ACCTQUERY + arguments. + + 2. With '--open', it prints an opposite "opening balances" transaction + that restores those balances from zero. This is similar to + Ledger's equity command. + + 3. With '--migrate', it prints both the closing and opening + transactions. This is the preferred way to migrate balances to a + new file: run 'hledger close --migrate', add the closing + transaction at the end of the old file, and add the opening + transaction at the start of the new file. The matching + closing/opening transactions cancel each other out, preserving + correct balances during multi-file reporting. + + 4. With '--retain', it prints a "retain earnings" transaction that + transfers RX (revenue and expense) balances to 'equity:retained + earnings'. Businesses traditionally do this at the end of each + accounting period; it is less necessary with computer-based + accounting, but it could still be useful if you want to see the + accounting equation (A=L+E) satisfied. + + In all modes, the defaults can be overridden: + + * the transaction descriptions can be changed with + '--close-desc=DESC' and '--open-desc=DESC' + * the account to transfer to/from can be changed with + '--close-acct=ACCT' and '--open-acct=ACCT' + * the accounts to be closed/opened can be changed with 'ACCTQUERY' + (account query arguments). + * the closing/opening dates can be changed with '-e DATE' (a report + end date) + + By default just one destination/source posting will be used, with its +amount left implicit. With '--x/--explicit', the amount will be shown +explicitly, and if it involves multiple commodities, a separate posting +will be generated for each of them (similar to 'print -x'). + + With '--show-costs', any amount costs are shown, with separate +postings for each cost. This is currently the best way to view +investment lots. If you have many currency conversion or investment +transactions, it can generate very large journal entries. + + With '--interleaved', each individual transfer is shown with source +and destination postings next to each other. This could be useful for +troubleshooting. + + The default closing date is yesterday, or the journal's end date, +whichever is later. You can change this by specifying a report end date +with '-e'. The last day of the report period will be the closing date, +eg '-e 2024' means "close on 2023-12-31". The opening date is always +the day after the closing date. + +* Menu: + +* close and balance assertions:: +* Example retain earnings:: +* Example migrate balances to a new file:: +* Example excluding closing/opening transactions:: + + +File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Up: close + +24.11.1 close and balance assertions +------------------------------------ + +Balance assertions will be generated, verifying that the accounts have +been reset to zero (and then restored to their previous balances, if +there is an opening transaction). + + These provide useful error checking, but you can ignore them +temporarily with '-I', or remove them if you prefer. + + You probably should avoid filtering transactions by status or +realness ('-C', '-R', 'status:'), or generating postings ('--auto'), +with this command, since the balance assertions would depend on these. + + Note custom posting dates spanning the file boundary will disrupt the +balance assertions: + +2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve that you can transfer the money to and from a temporary +account, in effect splitting the multi-day transaction into two +single-day transactions: + +; in 2022.journal: +2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + +; in 2023.journal: +2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + +File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close + +24.11.2 Example: retain earnings +-------------------------------- + +Record 2022's revenues/expenses as retained earnings on 2022-12-31, +appending the generated transaction to the journal: + +$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + Note 2022's income statement will now show only zeroes, because +revenues and expenses have been moved entirely to equity. To see them +again, you could exclude the retain transaction: + +$ hledger -f 2022.journal is not:desc:'retain earnings' + + +File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close + +24.11.3 Example: migrate balances to a new file +----------------------------------------------- + +Close assets/liabilities/equity on 2022-12-31 and re-open them on +2023-01-01: + +$ hledger close --migrate -f 2022.journal -p 2022 +# copy/paste the closing transaction to the end of 2022.journal +# copy/paste the opening transaction to the start of 2023.journal + + Now 2022's balance sheet will show only zeroes, indicating a balanced +accounting equation. (Unless you are using @/@@ notation - in that +case, try adding -infer-equity.) To see the end-of-year balances again, +you could exclude the closing transaction: + +$ hledger -f 2022.journal bs not:desc:'closing balances' + + +File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close + +24.11.4 Example: excluding closing/opening transactions +------------------------------------------------------- + +When combining many files for multi-year reports, the closing/opening +transactions cause some noise in transaction-oriented reports like +'print' and 'register'. You can exclude them as shown above, but +'not:desc:...' is not ideal as it depends on consistent descriptions; +also you will want to avoid excluding the very first opening +transaction, which could be awkward. Here is one alternative, using +tags: + + Add 'clopen:' tags to all opening/closing balances transactions +except the first, like this: + +; 2021.journal +2021-06-01 first opening balances +... +2021-12-31 closing balances ; clopen:2022 +... + +; 2022.journal +2022-01-01 opening balances ; clopen:2022 +... +2022-12-31 closing balances ; clopen:2023 +... + +; 2023.journal +2023-01-01 opening balances ; clopen:2023 +... + + Now, assuming a combined journal like: + +; all.journal +include 2021.journal +include 2022.journal +include 2023.journal + + The 'clopen:' tag can exclude all but the first opening transaction. +To show a clean multi-year checking register: + +$ hledger -f all.journal areg checking not:tag:clopen + + And the year values allow more precision. To show 2022's year-end +balance sheet: + +$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 + + +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS + +24.12 codes +=========== + +List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction's code field, in +the order transactions were parsed. The transaction code is an optional +value written in parentheses between the date and description, often +used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty +codes will not be shown by default. With the '-E'/'--empty' flag, they +will be printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + +2022/1/1 (123) Supermarket + Food $5.00 + Checking + +2022/1/2 (124) Post Office + Postage $8.32 + Checking + +2022/1/3 Supermarket + Food $11.23 + Checking + +2022/1/4 (126) Post Office + Postage $3.21 + Checking + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + +126 + + +File: hledger.info, Node: commodities, Next: demo, Prev: codes, Up: PART 4 COMMANDS + +24.13 commodities +================= + +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: demo, Next: descriptions, Prev: commodities, Up: PART 4 COMMANDS + +24.14 demo +========== + +Play demos of hledger usage in the terminal, if asciinema is installed. + + Run this command with no argument to list the demos. To play a demo, +write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/-speed SPEED option to set your preferred playback speed, +eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. +The default speed is 2x. + + Other asciinema options can be added following a double dash, eg '-- +-i.1' to limit pauses or '-- -h' to list asciinema's other options. + + During playback, several keys are available: SPACE to pause/unpause, +. to step forward (while paused), CTRL-c quit. + + Examples: + +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo at default speed (2x) +$ hledger demo install -s4 # play the "install" demo at 4x speed + + +File: hledger.info, Node: descriptions, Next: diff, Prev: demo, Up: PART 4 COMMANDS + +24.15 descriptions +================== + +List the unique descriptions that appear in transactions. + + This command lists the unique descriptions that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. + + Example: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS + +24.16 diff +========== + +Compares a particular account's transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + + More precisely, for each posting affecting this account in either +file, it looks for a corresponding posting in the other file which posts +the same amount to the same account (ignoring date, description, etc.) +Since postings not transactions are compared, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This is useful eg if you have downloaded an account's transactions +from your bank (eg as CSV data). When hledger and your bank disagree +about the account balance, you can compare the bank data with your +journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS + +24.17 files +=========== + +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + + +File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS + +24.18 help +========== + +Show the hledger user manual in the terminal, with 'info', 'man', or a +pager. With a TOPIC argument, open it at that topic if possible. TOPIC +can be any heading in the manual, or a heading prefix, case insensitive. +Eg: 'commands', 'print', 'forecast', 'journal', 'amount', '"auto +postings"'. + + This command shows the hledger manual built in to your hledger +version. It can be useful when offline, or when you prefer the terminal +to a web browser, or when the appropriate hledger manual or viewing +tools are not installed on your system. + + By default it chooses the best viewer found in $PATH, trying (in this +order): 'info', 'man', '$PAGER', 'less', 'more'. You can force the use +of info, man, or a pager with the '-i', '-m', or '-p' flags, If no +viewer can be found, or the command is run non-interactively, it just +prints the manual to stdout. + + If using 'info', note that version 6 or greater is needed for TOPIC +lookup. If you are on mac you will likely have info 4.8, and should +consider installing a newer version, eg with 'brew install texinfo' +(#1770). + + Examples + +$ hledger help --help # show how the help command works +$ hledger help # show the hledger manual with info, man or $PAGER +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help -m journal # show it with man, even if info is installed + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS + +24.19 import +============ + +Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. + + This command may append new transactions to the main journal file +(which should be in journal format). Existing transactions are not +changed. This is one of the few hledger commands that writes to the +journal file (see also 'add'). + + Unlike other hledger commands, with 'import' the journal file is an +output file, and will be modified, though only by appending (existing +data will not be changed). The input files are specified as arguments, +so to import one or more CSV files to your main journal, you will run +'hledger import bank.csv' or perhaps 'hledger import *.csv'. + + Note you can import from any file format, though CSV files are the +most common import source, and these docs focus on that case. + +* Menu: + +* Deduplication:: +* Import testing:: +* Importing balance assignments:: +* Commodity display styles:: + + +File: hledger.info, Node: Deduplication, Next: Import testing, Up: import + +24.19.1 Deduplication +--------------------- + +'import' does _time-based deduplication_, to detect only the new +transactions since the last successful import. (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 downloaded data, which may overlap with +previous downloads. Eg if every week (or every day) you download a +bank's last three months of CSV data, you can safely run 'hledger import +thebank.csv' each time and only new transactions will be imported. + + 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.FILE" file in FILE's directory (after a +succesful import). + + 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. + + Related: CSV > Working with CSV > Deduplicating, importing. + + +File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import + +24.19.2 Import testing +---------------------- + +With '--dry-run', the transactions that will be imported are printed to +the terminal, without updating your journal or state files. The output +is valid journal format, like the print command, so you can re-parse it. +Eg, to see any importable transactions which CSV rules have not +categorised: + +$ hledger import --dry bank.csv | hledger -f- -I print unknown + + or (live updating): + +$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' + + Note: when importing from multiple files at once, it's currently +possible for some .latest files to be updated successfully, while the +actual import fails because of a problem in one of the files, leaving +them out of sync (and causing some transactions to be missed). To +prevent this, do a -dry-run first and fix any problems before the real +import. + + +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import + +24.19.3 Importing balance assignments +------------------------------------- + +Entries added by import will have their posting amounts made explicit +(like 'hledger print -x'). This means that any balance assignments in +imported files must be evaluated; but, imported files don't get to see +the main file's account balances. As a result, importing entries with +balance assignments (eg from an institution that provides only balances +and not posting amounts) will probably generate incorrect posting +amounts. To avoid this problem, use print instead of import: + +$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE + + (If you think import should leave amounts implicit like print does, +please test it and send a pull request.) + + +File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import + +24.19.4 Commodity display styles +-------------------------------- + +Imported amounts will be formatted according to the canonical commodity +styles (declared or inferred) in the main journal file. + + +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS + +24.20 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', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS + +24.21 notes +=========== + +List the unique notes that appear in transactions. + + This command lists the unique notes that appear in transactions, in +alphabetic order. You can add a query to select a subset of +transactions. The note is the part of the transaction description after +a | character (or if there is no |, the whole description). + + Example: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS + +24.22 payees +============ + +List the unique payee/payer names that appear in transactions. + + This command lists unique payee/payer names which have been declared +with payee directives (-declared), used in transaction descriptions +(-used), or both (the default). + + The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). + + You can add query arguments to select a subset of transactions. This +implies -used. + + Example: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS + +24.23 prices +============ + +Print the market prices declared with P directives. With +-infer-market-prices, also show any additional prices inferred from +costs. With -show-reverse, also show additional prices inferred by +reversing known prices. + + Price amounts are always displayed with their full precision, except +for reverse prices which are limited to 8 decimal digits. + + Prices can be filtered by a date:, cur: or amt: query. + + Generally if you run this command with -infer-market-prices +-show-reverse, it will show the same prices used internally to calculate +value reports. But if in doubt, you can inspect those directly by +running the value report with -debug=2. + + +File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS + +24.24 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). + + 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/regenerate your journal you should take care to also copy +over the directives and inter-transaction comments. + + Eg: + +$ hledger print -f examples/sample.journal date:200806 +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 + +* Menu: + +* print explicitness:: +* print amount style:: +* print parseability:: +* print other features:: +* print output format:: + + +File: hledger.info, Node: print explicitness, Next: print amount style, Up: print + +24.24.1 print explicitness +-------------------------- + +Normally, whether posting amounts are implicit or explicit is preserved. +For example, when an amount is omitted in the journal, it will not +appear in the output. Similarly, if a conversion cost is implied but +not written, it will not appear in the output. + + You can use the '-x'/'--explicit' flag to force explicit display of +all amounts and costs. This 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'. + + The '-x'/'--explicit' flag will cause any postings with a +multi-commodity amount (which can arise when a multi-commodity +transaction has an implicit amount) to be split into multiple +single-commodity postings, keeping the output parseable. + + +File: hledger.info, Node: print amount style, Next: print parseability, Prev: print explicitness, Up: print + +24.24.2 print amount style +-------------------------- + +Amounts are shown right-aligned within each transaction (but not aligned +across all transactions; you can do that with ledger-mode in Emacs). + + Amounts will be (mostly) normalised to their commodity display style: +their symbol placement, decimal mark, and digit group marks will be made +consistent. By default, decimal digits are shown as they are written in +the journal. + + With the '--round' option, 'print' will try increasingly hard to +display decimal digits according to the commodity display styles: + + * '--round=none' show amounts with original precisions (default) + * '--round=soft' add/remove decimal zeros in amounts (except costs) + * '--round=hard' round amounts (except costs), possibly hiding + significant digits + * '--round=all' round all amounts and costs + + 'soft' is good for non-lossy cleanup, formatting amounts more +consistently where it's safe to do so. + + 'hard' and 'all' can cause 'print' to show invalid unbalanced journal +entries; they may be useful eg for stronger cleanup, with manual fixups +when needed. + + +File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print + +24.24.3 print parseability +-------------------------- + +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 (though the same can be achieved with 'expr:' queries +now): + +# 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: + + * Value reporting 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. + + +File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print + +24.24.4 print, other features +----------------------------- + +With '-B'/'--cost', amounts with costs are shown converted to cost. + + With '--new', print shows 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.) + + With '-m DESC'/'--match=DESC', print shows one recent transaction +whose description is most similar to DESC. DESC should contain at least +two characters. If there is no similar-enough match, no transaction +will be shown and the program exit code will be non-zero. + + +File: hledger.info, Node: print output format, Prev: print other features, Up: print + +24.24.5 print output format +--------------------------- + +This command also supports the output destination and output format +options The output formats supported are 'txt', 'beancount', 'csv', +'tsv', 'json' and 'sql'. + + _Experimental:_ The 'beancount' format tries to produce +Beancount-compatible output, as follows: + + * Transaction and postings with unmarked status are converted to + cleared ('*') status. + * Transactions' payee and note are backslash-escaped and + double-quote-escaped and wrapped in double quotes. + * Transaction tags are copied to Beancount #tag format. + * Commodity symbols are converted to upper case, and a small number + of currency symbols like '$' are converted to the corresponding + currency names. + * Account name parts are capitalised and unsupported characters are + replaced with '-'. If an account name part does not begin with a + letter, or if the first part is not Assets, Liabilities, Equity, + Income, or Expenses, an error is raised. (Use '--alias' options to + bring your accounts into compliance.) + * An 'open' directive is generated for each account used, on the + earliest transaction date. + + Some limitations: + + * Balance assertions are removed. + * Balance assignments become missing amounts. + * Virtual and balanced virtual postings become regular postings. + * Directives are not converted. + + Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS + +24.25 register +============== + +(reg) + + Show postings and their running total. + + The register command displays matched postings, across all accounts, +in date order, with their running total or running historical balance. +(See also the 'aregister' command, which shows matched transactions in a +specific account.) + + register normally shows line per posting, but note that +multi-commodity amounts will occupy multiple lines (one line per +commodity). + + It is typically used with a query selecting a particular account, to +see that account's activity: + +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + With '--date2', it shows and sorts by secondary date instead. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +'--align-all' flag. + + The '--historical'/'-H' flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + The '--depth' option limits the amount of sub-account detail +displayed. + + The '--average'/'-A' flag shows the running average posting amount +instead of the running total (so, the final number displayed is the +average for the whole report period). This flag implies '--empty' (see +below). It is affected by '--historical'. It works best when showing +just one account and one commodity. + + The '--related'/'-r' flag shows the _other_ postings in the +transactions of the postings which would normally be shown. + + The '--invert' flag negates all amounts. For example, it can be used +on an income account where amounts are normally displayed as negative +numbers. It's also useful to show postings on the checking account +together with the related account: + +$ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: + +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, +are not shown by default; use the '--empty'/'-E' flag to see them: + +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The '--depth' +option helps with this, causing subaccounts to be aggregated: + +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates +these will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. + + With '-m DESC'/'--match=DESC', register does a fuzzy search for one +recent posting whose description is most similar to DESC. DESC should +contain at least two characters. If there is no similar-enough match, +no posting will be shown and the program exit code will be non-zero. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +24.25.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', 'tsv', and +(experimental) 'json'. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS + +24.26 rewrite +============= + +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +$ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +24.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 + +24.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 + +24.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: PART 4 COMMANDS + +24.27 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, also known as money-weighted rate of return) and time-weighted +rate of return (TWR) for your investments for the time period requested. +IRR is always annualized due to the way it is computed, but TWR is +reported both as a rate over the chosen reporting period and as an +annual rate. + + Price directives will be taken into account if you supply appropriate +'--cost' or '--value' flags (see VALUATION). + + Note, in some cases this report can fail, for these reasons: + + * Error (NotBracketed): No solution for Internal Rate of Return + (IRR). Possible causes: IRR is huge (>1000000%), balance of + investment becomes negative at some point in time. + * Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or + converges too slowly. + + Examples: + + * Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger + + * Cookbook > Return on Investment: https://hledger.org/roi.html + +* Menu: + +* Spaces and special characters in --inv and --pnl:: +* Semantics of --inv and --pnl:: +* IRR and TWR explained:: + + +File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi + +24.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 + +24.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 + +24.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, and +the time between them. Investment at a particular fixed interest rate +is going to give you more interest than the same amount invested at the +same interest rate, but made later in time. 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, +so your IRR will be smaller. And if you are adding to your investment, +you will receive bigger absolute gains, which will be a bigger +percentage of your initial investment, so your IRR will be larger. + + 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 +account for the effect of your in-flows and out-flows, but unlike IRR it +will try to compute the true rate of return of the underlying asset, +compensating for the effect that deposits and withdrawas have on the +apparent rate of growth of your investment. + + 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, and make TWR less sensitive than IRR to the effects of +cash in-flows and out-flows. + + References: + + * Explanation of rate of return + * Explanation of IRR + * Explanation of TWR + * IRR vs TWR + * Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS + +24.28 stats +=========== + +Show journal and performance statistics. + + The stats command displays summary information for the whole journal, +or a matched part of it. With a reporting interval, it shows a report +for each report period. + + At the end, it shows (in the terminal) the overall run time and +number of transactions processed per second. Note these are approximate +and will vary based on machine, current load, data size, hledger +version, haskell lib versions, GHC version.. but they may be of +interest. The 'stats' command's run time is similar to that of a +single-column balance report. + + Example: + +$ hledger stats -f examples/1000x1000x10.journal +Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal +Included files : +Transactions span : 2000-01-01 to 2002-09-27 (1000 days) +Last transaction : 2002-09-26 (6995 days ago) +Transactions : 1000 (1.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) +Market prices : 1000 (A) + +Run time : 0.12 s +Throughput : 8342 txns/s + + This command supports the -o/-output-file option (but not +-O/-output-format selection). + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS + +24.29 tags +========== + +List the tags used in the journal, or their values. + + This command lists the tag names used in the journal, whether on +transactions, postings, or account declarations. + + With a TAGREGEX argument, only tag names matching this regular +expression (case insensitive, infix matched) are shown. + + With QUERY arguments, only transactions and accounts matching this +query are considered. If the query involves transaction fields (date:, +desc:, amt:, ...), the search is restricted to the matched transactions +and their accounts. + + With the -values flag, the tags' unique non-empty values are listed +instead. With -E/-empty, blank/empty values are also shown. + + With -parsed, tags or values are shown in the order they were parsed, +with duplicates included. (Except, tags from account declarations are +always shown first.) + + Tip: remember, accounts also acquire tags from their parents, +postings also acquire tags from their account and transaction, +transactions also acquire tags from their postings. + + +File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS + +24.30 test +========== + +Run built-in unit tests. + + This command runs the unit tests built in to hledger and hledger-lib, +printing the results on stdout. If any test fails, the exit code will +be non-zero. + + This is mainly used by hledger developers, but you can also use it to +sanity-check the installed hledger executable on your platform. All +tests are expected to pass - if you ever see a failure, please report as +a bug! + + This command also accepts tasty test runner options, written after a +- (double hyphen). Eg to run only the tests in Hledger.Data.Amount, +with ANSI colour codes disabled: + +$ hledger test -- -pData.Amount --color=never + + For help on these, see https://github.com/feuerbach/tasty#options +('-- --help' currently doesn't show them). + + +File: hledger.info, Node: PART 5 COMMON TASKS, Next: BUGS, Prev: PART 4 COMMANDS, Up: Top + +25 PART 5: COMMON TASKS +*********************** + +Here are some quick examples of how to do some basic tasks with hledger. + +* Menu: + +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting LEDGER_FILE:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file:: + + +File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS + +25.1 Getting help +================= + +Here's how to list commands and view options and command docs: + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version's manual in several formats by +using the help command. Eg: + +$ hledger help # show the hledger manual with info, man or $PAGER (best available) +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit +https://hledger.org. Chat and mail list support and discussion archives +can be found at https://hledger.org/support. + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS + +25.2 Constructing command lines +=============================== + +hledger has a flexible command line interface. We strive to keep it +simple and ergonomic, but if you run into one of the sharp edges +described in OPTIONS, here are some tips that might help: + + * command-specific options must go after the command (it's fine to + put common options there too: 'hledger CMD OPTS ARGS') + * running add-on executables directly simplifies command line parsing + ('hledger-ui OPTS ARGS') + * enclose "problematic" args in single quotes + * if needed, also add a backslash to hide regular expression + metacharacters from the shell + * to see how a misbehaving command line is being parsed, add + '--debug=2'. + + +File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: PART 5 COMMON TASKS + +25.3 Starting a journal file +============================ + +hledger looks for your accounting data in a journal file, +'$HOME/.hledger.journal' by default: + +$ hledger stats +The hledger journal file "/Users/simon/.hledger.journal" was not found. +Please create it first, eg with "hledger add" or a text editor. +Or, specify an existing journal file with -f or LEDGER_FILE. + + You can override this by setting the 'LEDGER_FILE' environment +variable (see below). 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 2023.journal +$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile +$ source ~/.profile +$ hledger stats +Main file : /Users/simon/finance/2023.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 LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: PART 5 COMMON TASKS + +25.4 Setting LEDGER_FILE +======================== + +How to set 'LEDGER_FILE' permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for +many people; adapt as needed: + +$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile +$ source ~/.profile + + When correctly configured, in a new terminal window 'env | grep +LEDGER_FILE' will show your file, and so will 'hledger files'. + + On mac, this additional step might be helpful for GUI applications +(like Emacs started from the dock): add an entry to +'~/.MacOSX/environment.plist' like + +{ + "LEDGER_FILE" : "~/finance/2023.journal" +} + + and then run 'killall Dock' in a terminal window (or restart the +machine). + + On Windows, see https://www.java.com/en/download/help/path.html, or +try running these commands in a powershell window (let us know if it +persists across a reboot, and if you need to be an Administrator): + +> CD +> MKDIR finance +> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: PART 5 COMMON TASKS + +25.5 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: + + 2023-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/2023.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 [2023-02-07]: 2023-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): . + 2023-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 [2023-01-01]: . + + If you're using version control, this could be a good time to commit +the journal. Eg: + +$ git commit -m 'initial balances' 2023.journal + + +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS + +25.6 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: + +2023/1/10 * gift received + assets:cash $20 + income:gifts + +2023.1.12 * farmers market + expenses:food $13 + assets:cash + +2023-01-15 paycheck + income:salary + assets:bank:checking $1000 + + +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS + +25.7 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: + + 2023-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 '2023-01-15' and 'paycheck' + + If you're using version control, this can be another good time to +commit: + +$ git commit -m 'txns' 2023.journal + + +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS + +25.8 Reporting +============== + +Here are some basic reports. + + Show all transactions: + +$ hledger print +2023-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +2023-01-10 * gift received + assets:cash $20 + income:gifts + +2023-01-12 * farmers market + expenses:food $13 + assets:cash + +2023-01-15 * paycheck + income:salary + assets:bank:checking $1000 + +2023-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + +$ hledger accounts --tree +assets + bank + checking + savings + cash +equity + opening/closing balances +expenses + food + misc +income + gifts + salary +liabilities + creditcard + + Show all account totals: + +$ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard +-------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to +depth 2: + +$ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard +-------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple +balance sheet: + +$ hledger bs -2 +Balance Sheet 2023-01-16 + + || 2023-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 2023-01-01-2023-01-16 + + || 2023-01-01-2023-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 +2023-01-01 opening balances assets:cash $100 $100 +2023-01-10 gift received assets:cash $20 $120 +2023-01-12 farmers market assets:cash $-13 $107 +2023-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + +$ hledger activity -W +2019-12-30 ***** +2023-01-06 **** +2023-01-13 **** + + +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS + +25.9 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: BUGS, Prev: PART 5 COMMON TASKS, Up: Top + +26 BUGS +******* + +We welcome bug reports in the hledger issue tracker (shortcut: +http://bugs.hledger.org), or on the #hledger chat or hledger mail list +(https://hledger.org/support). + + Some known issues and limitations: + + The need to precede add-on command options with '--' when invoked +from hledger is awkward. (See Command options, Constructing command +lines.) + + A UTF-8-aware system locale must be configured to work with non-ascii +data. (See Unicode characters, Troubleshooting.) + + On Microsoft Windows, depending whether you are running in a CMD +window or a Cygwin/MSYS/Mintty window and how you installed hledger, +non-ascii characters and colours may not be supported, and the tab key +may not be supported by 'hledger add'. (Running in a WSL window should +resolve these.) + + When processing large data files, hledger uses more memory than +Ledger. + +* Menu: + +* Troubleshooting:: + + +File: hledger.info, Node: Troubleshooting, Up: BUGS + +26.1 Troubleshooting +==================== + +Here are some common issues you might encounter when you run hledger, +and how to resolve them (and remember also you can usually get quick +Support): + + *PATH issues: I get an error like "No command 'hledger' found"* +Depending how you installed hledger, the executables may not be in your +shell's PATH. Eg on unix systems, stack installs hledger in +'~/.local/bin' and cabal installs it in '~/.cabal/bin'. You may need to +add one of these directories to your shell's PATH, and/or open a new +terminal window. + + *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not +using it* + + * 'LEDGER_FILE' should be a real environment variable, not just a + shell variable. Eg on unix, the command 'env | grep LEDGER_FILE' + should show it. You may need to use 'export' (see + https://stackoverflow.com/a/7411509). + * You may need to force your shell to see the new configuration. A + simple way is to close your terminal window and open a new one. + + *LANG issues: I get 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 +the system locale to be UTF-8-aware, or they will fail when they +encounter non-ascii characters. To fix it, set the LANG environment +variable to a locale which supports UTF-8 and which is installed on your +system. + + On unix, 'locale -a' lists the installed locales. Look for one which +mentions 'utf8', 'UTF-8' or similar. Some examples: 'C.UTF-8', +'en_US.utf-8', 'fr_FR.utf8'. If necessary, use your system package +manager to install one. Then select it by setting the 'LANG' +environment variable. Note, exact spelling and capitalisation of the +locale name may be important: Here's one common way to configure this +permanently for your shell: + +$ echo "export LANG=en_US.utf8" >>~/.profile +# close and re-open terminal window + + If you are using Nix (not NixOS) for GHC and Hledger, you might need +to set the 'LOCALE_ARCHIVE' variable: + +$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile +# close and re-open terminal window + + *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file* +Not all of Ledger's journal file syntax or feature set is supported. +See hledger and Ledger for full details. + + +Tag Table: +Node: Top210 +Node: PART 1 USER INTERFACE3822 +Ref: #part-1-user-interface3961 +Node: Input3961 +Ref: #input4071 +Node: Data formats5020 +Ref: #data-formats5133 +Node: Standard input6495 +Ref: #standard-input6635 +Node: Multiple files6862 +Ref: #multiple-files7001 +Node: Strict mode7599 +Ref: #strict-mode7709 +Node: Commands8433 +Ref: #commands8535 +Node: Add-on commands9602 +Ref: #add-on-commands9704 +Node: Options10820 +Ref: #options10932 +Node: General help options11260 +Ref: #general-help-options11406 +Node: General input options11688 +Ref: #general-input-options11870 +Node: General reporting options12572 +Ref: #general-reporting-options12733 +Node: Command line tips16123 +Ref: #command-line-tips16253 +Node: Option repetition16512 +Ref: #option-repetition16656 +Node: Special characters16760 +Ref: #special-characters16933 +Node: Single escaping shell metacharacters17096 +Ref: #single-escaping-shell-metacharacters17337 +Node: Double escaping regular expression metacharacters17940 +Ref: #double-escaping-regular-expression-metacharacters18251 +Node: Triple escaping for add-on commands18777 +Ref: #triple-escaping-for-add-on-commands19037 +Node: Less escaping19681 +Ref: #less-escaping19835 +Node: Unicode characters20159 +Ref: #unicode-characters20334 +Node: Regular expressions21746 +Ref: #regular-expressions21919 +Node: hledger's regular expressions25015 +Ref: #hledgers-regular-expressions25174 +Node: Argument files26560 +Ref: #argument-files26696 +Node: Output27193 +Ref: #output27305 +Node: Output destination27432 +Ref: #output-destination27563 +Node: Output format27988 +Ref: #output-format28134 +Node: CSV output29731 +Ref: #csv-output29847 +Node: HTML output29950 +Ref: #html-output30088 +Node: JSON output30182 +Ref: #json-output30320 +Node: SQL output31242 +Ref: #sql-output31358 +Node: Commodity styles32093 +Ref: #commodity-styles32233 +Node: Colour32832 +Ref: #colour32950 +Node: Box-drawing33354 +Ref: #box-drawing33472 +Node: Paging33762 +Ref: #paging33876 +Node: Debug output34829 +Ref: #debug-output34935 +Node: Environment35598 +Ref: #environment35722 +Node: PART 2 DATA FORMATS36266 +Ref: #part-2-data-formats36409 +Node: Journal36409 +Ref: #journal36518 +Node: Journal cheatsheet37175 +Ref: #journal-cheatsheet37314 +Node: About journal format41299 +Ref: #about-journal-format41459 +Node: Comments43075 +Ref: #comments43205 +Node: Transactions44021 +Ref: #transactions44144 +Node: Dates45158 +Ref: #dates45265 +Node: Simple dates45310 +Ref: #simple-dates45426 +Node: Posting dates45926 +Ref: #posting-dates46044 +Node: Status47013 +Ref: #status47114 +Node: Code48822 +Ref: #code48925 +Node: Description49157 +Ref: #description49288 +Node: Payee and note49608 +Ref: #payee-and-note49714 +Node: Transaction comments50049 +Ref: #transaction-comments50202 +Node: Postings50565 +Ref: #postings50698 +Node: Account names51693 +Ref: #account-names51823 +Node: Amounts53497 +Ref: #amounts53612 +Node: Decimal marks digit group marks54597 +Ref: #decimal-marks-digit-group-marks54772 +Node: Commodity55631 +Ref: #commodity55818 +Node: Directives influencing number parsing and display56770 +Ref: #directives-influencing-number-parsing-and-display57029 +Node: Commodity display style57481 +Ref: #commodity-display-style57687 +Node: Rounding59097 +Ref: #rounding59215 +Node: Costs59665 +Ref: #costs59781 +Node: Other cost/lot notations61977 +Ref: #other-costlot-notations62109 +Node: Balance assertions64698 +Ref: #balance-assertions64849 +Node: Assertions and ordering65932 +Ref: #assertions-and-ordering66121 +Node: Assertions and multiple included files66821 +Ref: #assertions-and-multiple-included-files67081 +Node: Assertions and multiple -f files67581 +Ref: #assertions-and-multiple--f-files67832 +Node: Assertions and commodities68229 +Ref: #assertions-and-commodities68451 +Node: Assertions and prices69631 +Ref: #assertions-and-prices69837 +Node: Assertions and subaccounts70264 +Ref: #assertions-and-subaccounts70485 +Node: Assertions and virtual postings70809 +Ref: #assertions-and-virtual-postings71047 +Node: Assertions and auto postings71179 +Ref: #assertions-and-auto-postings71409 +Node: Assertions and precision72054 +Ref: #assertions-and-precision72236 +Node: Posting comments72503 +Ref: #posting-comments72649 +Node: Tags73026 +Ref: #tags73140 +Node: Tag values74333 +Ref: #tag-values74422 +Node: Directives75181 +Ref: #directives75308 +Node: Directives and multiple files76638 +Ref: #directives-and-multiple-files76816 +Node: Directive effects77583 +Ref: #directive-effects77737 +Node: account directive80750 +Ref: #account-directive80906 +Node: Account comments82304 +Ref: #account-comments82454 +Node: Account subdirectives82962 +Ref: #account-subdirectives83153 +Node: Account error checking83295 +Ref: #account-error-checking83493 +Node: Account display order84682 +Ref: #account-display-order84870 +Node: Account types85971 +Ref: #account-types86112 +Node: alias directive89739 +Ref: #alias-directive89900 +Node: Basic aliases90950 +Ref: #basic-aliases91081 +Node: Regex aliases91825 +Ref: #regex-aliases91982 +Node: Combining aliases92872 +Ref: #combining-aliases93050 +Node: Aliases and multiple files94326 +Ref: #aliases-and-multiple-files94530 +Node: end aliases directive95109 +Ref: #end-aliases-directive95328 +Node: Aliases can generate bad account names95477 +Ref: #aliases-can-generate-bad-account-names95725 +Node: Aliases and account types96310 +Ref: #aliases-and-account-types96502 +Node: commodity directive97198 +Ref: #commodity-directive97372 +Node: Commodity directive syntax98557 +Ref: #commodity-directive-syntax98742 +Node: Commodity error checking100193 +Ref: #commodity-error-checking100374 +Node: decimal-mark directive100668 +Ref: #decimal-mark-directive100850 +Node: include directive101247 +Ref: #include-directive101411 +Node: P directive102323 +Ref: #p-directive102468 +Node: payee directive103357 +Ref: #payee-directive103506 +Node: tag directive103979 +Ref: #tag-directive104134 +Node: Periodic transactions104602 +Ref: #periodic-transactions104767 +Node: Periodic rule syntax106473 +Ref: #periodic-rule-syntax106651 +Node: Periodic rules and relative dates107296 +Ref: #periodic-rules-and-relative-dates107562 +Node: Two spaces between period expression and description!108073 +Ref: #two-spaces-between-period-expression-and-description108350 +Node: Auto postings109034 +Ref: #auto-postings109182 +Node: Auto postings and multiple files111619 +Ref: #auto-postings-and-multiple-files111783 +Node: Auto postings and dates112184 +Ref: #auto-postings-and-dates112432 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions112607 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112963 +Node: Auto posting tags113466 +Ref: #auto-posting-tags113748 +Node: Auto postings on forecast transactions only114384 +Ref: #auto-postings-on-forecast-transactions-only114630 +Node: Other syntax114877 +Ref: #other-syntax114993 +Node: Balance assignments115620 +Ref: #balance-assignments115776 +Node: Balance assignments and prices117149 +Ref: #balance-assignments-and-prices117364 +Node: Balance assignments and multiple files117575 +Ref: #balance-assignments-and-multiple-files117806 +Node: Bracketed posting dates117999 +Ref: #bracketed-posting-dates118183 +Node: D directive118697 +Ref: #d-directive118865 +Node: apply account directive120465 +Ref: #apply-account-directive120645 +Node: Y directive121332 +Ref: #y-directive121492 +Node: Secondary dates122320 +Ref: #secondary-dates122474 +Node: Star comments123288 +Ref: #star-comments123448 +Node: Valuation expressions123980 +Ref: #valuation-expressions124157 +Node: Virtual postings124279 +Ref: #virtual-postings124456 +Node: Other Ledger directives125893 +Ref: #other-ledger-directives126056 +Node: CSV126622 +Ref: #csv126715 +Node: CSV rules cheatsheet128795 +Ref: #csv-rules-cheatsheet128924 +Node: source130722 +Ref: #source130845 +Node: separator131725 +Ref: #separator131838 +Node: skip132378 +Ref: #skip132486 +Node: date-format133030 +Ref: #date-format133151 +Node: timezone133875 +Ref: #timezone133998 +Node: newest-first135003 +Ref: #newest-first135141 +Node: intra-day-reversed135718 +Ref: #intra-day-reversed135872 +Node: decimal-mark136320 +Ref: #decimal-mark136461 +Node: fields list136800 +Ref: #fields-list136939 +Node: Field assignment138610 +Ref: #field-assignment138754 +Node: Field names139831 +Ref: #field-names139962 +Node: date field141165 +Ref: #date-field141283 +Node: date2 field141331 +Ref: #date2-field141472 +Node: status field141528 +Ref: #status-field141671 +Node: code field141720 +Ref: #code-field141865 +Node: description field141910 +Ref: #description-field142070 +Node: comment field142129 +Ref: #comment-field142284 +Node: account field142577 +Ref: #account-field142727 +Node: amount field143297 +Ref: #amount-field143446 +Node: currency field146138 +Ref: #currency-field146291 +Node: balance field146548 +Ref: #balance-field146680 +Node: if block147052 +Ref: #if-block147173 +Node: Matchers148581 +Ref: #matchers148695 +Node: What matchers match149492 +Ref: #what-matchers-match149641 +Node: Combining matchers150081 +Ref: #combining-matchers150249 +Node: Match groups150735 +Ref: #match-groups150863 +Node: if table151610 +Ref: #if-table151732 +Node: balance-type153294 +Ref: #balance-type153423 +Node: include154123 +Ref: #include154250 +Node: Working with CSV154694 +Ref: #working-with-csv154841 +Node: Rapid feedback155248 +Ref: #rapid-feedback155381 +Node: Valid CSV155833 +Ref: #valid-csv155979 +Node: File Extension156711 +Ref: #file-extension156884 +Node: Reading CSV from standard input157448 +Ref: #reading-csv-from-standard-input157672 +Node: Reading multiple CSV files157836 +Ref: #reading-multiple-csv-files158067 +Node: Reading files specified by rule158308 +Ref: #reading-files-specified-by-rule158536 +Node: Valid transactions159707 +Ref: #valid-transactions159906 +Node: Deduplicating importing160534 +Ref: #deduplicating-importing160729 +Node: Setting amounts161765 +Ref: #setting-amounts161936 +Node: Amount signs164294 +Ref: #amount-signs164464 +Node: Setting currency/commodity165361 +Ref: #setting-currencycommodity165565 +Node: Amount decimal places166739 +Ref: #amount-decimal-places166945 +Node: Referencing other fields167257 +Ref: #referencing-other-fields167470 +Node: How CSV rules are evaluated168367 +Ref: #how-csv-rules-are-evaluated168584 +Node: Well factored rules170037 +Ref: #well-factored-rules170205 +Node: CSV rules examples170529 +Ref: #csv-rules-examples170664 +Node: Bank of Ireland170729 +Ref: #bank-of-ireland170866 +Node: Coinbase172328 +Ref: #coinbase172466 +Node: Amazon173513 +Ref: #amazon173638 +Node: Paypal175357 +Ref: #paypal175465 +Node: Timeclock183109 +Ref: #timeclock183214 +Node: Timedot185392 +Ref: #timedot185515 +Node: Timedot examples188620 +Ref: #timedot-examples188726 +Node: PART 3 REPORTING CONCEPTS190897 +Ref: #part-3-reporting-concepts191079 +Node: Amount formatting parseability191079 +Ref: #amount-formatting-parseability191276 +Node: Time periods193481 +Ref: #time-periods193620 +Node: Report start & end date193738 +Ref: #report-start-end-date193890 +Node: Smart dates195549 +Ref: #smart-dates195702 +Node: Report intervals197570 +Ref: #report-intervals197725 +Node: Date adjustment198143 +Ref: #date-adjustment198303 +Node: Period expressions199154 +Ref: #period-expressions199295 +Node: Period expressions with a report interval201059 +Ref: #period-expressions-with-a-report-interval201293 +Node: More complex report intervals201507 +Ref: #more-complex-report-intervals201752 +Node: Multiple weekday intervals203553 +Ref: #multiple-weekday-intervals203742 +Node: Depth204564 +Ref: #depth204666 +Node: Queries204962 +Ref: #queries205064 +Node: Query types206189 +Ref: #query-types206310 +Node: Combining query terms209646 +Ref: #combining-query-terms209823 +Node: Queries and command options211091 +Ref: #queries-and-command-options211290 +Node: Queries and valuation211539 +Ref: #queries-and-valuation211734 +Node: Querying with account aliases211963 +Ref: #querying-with-account-aliases212174 +Node: Querying with cost or value212304 +Ref: #querying-with-cost-or-value212481 +Node: Pivoting212782 +Ref: #pivoting212896 +Node: Generating data214673 +Ref: #generating-data214805 +Node: Forecasting216388 +Ref: #forecasting216513 +Node: --forecast217044 +Ref: #forecast217175 +Node: Inspecting forecast transactions218221 +Ref: #inspecting-forecast-transactions218423 +Node: Forecast reports219553 +Ref: #forecast-reports219726 +Node: Forecast tags220662 +Ref: #forecast-tags220822 +Node: Forecast period in detail221282 +Ref: #forecast-period-in-detail221476 +Node: Forecast troubleshooting222370 +Ref: #forecast-troubleshooting222538 +Node: Budgeting223441 +Ref: #budgeting223561 +Node: Cost reporting223998 +Ref: #cost-reporting224132 +Node: Recording costs224793 +Ref: #recording-costs224929 +Node: Reporting at cost226520 +Ref: #reporting-at-cost226695 +Node: Equity conversion postings227285 +Ref: #equity-conversion-postings227499 +Node: Inferring equity conversion postings229930 +Ref: #inferring-equity-conversion-postings230193 +Node: Combining costs and equity conversion postings230945 +Ref: #combining-costs-and-equity-conversion-postings231255 +Node: Requirements for detecting equity conversion postings232243 +Ref: #requirements-for-detecting-equity-conversion-postings232565 +Node: Infer cost and equity by default ?233765 +Ref: #infer-cost-and-equity-by-default233994 +Node: Value reporting234202 +Ref: #value-reporting234344 +Node: -V Value235118 +Ref: #v-value235250 +Node: -X Value in specified commodity235445 +Ref: #x-value-in-specified-commodity235646 +Node: Valuation date235795 +Ref: #valuation-date235972 +Node: Finding market price236755 +Ref: #finding-market-price236966 +Node: --infer-market-prices market prices from transactions238135 +Ref: #infer-market-prices-market-prices-from-transactions238417 +Node: Valuation commodity241179 +Ref: #valuation-commodity241398 +Node: Simple valuation examples242611 +Ref: #simple-valuation-examples242815 +Node: --value Flexible valuation243474 +Ref: #value-flexible-valuation243684 +Node: More valuation examples245328 +Ref: #more-valuation-examples245543 +Node: Interaction of valuation and queries246813 +Ref: #interaction-of-valuation-and-queries247060 +Node: Effect of valuation on reports247532 +Ref: #effect-of-valuation-on-reports247735 +Node: PART 4 COMMANDS255432 +Ref: #part-4-commands255581 +Node: Commands overview255960 +Ref: #commands-overview256094 +Node: DATA ENTRY256273 +Ref: #data-entry256397 +Node: DATA CREATION256596 +Ref: #data-creation256750 +Node: DATA MANAGEMENT256868 +Ref: #data-management257033 +Node: REPORTS FINANCIAL257154 +Ref: #reports-financial257329 +Node: REPORTS VERSATILE257634 +Ref: #reports-versatile257807 +Node: REPORTS BASIC258060 +Ref: #reports-basic258212 +Node: HELP258721 +Ref: #help258843 +Node: ADD-ONS258953 +Ref: #add-ons259059 +Node: accounts259638 +Ref: #accounts259771 +Node: activity261658 +Ref: #activity261777 +Node: add262151 +Ref: #add262261 +Node: aregister265072 +Ref: #aregister265193 +Node: aregister and posting dates268081 +Ref: #aregister-and-posting-dates268226 +Node: balance268982 +Ref: #balance269108 +Node: balance features270093 +Ref: #balance-features270233 +Node: Simple balance report272199 +Ref: #simple-balance-report272384 +Node: Balance report line format274009 +Ref: #balance-report-line-format274211 +Node: Filtered balance report276369 +Ref: #filtered-balance-report276561 +Node: List or tree mode276888 +Ref: #list-or-tree-mode277056 +Node: Depth limiting278401 +Ref: #depth-limiting278567 +Node: Dropping top-level accounts279168 +Ref: #dropping-top-level-accounts279368 +Node: Showing declared accounts279678 +Ref: #showing-declared-accounts279877 +Node: Sorting by amount280408 +Ref: #sorting-by-amount280575 +Node: Percentages281245 +Ref: #percentages281404 +Node: Multi-period balance report281952 +Ref: #multi-period-balance-report282152 +Node: Balance change end balance284427 +Ref: #balance-change-end-balance284636 +Node: Balance report types286064 +Ref: #balance-report-types286245 +Node: Calculation type286743 +Ref: #calculation-type286898 +Node: Accumulation type287447 +Ref: #accumulation-type287627 +Node: Valuation type288529 +Ref: #valuation-type288717 +Node: Combining balance report types289718 +Ref: #combining-balance-report-types289912 +Node: Budget report291750 +Ref: #budget-report291912 +Node: Budget report start date297566 +Ref: #budget-report-start-date297744 +Node: Budgets and subaccounts299076 +Ref: #budgets-and-subaccounts299283 +Node: Selecting budget goals302723 +Ref: #selecting-budget-goals302922 +Node: Budget vs forecast303957 +Ref: #budget-vs-forecast304116 +Node: Balance report layout305746 +Ref: #balance-report-layout305926 +Node: Useful balance reports314111 +Ref: #useful-balance-reports314271 +Node: balancesheet315356 +Ref: #balancesheet315501 +Node: balancesheetequity316828 +Ref: #balancesheetequity316986 +Node: cashflow318382 +Ref: #cashflow318513 +Node: check319948 +Ref: #check320062 +Node: Default checks320866 +Ref: #default-checks320992 +Node: Strict checks321489 +Ref: #strict-checks321634 +Node: Other checks322114 +Ref: #other-checks322256 +Node: Custom checks322789 +Ref: #custom-checks322946 +Node: More about specific checks323363 +Ref: #more-about-specific-checks323525 +Node: close324231 +Ref: #close324342 +Node: close and balance assertions327807 +Ref: #close-and-balance-assertions327985 +Node: Example retain earnings329136 +Ref: #example-retain-earnings329353 +Node: Example migrate balances to a new file329785 +Ref: #example-migrate-balances-to-a-new-file330050 +Node: Example excluding closing/opening transactions330626 +Ref: #example-excluding-closingopening-transactions330875 +Node: codes332093 +Ref: #codes332210 +Node: commodities333074 +Ref: #commodities333202 +Node: demo333272 +Ref: #demo333393 +Node: descriptions334309 +Ref: #descriptions334439 +Node: diff334730 +Ref: #diff334845 +Node: files335887 +Ref: #files335996 +Node: help336137 +Ref: #help-1336246 +Node: import337619 +Ref: #import337742 +Node: Deduplication338850 +Ref: #deduplication338975 +Node: Import testing340994 +Ref: #import-testing341159 +Node: Importing balance assignments342002 +Ref: #importing-balance-assignments342208 +Node: Commodity display styles342857 +Ref: #commodity-display-styles343030 +Node: incomestatement343159 +Ref: #incomestatement343301 +Node: notes344629 +Ref: #notes344751 +Node: payees345113 +Ref: #payees345228 +Node: prices345747 +Ref: #prices345862 +Node: print346515 +Ref: #print346630 +Node: print explicitness347606 +Ref: #print-explicitness347749 +Node: print amount style348528 +Ref: #print-amount-style348698 +Node: print parseability349750 +Ref: #print-parseability349922 +Node: print other features350671 +Ref: #print-other-features350850 +Node: print output format351371 +Ref: #print-output-format351519 +Node: register354638 +Ref: #register354760 +Node: Custom register output359791 +Ref: #custom-register-output359922 +Node: rewrite361266 +Ref: #rewrite361384 +Node: Re-write rules in a file363282 +Ref: #re-write-rules-in-a-file363445 +Node: Diff output format364594 +Ref: #diff-output-format364777 +Node: rewrite vs print --auto365869 +Ref: #rewrite-vs.-print---auto366029 +Node: roi366585 +Ref: #roi366692 +Node: Spaces and special characters in --inv and --pnl368504 +Ref: #spaces-and-special-characters-in---inv-and---pnl368744 +Node: Semantics of --inv and --pnl369232 +Ref: #semantics-of---inv-and---pnl369471 +Node: IRR and TWR explained371321 +Ref: #irr-and-twr-explained371481 +Node: stats374734 +Ref: #stats374842 +Node: tags376229 +Ref: #tags-1376336 +Node: test377345 +Ref: #test377438 +Node: PART 5 COMMON TASKS378180 +Ref: #part-5-common-tasks378326 +Node: Getting help378624 +Ref: #getting-help378765 +Node: Constructing command lines379525 +Ref: #constructing-command-lines379726 +Node: Starting a journal file380383 +Ref: #starting-a-journal-file380585 +Node: Setting LEDGER_FILE381787 +Ref: #setting-ledger_file381979 +Node: Setting opening balances382936 +Ref: #setting-opening-balances383137 +Node: Recording transactions386278 +Ref: #recording-transactions386467 +Node: Reconciling387023 +Ref: #reconciling387175 +Node: Reporting389432 +Ref: #reporting389581 +Node: Migrating to a new file393566 +Ref: #migrating-to-a-new-file393723 +Node: BUGS394022 +Ref: #bugs394112 +Node: Troubleshooting394991 +Ref: #troubleshooting395091  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -16,8951 +16,8964 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.32. It - also describes the common options, file formats and concepts used by - all hledger programs. It might accidentally teach you some bookkeep- - ing/accounting as well! You don't need to know everything in here to - use hledger productively, but when you have a question about function- - ality, this doc should answer it. It is detailed, so do skip ahead or - skim when needed. You can read it on hledger.org, or as an info manual - or man page on your system. You can also get it from hledger itself - with - hledger --man, hledger --info or hledger help [TOPIC]. - - The main function of the hledger CLI is to read plain text files de- - scribing financial transactions, crunch the numbers, and print a useful - report on the terminal (or save it as HTML, CSV, JSON or SQL). Many - reports are available, as subcommands. hledger will also detect other - hledger-* executables as extra subcommands. - - hledger usually reads from (and appends to) a journal file specified by - the LEDGER_FILE environment variable (defaulting to - $HOME/.hledger.journal); or you can specify files with -f options. It - can also read timeclock files, timedot files, or any CSV/SSV/TSV file - with a date field. - - Here is a small journal file describing one transaction: - - 2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more - accounts: bank accounts, your wallet, revenue/expense categories, peo- - ple, etc. You can choose any account names you wish, using : to indi- - cate subaccounts. There must be at least two spaces between account - name and amount. Positive amounts are inflow to that account (debit), - negatives are outflow from it (credit). (Some reports show revenue, - liability and equity account balances as negative numbers as a result; - this is normal.) - - hledger's add command can help you add transactions, or you can install - other data entry UIs like hledger-web or hledger-iadd. For more exten- - sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM + - vim-ledger, or VS Code + hledger-vscode are some good choices (see - https://hledger.org/editors.html). - - To get started, run hledger add and follow the prompts, or save some - entries like the above in $HOME/.hledger.journal, then try commands - like: - hledger print -x - hledger aregister assets - hledger balance - hledger balancesheet - hledger incomestatement. - Run hledger to list the commands. See also the "Starting a journal - file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -PART 1: USER INTERFACE -Input - hledger reads one or more data files, each time you run it. You can - specify a file with -f, like so - - $ hledger -f FILE print - - Files are most often in hledger's journal format, with the .journal - file extension (.hledger or .j also work); these files describe trans- - actions, like an accounting general journal. - - When no file is specified, hledger looks for .hledger.journal in your - home directory. - - But most people prefer to keep financial files in a dedicated folder, - perhaps with version control. Also, starting a new journal file each - year is common (it's not required, but helps keep things fast and or- - ganised). So we usually configure a different journal file, by setting - the LEDGER_FILE environment variable, to something like ~/fi- - nance/2023.journal. For more about how to do that on your system, see - Common tasks > Setting LEDGER_FILE. - - 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 .journal .j .hledger .ledger - Ledger journals, for transac- - tions - timeclock timeclock files, for precise .timeclock - time logging - timedot timedot files, for approximate .timedot - time logging - csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules - rated values, for data import .ssv.rules .tsv.rules - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a - recognised file extension, so as to either read successfully or to show - relevant error messages. - - You can also force a specific reader/format by prefixing the file path - with the format and a colon. Eg, to read a .dat file as csv format: - - $ hledger -f csv:/some/csv-file.dat stats - - Standard input - The file name - means standard input: - - $ cat FILE | hledger -f- print - - If reading non-journal data in this way, you'll need to add a file for- - mat prefix, like: - - $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- - - Multiple files - You can specify multiple -f options, to read multiple files as one big - journal. When doing this, note that certain features (described below) - will be affected: - - o Balance assertions will not see the effect of transactions in previ- - ous files. (Usually this doesn't matter as each file will set the - corresponding opening balances.) - - o Some directives will not affect previous or subsequent files. - - If needed, you can work around these by using a single parent file - which includes the others, or concatenating the files into one, 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. - -Commands - hledger provides various subcommands for getting things done. Most of - these commands do not change the journal file; they just read it and - output a report. A few commands assist with adding data and file man- - agement. - - To show the commands list, run hledger with no arguments. The commands - are described in detail in PART 4: COMMANDS, below. - - To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], - - o CMD is the full command name, or its standard abbreviation shown in - the commands list, or any unambiguous prefix of the name. - - o CMDOPTS are command-specific options, if any. Command-specific op- - tions must be written after the command name. Eg: hledger print -x. - - o CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit the - data in some way. Eg: hledger reg assets:checking. - - To list a command's options, arguments, and documentation in the termi- - nal, run hledger CMD -h. Eg: hledger bal -h. - - Add-on commands - In addition to the built-in commands, you can install add-on commands: - programs or scripts named "hledger-SOMETHING", which will also appear - in hledger's commands list. If you used the hledger-install script, - you will have several add-ons installed already. Some more can be - found in hledger's bin/ directory, documented at - https://hledger.org/scripts.html. - - More precisely, add-on commands are programs or scripts in your shell's - PATH, whose name starts with "hledger-" and ends with no extension or a - recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", - ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix - and mac) which has executable permission for the current user. - - You can run add-on commands using hledger, much like built-in commands: - hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double - hyphen argument, required before add-on-specific options. Eg: hledger - ui -- --watch or hledger web -- --serve. If this causes difficulty, - you can always run the add-on directly, without using hledger: hledger- - ui --watch or hledger-web --serve. - -Options - Run hledger -h to see general command line help, and general options - which are common to most hledger commands. These options can be writ- - ten anywhere on the command line. They can be grouped into help, in- - put, and reporting options: - - 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 de- - clared) - - 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 ef- - fects) - - --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-equity - infer conversion equity postings from costs - - --infer-costs - infer costs from conversion equity postings - - --infer-market-prices - use costs as additional market prices, as if they were P direc- - tives - - --forecast - generate transactions from periodic rules, between the latest - recorded txn and 6 months from today, or during the specified - PERIOD (= is required). Auto posting rules will be applied to - these transactions as well. Also, in hledger-ui make future- - dated transactions visible. - - --auto generate extra postings by applying auto posting rules to all - txns (not just forecast txns) - - --verbose-tags - add visible tags indicating transactions or postings which have - been generated/modified - - --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 line tips - Here are some details useful to know about for hledger command lines - (and elsewhere). Feel free to skip this section until you need it. - - Option repetition - If options are repeated in a command line, hledger will generally use - the last (right-most) occurence. - - 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 ac- - count 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 be- - low), 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:\\$ - - 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 de- - code 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 - A regular expression (regexp) is a small piece of text where certain - characters (like ., ^, $, +, *, (), |, [], \) have special meanings, - forming a tiny language for matching text precisely - very useful in - hledger and elsewhere. To learn all about them, visit regular-expres- - sions.info. - - hledger supports regexps whenever you are entering a pattern to match - something, eg in query arguments, account aliases, CSV if rules, - hledger-web's search form, hledger-ui's / search, etc. You may need to - wrap them in quotes, especially at the command line (see Special char- - acters above). Here are some examples: - - Account name queries (quoted for command line use): - - Regular expression: Matches: - ------------------- ------------------------------------------------------------ - bank assets:bank, assets:bank:savings, expenses:art:banksy, ... - :bank assets:bank:savings, expenses:art:banksy - :bank: assets:bank:savings - '^bank' none of those ( ^ matches beginning of text ) - 'bank$' assets:bank ( $ matches end of text ) - 'big \$ bank' big $ bank ( \ disables following character's special meaning ) - '\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) - '(sav|check)ing' saving or checking ( (|) matches either alternative ) - 'saving|checking' saving or checking ( outer parentheses are not needed ) - 'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) - 'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) - 'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) - 'b.nk' bank, bonk, b nk, ... ( . matches any character ) - - Some other queries: - - desc:'amazon|amzn|audible' Amazon transactions - cur:EUR amounts with commodity symbol containing EUR - cur:'\$' amounts with commodity symbol containing $ - cur:'^\$$' only $ amounts, not eg AU$ or CA$ - cur:....? amounts with 4-or-more-character symbols - tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 - - Account name aliases: accept . instead of : as account separator: - - alias /\./=: replaces all periods in account names with colons - - Show multiple top-level accounts combined as one: - - --alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) - - Show accounts with the second-level part removed: - - --alias '/^([^:]+):[^:]+/ = \1' - match a top-level account and a second-level account - and replace those with just the top-level account - ( \1 in the replacement text means "whatever was matched - by the first parenthesised part of the regexp" - - CSV rules: match CSV records containing dining-related MCC codes: - - if \?MCC581[124] - - Match CSV records with a specific amount around the end/start of month: - - if %amount \b3\.99 - & %date (29|30|31|01|02|03)$ - - hledger's regular expressions - 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. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the re- - placement string to reference capturing groups in the search regexp. - Otherwise, if you write \1, it will match the digit 1. - - 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. - - Argument files - You can save a set of command line options and arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: - hledger bal @foo.args. - - Inside the argument file, each line should contain just one option or - argument. Don't use spaces except inside quotes (or you'll see a con- - fusing error); write = (or nothing) between a flag and its argument. - For the special characters mentioned above, use one less level of quot- - ing than you would at the command prompt. - -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) - - Output format - Some commands offer other kinds of output, not just text on the termi- - nal. Here are those commands and the formats currently supported: - - - txt csv/tsv html json sql - -------------------------------------------------------------------------------------- - aregister Y Y Y Y - balance Y 1 Y 1 Y 1,2 Y - balancesheet Y 1 Y 1 Y 1 Y - balancesheete- Y 1 Y 1 Y 1 Y - quity - 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 - - 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 - - Some notes about the various output formats: - - 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 This is not yet much used; real-world feedback is welcome. - - o Our JSON is rather large and verbose, since it is a faithful repre- - sentation 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 This is not yet much used; real-world feedback is welcome. - - o SQL output is expected to work at least with SQLite, MySQL and Post- - gres. - - o For SQLite, it will be more useful if you modify the generated id - field to be a PRIMARY KEY. Eg: - - $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - - 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 - When displaying amounts, hledger infers a standard display style for - each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a -c/--commodity-style option (ex- - cept for cost amounts and amounts displayed by the print command, which - are always displayed with all decimal digits). For example, the fol- - lowing will force dollar amounts to be displayed as shown: - - $ hledger print -c '$1.000,0' - - This option can repeated to set the display style for multiple commodi- - ties/currencies. Its argument is as described in the commodity direc- - tive. - - Colour - In terminal output, some commands can produce colour when the terminal - supports it: - - o if the --color/--colour option is given a value of yes or always (or - no or never), colour will (or will not) be used; - - o otherwise, if the NO_COLOR environment variable is set, colour will - not be used; - - o otherwise, colour will be used if the output (terminal or file) sup- - ports it. - - Box-drawing - In terminal output, you can enable unicode box-drawing characters to - render prettier tables: - - o if the --pretty option is given a value of yes or always (or no or - never), unicode characters will (or will not) be used; - - o otherwise, unicode characters will not be used. - - Paging - When showing long output in the terminal, hledger will try to use the - pager specified by the PAGER environment variable, or less, or more. - (A pager is a helper program that shows one page at a time rather than - scrolling everything off screen). Currently it does this only for help - output, not for reports; specifically, - - o when listing commands, with hledger - - o when showing help with hledger [CMD] --help, - - o when viewing manuals with hledger help or hledger --man. - - Note the pager is expected to handle ANSI codes, which hledger uses eg - for bold emphasis. For the common pager less (and its more compatibil- - ity mode), we add R to the LESS and MORE environment variables to make - this work. If you use a different pager, you might need to configure - it similarly, to avoid seeing junk on screen (let us know). Otherwise, - you can set the NO_COLOR environment variable to 1 to disable all ANSI - output (see Colour). - - Debug output - We intend hledger to be relatively easy to troubleshoot, introspect and - develop. You can add --debug[=N] to any hledger command line to see - additional debug output. N ranges from 1 (least output, the default) - to 9 (maximum output). Typically you would start with 1 and increase - until you are seeing enough. Debug output goes to stderr, and is not - affected by -o/--output-file (unless you redirect stderr to stdout, eg: - 2>&1). It will be interleaved with normal output, which can help re- - veal when parts of the code are evaluated. To capture debug output in - a log file instead, you can usually redirect stderr, eg: - - hledger bal --debug=3 2>hledger.log - -Environment - These environment variables affect hledger: - - COLUMNS This is normally set by your terminal; some hledger commands - (register) will format their output to this width. If not set, they - will try to use the available terminal width. - - LEDGER_FILE The main journal file to use when not specified with - -f/--file. Default: $HOME/.hledger.journal. - - NO_COLOR If this environment variable is set (with any value), hledger - will not use ANSI color codes in terminal output, unless overridden by - an explicit --color/--colour option. - -PART 2: DATA FORMATS -Journal - hledger's default file format, representing a General Journal. Here's - a cheatsheet/mini-tutorial, or you can skip ahead to About journal for- - mat. - - Journal cheatsheet - # Here is the main syntax of hledger's journal format - # (omitting extra Ledger compatibility syntax). - # hledger journals contain comments, directives, and transactions, in any order: - - ############################################################################### - # 1. Comment lines are for notes or temporarily disabling things. - # They begin with #, ;, or a line containing the word "comment". - - # hash comment line - ; semicolon comment line - comment - These lines - are commented. - end comment - - # Some but not all hledger entries can have same-line comments attached to them, - # from ; (semicolon) to end of line. - - ############################################################################### - # 2. Directives modify parsing or reports in some way. - # They begin with a word or letter (or symbol). - - account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. - account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) - alias chkg = assets:checking - commodity $0.00 - decimal-mark . - include /dev/null - payee Whole Foods - P 2022-01-01 AAAA $1.40 - ~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - - ############################################################################### - # 3. Transactions are what it's all about; they are dated events, - # usually describing movements of money. - # They begin with a date. - - # DATE DESCRIPTION ; This is a transaction comment. - # ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. - # ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. - # ; ^^ At least 2 spaces between account and amount. - # ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - - 2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - - 2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - - 2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - - 2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - - 2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - - 1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - - 2022.01.01 These date - 2022/1/1 formats are - 12/31 also allowed (but consistent YYYY-MM-DD is recommended). - - About journal format - hledger's usual data source is a plain text file containing journal en- - tries in hledger journal format. This file represents a standard ac- - counting 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 compatible with most of Ledger's journal - format, but not all of it. The differences and interoperation tips are - described at hledger and Ledger. With some care, and by avoiding in- - compatible features, you can keep your hledger journal readable by - Ledger and vice versa. This can useful eg for comparing the behaviour - of one app against the other. - - 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). - - A hledger journal file can contain three kinds of thing: file comments, - transactions, and/or directives (counting periodic transaction rules - and auto posting rules as directives). - - Comments - Lines in the journal will be ignored if they begin with a hash (#) or a - semicolon (;). (See also Other syntax.) hledger will also ignore re- - gions beginning with a comment line and ending with an end comment line - (or file end). Here's a suggestion for choosing between them: - - o # for top-level notes - - o ; for commenting out things temporarily - - o comment for quickly commenting large regions (remember it's there, or - you might get confused) - - Eg: - - # a comment line - ; another commentline - comment - A multi-line comment block, - continuing until "end comment" directive - or the end of the current file. - end comment - - Some hledger entries can have same-line comments attached to them, from - ; (semicolon) to end of line. See Transaction comments, Posting com- - ments, and Account comments below. - - 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 op- - tional 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 Y directive, or the cur- - rent 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.) - - 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 re- - ports, and the deduction from checking should be reported on 6/1 for - easy bank reconciliation: - - 2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - - $ hledger -f t.j register food - 2015-05-30 expenses:food $10 $10 - - $ hledger -f t.j register checking - 2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. - The date: tag must have a valid simple date value if it is present, eg - a date: tag with no value is not allowed. - - Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction de- - scription or posting account name, separated from it by a space, indi- - cating 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 un- - marked 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 un- - cashed 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 (af- - ter the first |). This may be worthwhile if you need to do more pre- - cise querying and pivoting by payee or by note. - - Transaction comments - Text following ;, after a transaction description, and/or on indented - lines immediately below it, form comments for that transaction. They - are reproduced by print but otherwise ignored, except they may contain - tags, which are not ignored. - - 2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - 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 - spaces. But if you accidentally leave only one space (or tab) before - the amount, the amount will be considered part of the account name. - - Account names - Accounts are the main way of categorising things in hledger. As in - Double Entry Bookkeeping, they can represent real world accounts (such - as a bank account), or more abstract categories such as "money borrowed - from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the - traditional accounting categories, which in english are assets, liabil- - ities, equity, revenues, expenses. (You might see these referred to as - A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts - into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking - and expenses:food, hledger will infer this hierarchy of five accounts: - - assets - assets:bank - assets:bank:checking - expenses - expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - - assets - bank - checking - expenses - food - - hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account - names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or - more spaces (or tabs). - - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to - the account name have no special meaning. - - Account names can be altered temporarily or permanently by account - aliases. - - Amounts - After the account name, there is usually an amount. (Important: be- - tween 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,23 - - 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 - - hledger is not biased towards period or comma decimal marks, so a num- - ber containing just one period or comma, like 1,000 or 1.000, is am- - biguous. In such cases hledger assumes it is a decimal mark, parsing - both of these as 1. - - To disambiguate these and ensure accurate number parsing, especially if - you use digit group marks, we recommend declaring the decimal mark. - You can declare it for each file with decimal-mark directives, or for - each commodity with commodity directives (described 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, but here's a quick example: - - # the decimal mark character used by all amounts in this file (all commodities) - decimal-mark . - - # display styles for the $, EUR, INR and no-symbol commodities: - commodity $1,000.00 - commodity EUR 1.000,00 - commodity INR 9,99,99,999.00 - commodity 1 000 000.9455 - - Commodity display style - For the amounts in each commodity, hledger chooses a consistent display - style (symbol placement, decimal mark and digit group marks, number of - decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a D directive declaring a default commodity, that - commodity symbol and amount format is applied to all no-symbol amounts - in the journal. - - Then each commodity's display style is determined from its commodity - directive. We recommend always declaring commodities with commodity - directives, since they help ensure consistent display styles and preci- - sions, and bring other benefits such as error checking for commodity - symbols. - - But if a commodity directive is not present, hledger infers a commod- - ity's display styles from its amounts as they are written in the jour- - nal (excluding cost amounts and amounts in periodic transaction rules - or auto posting rules). It uses - - o the symbol placement and decimal mark of the first amount seen - - o the digit group marks of the first amount with digit group marks - - o and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a de- - fault style, like $1000.00 (symbol on the left with no space, period as - decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -c/--commodity-style - command line option. - - Rounding - Amounts are stored internally as decimal numbers with up to 255 decimal - places. They are displayed with their original journal precisions by - print and print-like reports, and rounded to their display precision - (the number of decimal digits specified by the commodity display style) - by other reports. When rounding, hledger uses banker's rounding (it - rounds to the nearest even digit). So eg 0.5 displayed with zero deci- - mal digits appears as "0". - - Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- - tion, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, - discussions, or code; that term was directionally neutral and reminded - that it is a price specific to a transaction, but we now just call it - "cost", with the understanding that the transaction could be a purchase - or a sale.) - - Costs are usually written explicitly with @ or @@, but can also be in- - ferred automatically for simple multi-commodity transactions. Note, if - costs are inferred, the order of postings is significant; the first - posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign - currency in hledger, using the cost notation either explicitly or im- - plicitly: - - 1. Write the price per unit, as @ UNITPRICE after the amount: - - 2009/1/1 - assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as @@ TOTALPRICE after the amount: - - 2009/1/1 - assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, and - let hledger infer the price that balances the transaction. Note the - effect of posting order: the price is added to first posting, making - it 100 @@ $135, as in example 2: - - 2009/1/1 - assets:euros 100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the -B/--cost - flag; this is discussed more in the Cost reporting section. - - Note that the cost normally should be a positive amount, though it's - not required to be. This can be a little confusing, see discussion at - --infer-market-prices: market prices from transactions. - - Other cost/lot notations - A slight digression for Ledger and Beancount users. Ledger has a num- - ber of cost/lot-related notations: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a conversion rate, as in hledger - - o when buying, also creates a lot than can be selected at selling - time - - o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - - o like the above, but also means "this cost was exceptional, don't - use it when inferring market prices". - - Currently, hledger treats the above like @ and @@; the parentheses are - ignored. - - o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) - - o when buying, means "this cost is also the fixed price, don't let it - fluctuate in value reports" - - o {UNITCOST} and {{TOTALCOST}} (lot price) - - o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- - ates a lot - - o when selling, combined with @ ..., specifies an investment lot by - its cost basis; does not check if that lot is present - - o and related: [YYYY/MM/DD] (lot date) - - o when buying, attaches this acquisition date to the lot - - o when selling, selects a lot by its acquisition date - - o (SOME TEXT) (lot note) - - o when buying, attaches this note to the lot - - o when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after - the posting amount, but ignores them. (This can break transaction bal- - ancing.) - - For Beancount users, the notation and behaviour is different: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a cost without creating a lot, as in hledger - - o when buying (augmenting) or selling (reducing) a lot, combined with - {...}: documents the cost/selling price (not used for transaction - balancing) - - o {UNITCOST} and {{TOTALCOST}} - - o when buying (augmenting), expresses the cost for transaction bal- - ancing, and also creates a lot with this cost basis attached - - o when selling (reducing), - - o selects a lot by its cost basis - - o raises an error if that lot is not present or can not be selected - unambiguously (depending on booking method configured) - - o expresses the selling price for transaction balancing - - Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but - ignores it. - - o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- - COST, YYYY-MM-DD, "LABEL"} etc. - - Currently, hledger rejects these. - - 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, described 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 or- - der 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 in- - clude, 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 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 - - Assertions and prices - Balance assertions ignore costs, and should normally be written without - one: - - 2019/1/1 - (a) $1 @ 1 = $1 - - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance 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. - - Posting comments - Text following ;, at the end of a posting line, and/or on indented - lines immediately below it, form comments for that posting. They are - reproduced by print but otherwise ignored, except they may contain - tags, which are not ignored. - - 2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - Tags - Tags are a way to add extra labels or labelled data to transactions, - postings, or accounts, which you can then search or pivot on. - - They are written as a word (optionally hyphenated) immediately followed - by a full colon, in a transaction or posting or account directive's - comment. (This is an exception to the usual rule that things in com- - ments are ignored.) Eg, here four different tags are recorded: one on - the checking account, two on the transaction, and one on the expenses - posting: - - account assets:checking ; accounttag: - - 2017/1/16 bought groceries ; transactiontag-1: - ; transactiontag-2: - assets:checking $-1 - expenses:food $1 ; postingtag: - - Postings also inherit tags from their transaction and their account. - And transactions also acquire tags from their postings (and postings' - accounts). So in the example above, the expenses posting effectively - has all four tags (by inheriting from account and transaction), and the - transaction also has all four tags (by acquiring from the expenses - posting). - - You can list tag names with hledger tags [NAMEREGEX], or match by tag - name with a tag:NAMEREGEX query. - - Tag values - Tags can have a value, which is any text after the colon up until a - comma or end of line (with surrounding whitespace removed). Note this - means that hledger tag values can not contain commas. Eg in the fol- - lowing posting, the three tags' values are "value 1", "value 2", and "" - (empty) respectively: - - expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - - Note that tags can be repeated, and are additive rather than overrid- - ing: when the same tag name is seen again with a new value, the new - name:value pair is added to the tags. (It is not possible to override - a tag's value or remove a tag.) - - You can list a tag's values with hledger tags TAGNAME --values, or - match by tag value with a tag:NAMEREGEX=VALUEREGEX query. - - Directives - Besides transactions, there is something else you can put in a journal - file: directives. These are declarations, beginning with a keyword, - that modify hledger's behaviour. Some directives can have more spe- - cific subdirectives, indented below them. hledger's directives are - similar to Ledger's in many cases, but there are also many differences. - Directives are not required, but can be useful. Here are the main di- - rectives: - - purpose directive - -------------------------------------------------------------------------- - READING DATA: - Rewrite account names alias - Comment out sections of the file comment - Declare file's decimal mark, to help decimal-mark - parse amounts accurately - Include other data files include - GENERATING DATA: - Generate recurring transactions or bud- ~ - get goals - Generate extra postings on existing = - transactions - CHECKING FOR ERRORS: - Define valid entities to provide more account, commodity, payee, tag - error checking - REPORTING: - Declare accounts' type and display order account - Declare commodity display styles commodity - Declare market prices P - - Directives and multiple files - Directives vary in their scope, ie which journal entries and which in- - put files they affect. Most often, a directive will affect the follow- - ing entries and included files if any, until the end of the current - file - and no further. You might find this inconvenient! For example, - alias directives do not affect parent or sibling files. But there are - usually workarounds; for example, put alias directives in your top-most - file, before including other files. - - The restriction, though it may be annoying at first, is in a good - cause; it allows reports to be stable and deterministic, independent of - the order of input. Without it, reports could show different numbers - depending on the order of -f options, or the positions of include di- - rectives in your files. - - Directive effects - Here are all hledger's directives, with their effects and scope sum- - marised - nine main directives, plus four others which we consider non- - essential: - - di- what it does ends - rec- at - tive file - end? - -------------------------------------------------------------------------------------- - ac- Declares an account, for checking all entries in all files; and N - count its display order and type. Subdirectives: any text, ignored. - alias Rewrites account names, in following entries until end of cur- Y - rent file or end aliases. Command line equivalent: --alias - com- Ignores part of the journal file, until end of current file or Y - ment end comment. - com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N - mod- all amounts in all files 2. the decimal mark for parsing - ity amounts of this commodity, in the following entries until end of - current file (if there is no decimal-mark directive) 3. and the - display style for amounts of this commodity 4. which is also - the precision to use for balanced-transaction checking in this - commodity. Takes precedence over D. Subdirectives: format - (Ledger-compatible syntax). Command line equivalent: -c/--com- - modity-style - deci- Declares the decimal mark, for parsing amounts of all commodi- Y - mal- ties in following entries until next decimal-mark or end of cur- - mark rent file. Included files can override. Takes precedence over - commodity and D. - in- Includes entries and directives from another file, as if they N - clude were written inline. Command line alternative: multiple - -f/--file - payee Declares a payee name, for checking all entries in all files. N - P Declares the market price of a commodity on some date, for value N - reports. - ~ Declares a periodic transaction rule that generates future N - (tilde) transactions with --forecast and budget goals with balance - --budget. - Other - syntax: - apply Prepends a common parent account to all account names, in fol- Y - account lowing entries until end of current file or end apply account. - D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no commodity directive for this commodity: its decimal - mark, balancing precision, and display style, as above. - Y Sets a default year to use for any yearless dates, in following Y - entries until end of current file. - = Declares an auto posting rule that generates extra postings on partly - (equals) matched transactions with --auto, in current, parent, and child - files (but not sibling files, see #1212). - Other Other directives from Ledger's file format are accepted but ig- - Ledger nored. - direc- - tives - - account directive - 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 In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - - o They control account display order in reports, allowing non-alpha- - betic sorting (eg Revenues to appear above Expenses). - - o They help with account name completion (in hledger add, hledger-web, - hledger-iadd, ledger-mode, etc.) - - o They can store additional account information as comments, or as tags - which can be used to filter or pivot reports. - - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - - They are written as the word account followed by a hledger-style ac- - count name, eg: - - account assets:bank:checking - - Note, however, that accounts declared in account directives are not al- - lowed to have surrounding brackets and parentheses, unlike accounts - used in postings. So the following journal will not parse: - - account (assets:bank:checking) - - Account comments - Text following two or more spaces and ; at the end of an account direc- - tive line, and/or following ; on indented lines immediately below it, - form comments for that account. They are ignored except they may con- - tain tags, which are not ignored. - - The two-space requirement for same-line account comments is because ; - is allowed in account names. - - account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - Account subdirectives - Ledger-style indented subdirectives are also accepted, but currently - ignored: - - account assets:bank:checking - format subdirective is ignored - - Account error checking - By default, accounts need not be declared; they come into existence - when a posting references them. This is convenient, but it means - hledger can't warn you when you mis-spell an account name in the jour- - nal. Usually you'll find that error later, as an extra account in bal- - ance 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 de- - clared 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 ac- - count 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 in- - cluded files of all types. - - o It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - Account display order - The order in which account directives are written influences the order - in which accounts appear in reports, hledger-ui, hledger-web etc. By - default accounts appear in alphabetical order, but if you add these ac- - count directives to the journal file: - - account assets - account liabilities - account equity - account revenues - account expenses - - those accounts will be displayed in declaration order: - - $ hledger accounts -1 - assets - liabilities - equity - revenues - expenses - - Any undeclared accounts are displayed last, in alphabetical order. - - Sorting is done at each level of the account tree, within each group of - sibling accounts under the same parent. And currently, this directive: - - account other:zoo - - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - - o you will sometimes declare parent accounts (eg account other above) - that you don't intend to post to, just to customize their display or- - der - - o sibling accounts stay together (you couldn't display x:y in between - a:b and a:c). - - 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 (de- - scribed below). But generally we recommend you declare types explic- - itly, by adding a type: tag to your top-level account directives. Sub- - accounts 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 Cost re- - porting).) - - 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. - - 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 ac- - count for all of the account types, 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] - - alias directive - You can define account alias rules which rewrite your account names, or - parts of them, before generating reports. This can be useful for: - - 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 re- - place any occurrence of the old account name with the new one. Subac- - counts 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 ex- - pression.) - - Eg: - - alias /REGEX/ = REPLACEMENT - - or: - - $ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by RE- - PLACEMENT. 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. In- - cluding the aliases doesn't work either: - - include a.aliases - - 2023-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 - - 2023-01-01 ; affected by aliases above - foo 1 - bar - - include c.journal ; also affected - - end aliases directive - 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 ef- - fect. - - 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 - - commodity directive - The commodity directive performs several functions: - - 1. It declares which commodity symbols may be used in the journal, en- - abling useful error checking with strict mode or the check command. - (See Commodity error checking below.) - - 2. It declares the precision with which this commodity's amounts should - be compared when checking for balanced transactions. - - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See Commodity display style above.) - - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no decimal-mark - directive in effect. See Decimal marks, digit group marks above. - For related dev discussion, see #793.) - - Declaring commodities solves several common parsing/display problems, - so we recommend it. Generally you should put commodity directives at - the top of your journal file (because function 4 is position-sensi- - tive). - - Commodity directive syntax - A commodity directive is normally the word commodity followed by a sam- - ple amount (and optionally a comment). Only the amount's symbol and - format is significant. Eg: - - commodity $1000.00 - commodity 1.000,00 EUR - commodity 1 000 000.0000 ; the no-symbol commodity - - A commodity directive's sample amount must always include a period or - comma decimal mark (this rule helps disambiguate decimal marks and - digit group marks). If you don't want to show any decimal digits, - write the decimal mark at the end: - - commodity 1000. AAAA ; show AAAA with no decimals - - Commodity symbols containing spaces, numbers, or punctuation must be - enclosed in double quotes, as usual: - - commodity 1.0000 "AAAA 2023" - - Commodity directives normally include a sample amount, but can declare - only a symbol (ie, just function 1 above): - - commodity $ - commodity INR - commodity "AAAA 2023" - commodity "" ; the no-symbol commodity - - Commodity directives may also be written with an indented format subdi- - rective, as in Ledger. The symbol is repeated and must be the same in - both places. Other subdirectives are currently ignored: - - ; 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 - an unsupported subdirective ; ignored by hledger - - Commodity error checking - In strict mode (-s/--strict) (or when you run hledger check commodi- - ties), hledger will report an error if an undeclared commodity symbol - is used. (With one exception: zero amounts are always allowed to have - no commodity symbol.) It works like account error checking (described - above). - - decimal-mark directive - You can use a decimal-mark directive - usually one per file, at the top - of the file - to declare which character represents a decimal mark when - parsing amounts in this file. It can look like - - decimal-mark . - - or - - decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we - recommend it, especially if the file contains digit group marks (eg - thousands separators). - - include directive - You can pull in the content of additional files by writing an include - directive, like this: - - include FILEPATH - - Only journal files can include, and only journal, timeclock or timedot - files can be included (not CSV files, currently). - - If the file path does not begin with a slash, it is relative to the - current file's folder. - - A tilde means home directory, eg: include ~/main.journal. - - The path may contain glob patterns to match multiple files, eg: include - *.journal. - - There is limited support for recursive wildcards: **/ (the slash is re- - quired) 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 Data formats): include time- - dot:~/notes/2023*.md. - - P directive - The P directive declares a market price, which is a conversion rate be- - tween two commodities on a certain date. This allows value reports to - convert amounts of one commodity to their value in another, on or after - that date. These prices are often obtained from a stock exchange, - cryptocurrency exchange, the or foreign exchange market. - - The format is: - - P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity - being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) - of commodity 2 that one unit of commodity 1 is worth on this date. Ex- - amples: - - # 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 Value reporting. - - payee directive - payee PAYEE NAME - - This directive can be used to declare a limited set of payees which may - appear in transaction descriptions. The "payees" check will report an - error if any transaction refers to a payee that has not been declared. - Eg: - - payee Whole Foods - - Any indented subdirectives are currently ignored. - - tag directive - tag TAGNAME - - This directive can be used to declare a limited set of tag names al- - lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - - tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is - used. It is quite easy to accidentally create a tag through normal use - of colons in comments(#comments]; if you want to prevent this, you can - declare and check your tags . - - Periodic transactions - The ~ directive declares recurring transactions. Such directives allow - hledger to generate temporary future transactions (visible in reports, - not in the journal file) to help with forecasting or budgeting. - - Periodic transactions can be a little tricky, so before you use them, - read this whole section, or at least these tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast - tag:generated. - - 3. Forecasted transactions will begin only after the last non-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 im- - provement, 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 - 2023/01, which is equivalent to ~ every 10th day of month from - 2023/01/01, will be adjusted to start on 2019/12/10. - - Periodic rule syntax - A periodic transaction rule looks like a normal journal entry, with the - date replaced by a tilde (~) followed by a period expression (mnemonic: - ~ looks like a recurring sine wave.): - - # every first of month - ~ monthly - expenses:rent $2000 - assets:bank:checking - - # every 15th of month in 2023's first quarter: - ~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying multi-pe- - riod reports, just interpreted differently; there, it specifies report - periods; here it specifies recurrence dates (the periods' start dates). - - 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 re- - sults 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 2023" - ; || - ; vv - ~ every 2 months in 2023, 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 ex- - pression. - - Auto postings - The = directive declares a rule for generating temporary extra postings - on transactions. Wherever the rule matches an existing posting, it can - add one or more companion postings below that one, optionally influ- - enced by the matched posting's amount. This can be useful for generat- - ing tax postings with a standard percentage, for example. - - Note that depending on generated data is not ideal for financial - records (it's less portable, less future-proof, less auditable by oth- - ers, and less robust, since other features like balance assertions will - depend on using or not using --auto). - - 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". - - Auto postings on forecast transactions only - Tip: you can can make auto postings that will apply to forecast trans- - actions but not recorded transactions, by adding tag:_generated-trans- - action to their QUERY. This can be useful when generating new journal - entries to be saved in the journal. - - Other syntax - hledger journal format supports quite a few other features, mainly to - make interoperating with or converting from Ledger easier. Note some - of the features below are powerful and can be useful in special cases, - but in general, features in this section are considered less important - or even not recommended for most users. Downsides are mentioned to - help you decide if you want to use them. - - 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). - - Downsides: using balance assignments makes your journal less explicit; - to know the exact amount posted, you have to run hledger or do the cal- - culations yourself, instead of just reading it. Also balance assign- - ments' forcing of balances can hide errors. These things make your fi- - nancial data less portable, less future-proof, and less trustworthy in - an audit. - - Balance assignments and prices - A cost in a balance assignment will cause the calculated amount to have - that price attached: - - 2019/1/1 - (a) = $1 @ 2 - - $ hledger print --explicit - 2019-01-01 - (a) $1 @ 2 = $1 @ 2 - - Balance assignments and multiple files - Balance assignments handle multiple files like balance assertions. - They see balance from other files previously included from the current - file, but not from previous sibling or parent files. - - Bracketed posting dates - For setting posting dates and secondary posting dates, Ledger's brack- - eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in - posting comments. hledger will attempt to parse any square-bracketed - sequence of the 0123456789/-.= characters in this way. With this syn- - tax, DATE infers its year from the transaction and DATE2 infers its - year from DATE. - - Downsides: another syntax to learn, redundant with hledger's - date:/date2: tags, and confusingly similar to Ledger's lot date syntax. - - D directive - D AMOUNT - - This directive sets a default commodity, to be used for any subsequent - commodityless amounts (ie, plain numbers) seen while parsing the 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 di- - rective (setting the commodity's decimal mark for parsing and display - style for output). So its argument is not just a commodity symbol, but - a full amount demonstrating the style. The amount must include a deci- - mal mark (either period or comma). Eg: - - ; commodity-less amounts should be treated as dollars - ; (and displayed with the dollar sign on the left, thousands separators and two decimal places) - D $1,000.00 - - 1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity's display style, a commodity directive has - highest priority, then a D directive. - - For detecting a commodity's decimal mark during parsing, decimal-mark - has highest priority, then commodity, then D. - - For checking commodity symbols with the check command, a commodity di- - rective is required (hledger check commodities ignores D directives). - - Downsides: omitting commodity symbols makes your financial data less - explicit, less portable, and less trustworthy in an audit. It is usu- - ally an unsustainable shortcut; sooner or later you will want to track - multiple commodities. D is overloaded with functions redundant with - commodity and decimal-mark. And it works differently from Ledger's D. - - apply account directive - This directive sets a default parent account, which will be prepended - to all accounts in following entries, until an end apply account direc- - tive or end of current file. Eg: - - apply account home - - 2010/1/1 - food $10 - cash - - end apply account - - is equivalent to: - - 2010/01/01 - home:food $10 - home:cash $-10 - - account directives are also affected, and so is any included content. - - Account names entered via hledger add or hledger-web are not affected. - - Account aliases, if any, are applied after the parent account is - prepended. - - Downsides: this can make your financial data less explicit, less - portable, and less trustworthy in an audit. - - Y directive - Y YEAR - - or (deprecated backward-compatible forms): - - year YEAR apply year YEAR - - The space is optional. This sets a default year to be used for subse- - quent dates which don't specify a year. Eg: - - Y2009 ; set default year to 2009 - - 12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - - year 2010 ; change default year to 2010 - - 2009/1/30 ; specifies the year, not affected - expenses 1 - assets - - 1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at least) - makes your financial data less explicit, less portable, and less trust- - worthy in an audit. Such dates can get separated from their corre- - sponding Y directive, eg when evaluating a region of the journal in - your editor. A missing Y directive makes reports dependent on today's - date. - - Secondary dates - A secondary date is written after the primary date, following an equals - sign. If the year is omitted, the primary date's year is assumed. - When running reports, the primary (left) date is used by default, but - with the --date2 flag (or --aux-date or --effective), the secondary - (right) date will be used instead. - - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg "primary = the bank's clearing date, secondary = - date the transaction was initiated, if different". - - Downsides: makes your financial data more complicated, less portable, - and less trustworthy in an audit. Keeping the meaning of the two dates - consistent requires discipline, and you have to remember which report- - ing mode is appropriate for a given report. Posting dates are simpler - and better. - - Star comments - Lines beginning with * (star/asterisk) are also comment lines. This - feature allows Emacs users to insert org headings in their journal, al- - lowing them to fold/unfold/navigate it like an outline when viewed with - org mode. - - Downsides: another, unconventional comment syntax to learn. Decreases - your journal's portability. And switching to Emacs org mode just for - folding/unfolding meant losing the benefits of ledger mode; nowadays - you can add outshine mode to ledger mode to get folding without losing - ledger mode's features. - - Valuation expressions - Ledger allows a valuation function or value to be written in double - parentheses after an amount. hledger ignores these. - - Virtual postings - A posting with parentheses around the account name ((some:account)) is - called a unbalanced virtual posting. Such postings do not participate - in transaction balancing. (And if you write them without an amount, a - zero amount is always inferred.) These can occasionally be convenient - for special circumstances, but they violate double entry bookkeeping - and make your data less portable across applications, so many people - avoid using them at all. - - A posting with brackets around the account name ([some:account]) is - called a balanced virtual posting. The balanced virtual postings in a - transaction must add up to zero, just like ordinary postings, but sepa- - rately from them. These are not part of double entry bookkeeping ei- - ther, but they are at least balanced. An example: - - 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Ordinary postings, whose account names are neither parenthesised nor - bracketed, are called real postings. You can exclude virtual postings - from reports with the -R/--real flag or a real:1 query. - - Other Ledger directives - These other Ledger directives are currently accepted but ignored. This - allows hledger to read more Ledger files, but be aware that hledger's - reports may differ from Ledger's if you use these. - - apply fixed COMM AMT - apply tag TAG - assert EXPR - bucket / A ACCT - capture ACCT REGEX - check EXPR - define VAR=EXPR - end apply fixed - end apply tag - end apply year - end tag - eval / expr EXPR - python - PYTHONCODE - tag NAME - value EXPR - --command-line-flags - - See also https://hledger.org/ledger.html for a detailed hledger/Ledger - syntax comparison. - -CSV - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records, automatically converting - each record into a transaction. - - (To learn about writing CSV, see CSV output.) - - For best error messages when reading CSV/TSV/SSV files, make sure they - have a corresponding .csv, .tsv or .ssv file extension or use a hledger - file prefix (see File Extension below). - - Each CSV file must be described by a corresponding rules file. - This contains rules describing the CSV data (header line, fields lay- - out, date format etc.), how to construct hledger transactions from it, - and how to categorise transactions based on description or other at- - tributes. - - By default hledger looks for a rules file named like the CSV file with - an extra .rules extension, in the same directory. Eg when asked to - read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec- - ify a different rules file with the --rules-file option. If no rules - file is found, hledger will create a sample rules file, which you'll - need to adjust. - - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines - there are. Here's a simple CSV file and a rules file for it: - - Date, Description, Id, Amount - 12/11/2019, Foo, 123, 10.23 - - # basic.csv.rules - skip 1 - fields date, description, , amount - date-format %d/%m/%Y - - $ hledger print -f basic.csv - 2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There's an introductory Importing CSV data tutorial on hledger.org, and - more CSV rules examples below, and a larger collection at - https://github.com/simonmichael/hledger/tree/master/examples/csv. - - CSV rules cheatsheet - The following kinds of rule can appear in the rules file, in any order. - (Blank lines and lines beginning with # or ; or * are ignored.) - - source optionally declare which file to read data - from - separator declare the field separator, instead of rely- - ing on file extension - skip skip one or more header lines at start of file - date-format declare how to parse CSV dates/date-times - timezone declare the time zone of ambiguous CSV date- - times - newest-first improve txn order when: there are multiple - records, newest first, all with the same date - intra-day-reversed improve txn order when: same-day txns are in - opposite order to the overall file - decimal-mark declare the decimal mark used in CSV amounts, - when ambiguous - fields list name CSV fields for easy reference, and op- - tionally assign their values to hledger fields - Field assignment assign a CSV value or interpolated text value - to a hledger field - if block conditionally assign values to hledger fields, - or skip a record or end (skip rest of file) - if table conditionally assign values to hledger fields, - using compact syntax - balance-type select which type of balance assertions/as- - signments to generate - include inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are - evaluated. - - source - If you tell hledger to read a csv file with -f foo.csv, it will look - for rules in foo.csv.rules. Or, you can tell it to read the rules - file, with -f foo.csv.rules, and it will look for data in foo.csv - (since 1.30). - - These are mostly equivalent, but the second method provides some extra - features. For one, the data file can be missing, without causing an - error; it is just considered empty. And, you can specify a different - data file by adding a "source" rule: - - source ./Checking1.csv - - If you specify just a file name with no path, hledger will look for it - in your system's downloads directory (~/Downloads, currently): - - source Checking1.csv - - And if you specify a glob pattern, hledger will read the most recent of - the matched files (useful with repeated downloads): - - source Checking1*.csv - - See also "Working with CSV > Reading files specified by rule". - - 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. - - skip - skip N - - The word skip followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines at the start of the input - data. You'll need this whenever your CSV data contains header lines. - Note, empty and blank lines are skipped automatically, so you don't - need to count those. - - skip has a second meaning: it can be used inside if blocks (described - below), to skip one or more records whenever the condition is true. - Records skipped in this way are ignored, except they are still required - to be valid CSV. - - date-format - date-format DATEFMT - - This is a helper for the date (and date2) fields. If your CSV dates - are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll - need to add a date-format rule describing them with a strptime-style - date parsing pattern - see https://hackage.haskell.org/pack- - age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must - parse the CSV date value completely. Some examples: - - # MM/DD/YY - date-format %m/%d/%y - - # D/M/YYYY - # The - makes leading zeros optional. - date-format %-d/%-m/%Y - - # YYYY-Mmm-DD - date-format %Y-%h-%d - - # M/D/YYYY HH:MM AM some other junk - # Note the time and junk must be fully parsed, though only the date is used. - date-format %-m/%-d/%Y %l:%M %p some other junk - - timezone - timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone - other than yours, but containing no explicit time zone information, you - can use this rule to declare the CSV's native time zone, which helps - prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don't - need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see - the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware conversion, - localising the CSV date-times to your current system time zone. If you - prefer to localise to some other time zone, eg for reproducibility, you - can (on unix at least) set the output timezone with the TZ environment - variable, eg: - - $ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - timezone currently does not understand timezone names, except "UTC", - "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For - others, use numeric format: +HHMM or -HHMM. - - newest-first - hledger tries to ensure that the generated transactions will be ordered - chronologically, including same-day transactions. Usually it can auto- - detect how the CSV records are ordered. But if it encounters CSV where - all records are on the same date, it assumes that the records are old- - est first. If in fact the CSV's records are normally newest first, - like: - - 2022-10-01, txn 3... - 2022-10-01, txn 2... - 2022-10-01, txn 1... - - you can add the newest-first rule to help hledger generate the transac- - tions in correct order. - - # same-day CSV records are newest first - newest-first - - intra-day-reversed - If CSV records within a single day are ordered opposite to the overall - record order, you can add the intra-day-reversed rule to improve the - order of journal entries. Eg, here the overall record order is newest - first, but same-day records are oldest first: - - 2022-10-02, txn 3... - 2022-10-02, txn 4... - 2022-10-01, txn 1... - 2022-10-01, txn 2... - - # transactions within each day are reversed with respect to the overall date order - intra-day-reversed - - 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. - - fields list - fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word fields followed by comma-separated field names) - is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say %SomeField - instead of remembering %13. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and - build a transaction. - - Here's an example that says "use the 1st, 2nd and 4th fields as the - transaction's date, description and amount; name the last two fields - for later reference; and ignore the others": - - fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to the - CSV file's separator. Also: - - o 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 Fields you don't care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it's convenient to use these for - your field names, suitably modified (eg lower-cased with spaces re- - placed by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning to - a hledger field with the same name. Eg you could call the CSV's "bal- - ance" field balance_ to avoid directly setting hledger's balance field - (and generating a balance assertion). - - Field assignment - HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to - hledger fields. They can be used instead of or in addition to a fields - list (see above). - - To assign a value to a hledger field, write the field name (any of the - standard hledger field/pseudo-field names, defined below), a space, - followed by a text value on the same line. This text value may inter- - polate CSV fields, referenced either by their 1-based position in the - CSV record (%N) or by the name they were given in the fields list - (%CSVFIELD), and regular expression match groups (\N). - - 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 " be- - comes 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 - Note the two kinds of field names mentioned here, and used only in - hledger CSV rules files: - - 1. CSV field names (CSVFIELD in these docs): you can optionally name - the CSV columns for easy reference (since hledger doesn't yet auto- - matically recognise column headings in a CSV file), by writing arbi- - trary names in a fields list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special hledger field names (HLEDGERFIELD in these docs): you must - set at least some of these to generate the hledger transaction from - a CSV record, by writing them as the left hand side of a field as- - signment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a fields list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what hap- - pens when you assign values to them: - - 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. - - 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. - - account field - Assigning to accountN, where N is 1 to 99, sets the account name of the - Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you'll want to set account1 and - account2. Typically account1 is associated with the CSV file, and is - set once with a top-level assignment, while account2 is set based on - each transaction's description, in conditional rules. - - If a posting's account name is left unset but its amount is set (see - below), a default account name will be chosen (like "expenses:unknown" - or "income:unknown"). - - amount field - There are several ways to set posting amounts from CSV, useful in dif- - ferent situations. - - 1. amount is the oldest and simplest. Assigning to this sets the - amount of the first and second postings. In the second posting, the - amount will be negated; also, if it has a cost attached, it will be - converted to cost. - - 2. amount-in and amount-out work exactly like the above, but should be - used when the CSV has two amount fields (such as "Debit" and - "Credit", or "Inflow" and "Outflow"). Whichever field has a non- - zero value will be used as the amount of the first and second post- - ings. Here are some tips to avoid confusion: - - o It's not "amount-in for posting 1 and amount-out for posting 2", - it is "extract a single amount from the amount-in or amount-out - field, and use that for posting 1 and (negated) for posting 2". - - o Don't use both amount and amount-in/amount-out in the same rules - file; choose based on whether the amount is in a single CSV field - or spread across two fields. - - o In each record, at most one of the two CSV fields should contain - a non-zero amount; the other field must contain a zero or noth- - ing. - - o hledger assumes both CSV fields contain unsigned numbers, and it - automatically negates the amount-out values. - - o If the data doesn't fit these requirements, you'll probably need - an if rule (see below). - - 3. amountN (where N is a number from 1 to 99) sets the amount of only a - single posting: the Nth posting in the transaction. You'll usually - need at least two such assignments to make a balanced transaction. - You can also generate more than two postings, to represent more com- - plex transactions. The posting numbers don't have to be consecu- - tive; with if rules, higher posting numbers can be useful to ensure - a certain order of postings. - - 4. amountN-in and amountN-out work exactly like the above, but should - be used when the CSV has two amount fields. This is analogous to - amount-in and amount-out, and those tips also apply here. - - 5. Remember that a fields list can also do assignments. So in a fields - list if you name a CSV field "amount", that counts as assigning to - amount. (If you don't want that, call it something else in the - fields list, like "amount_".) - - 6. The above don't handle every situation; if you need more flexibil- - ity, use an if rule to set amounts conditionally. See "Working with - CSV > Setting amounts" below for more on this and on amount-setting - generally. - - 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. - - if block - Rules can be applied conditionally, depending on patterns in the CSV - data. This allows flexibility; in particular, it is how you can cate- - gorise transactions, selecting an appropriate account name based on - their description (for example). There are two ways to write condi- - tional rules: "if blocks", described here, and "if tables", described - below. - - An if block is the word if and one or more "matcher" expressions (can - be a word or phrase), one per line, starting either on the same or next - line; followed by one or more indented rules. Eg, - - if MATCHER - RULE - - or - - if - MATCHER - MATCHER - MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be ap- - plied. They are usually field assignments, but the following special - rules may also be used within an if block: - - o skip - skips the matched CSV record (generating no transaction from - it) - - o end - skips the rest of the current CSV file. - - Some examples: - - # if the record contains "groceries", set account2 to "expenses:groceries" - if groceries - account2 expenses:groceries - - # if the record contains any of these phrases, set account2 and a transaction comment as shown - if - monthly service fee - atm transaction fee - banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - # if an empty record is seen (assuming five fields), ignore the rest of the CSV file - if ,,,, - end - - Matchers - There are two kinds: - - 1. A record matcher is a word or single-line text fragment or regular - expression (REGEX), which hledger will try to match case-insensi- - tively anywhere within the CSV record. - Eg: whole foods - - 2. A field matcher is preceded with a percent sign and CSV field name - (%CSVFIELD REGEX). hledger will try to match these just within the - named CSV field. - Eg: %date 2023 - - The regular expression is (as usual in hledger) a POSIX extended regu- - lar expression, that also supports GNU word boundaries (\b, \B, \<, - \>), and nothing else. If you have trouble, see "Regular expressions" - in the hledger manual (https://hledger.org/hledger.html#regular-expres- - sions). - - With record matchers, it's important to know that the record matched is - not the original CSV record, but a modified one: separators will be - converted to commas, and enclosing double quotes (but not enclosing - whitespace) are removed. So for example, when reading an SSV file, if - the original record was: - - 2023-01-01; "Acme, Inc."; 1,000 - - the regex would see, and try to match, this modified record text: - - 2023-01-01,Acme, Inc., 1,000 - - When an if block has multiple matchers, they are combined as follows: - - o By default they are OR'd (any one of them can match) - - o When a matcher is preceded by ampersand (&) it will be AND'ed with - the previous matcher (both of them must match). - - When a matcher is preceded by an exclamation mark (!), the matcher will - be negated, ie it will exclude CSV records that match. - - Match groups - Matchers can define match groups: parenthesised portions of the regular - expression which are available for reference in field assignments. - Groups are enclosed in regular parentheses (( and )) and can be nested. - Each group is available in field assignments using the token \N, where - N is an index into the match groups for this conditional block (e.g. - \1, \2, etc.). - - Example: Warp credit card payment postings to the beginning of the - billing period (Month start), to match how they are presented in state- - ments, using posting dates: - - if %date (....-..)-.. - comment2 date:\1-01 - - Another example: Read the expense account from the CSV field, but throw - away a prefix: - - if %account1 liabilities:family:(expenses:.*) - account1 \1 - - if table - "if tables" are an alternative to if blocks; they can express many - matchers and field assignments in a more compact tabular format, like - this: - - if,HLEDGERFIELD1,HLEDGERFIELD2,... - MATCHERA,VALUE1,VALUE2,... - MATCHERB,VALUE1,VALUE2,... - MATCHERC,VALUE1,VALUE2,... - - - The first character after if is taken to be this if table's field sepa- - rator. It is unrelated to the separator used in the CSV file. It - should be a non-alphanumeric character like , or | that does not appear - anywhere else in the table (it should not be used in field names or - matchers or values, and it cannot be escaped with a backslash). - - Each line must contain the same number of separators; empty values are - allowed. Whitespace can be used in the matcher lines for readability - (but not in the if line, currently). The table must be terminated by - an empty line (or end of file). - - An if table like the above is interpreted as follows: try all of the - matchers; whenever a matcher succeeds, assign all of the values on that - line to the corresponding hledger fields; later lines can overrider - earlier ones. It is equivalent to this sequence of if blocks: - - if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - if MATCHERB - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - if MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - - if,account2,comment - atm transaction fee,expenses:business:banking,deductible? check it - %description groceries,expenses:groceries, - 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - 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 - - 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 - - Working with CSV - Some 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 - Note that hledger will only accept valid CSV conforming to RFC 4180, - and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or - tab as separators). This means, eg: - - o Values may be enclosed in double quotes, or not. Enclosing in single - quotes is not allowed. (Eg 'A','B' is rejected.) - - o When values are enclosed in double quotes, spaces outside the quotes - are not allowed. (Eg "A", "B" is rejected.) - - o When values are not enclosed in quotes, they may not contain double - quotes. (Eg A"A, B is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- - form it before reading with hledger. Try using sed, or a more permis- - sive CSV parser like python's csv lib. - - File Extension - To help hledger choose the CSV file reader and show the right error - messages (and choose the right field separator character by default), - it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv - filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV - reader (and the default field separator) by prefixing the file path - with csv:, ssv: or tsv:: Eg: - - $ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator rule - if needed. - - Reading CSV from standard input - You'll need the file format prefix when reading CSV from stdin also, - since hledger assumes journal format by default. Eg: - - $ cat foo.dat | hledger -f ssv:- print - - 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. - - Reading files specified by rule - Instead of specifying a CSV file in the command line, you can specify a - rules file, as in hledger -f foo.csv.rules CMD. By default this will - read data from foo.csv in the same directory, but you can add a source - rule to specify a different data file, perhaps located in your web - browser's download directory. - - This feature was added in hledger 1.30, so you won't see it in most CSV - rules examples. But it helps remove some of the busywork of managing - CSV downloads. Most of your financial institutions's default CSV file- - names are different and can be recognised by a glob pattern. So you - can put a rule like source Checking1*.csv in foo-checking.csv.rules, - and then periodically follow a workflow like: - - 1. Download CSV from Foo's website, using your browser's defaults - - 2. Run hledger import foo-checking.csv.rules to import any new transac- - tions - - After import, you can: discard the CSV, or leave it where it is for a - while, or move it into your archives, as you prefer. If you do noth- - ing, next time your browser will save something like Checking1-2.csv, - and hledger will use that because of the * wild card and because it is - the most recent. - - 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 as- - sertions 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 - Continuing from amount field above, here are more tips for amount-set- - ting: - - 1. If the amount is in a single CSV field: - a. If its sign indicates direction of flow: - Assign it to amountN, to set the Nth posting's amount. N is usu- - ally 1 or 2 but can go up to 99. - - b. If another field indicates direction of flow: - Use one or more conditional rules to set the appropriate amount - sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. If the amount is in two CSV fields (such as Debit and Credit, or In - and Out): - a. If both fields are unsigned: - Assign one field to amountN-in and the other to amountN-out. - hledger will automatically negate the "out" field, and will use - whichever field value is non-zero as posting N's amount. - - b. If either field is signed: - You will probably need to override hledger's sign for one or the - other field, as in the following example: - - # Negate the -out value, but only if it is not empty: - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. If both fields can contain a non-zero value (or both can be - empty): - The -in/-out rules normally choose the value which is non-zero/non- - empty. Some value pairs can be ambiguous, such as 1 and none. For - such cases, use conditional rules to help select the amount. Eg, - to handle the above you could select the value containing non-zero - digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. If you want posting 2's amount converted to cost: - Use the unnumbered amount (or amount-in and amount-out) syntax. - - 4. If the CSV has only balance amounts, not transaction amounts: - Assign to balanceN, to set a balance assignment on the Nth posting, - causing the posting's amount to be calculated automatically. balance - with no number is equivalent to balance1. In this situation hledger is - more likely to guess the wrong default account name, so you may need to - set that explicitly. - - Amount signs - There is some special handling making it easier to parse and to reverse - amount signs. (This only works for whole amounts, not for cost amounts - such as COST in amount1 AMT @ COST): - - 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 - "". - - It's not possible (without preprocessing the CSV) to set an amount to - its absolute value, ie discard its sign. - - Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount - field(s): - - 2023-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 - - 2023-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - - 2023-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 - - 2023-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 - - 2023-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 re- - peated, 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 re- - maining 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 as- - signed to it (and interpolate the %CSVFIELD references), or a default - - o generate a hledger transaction (journal entry) from these values. - - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the - user specified. - - Well factored rules - Some things than can help reduce duplication and complexity in rules - files: - - o Extracting common rules usable with multiple CSV files into a com- - mon.rules, and adding include common.rules to each CSV's rules file. - - o Splitting if blocks into smaller if blocks, extracting the frequently - used parts. - - CSV rules examples - 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. - - Coinbase - A simple example with some CSV from Coinbase. The spot price is - recorded using cost notation. The legacy amount field name conve- - niently sets amount 2 (posting 2's amount) to the total cost. - - # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes - # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - - # coinbase.csv.rules - skip 1 - fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes - date %Timestamp - date-format %Y-%m-%dT%T%Z - description %Notes - account1 assets:coinbase:cc - amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - - $ hledger print -f coinbase.csv - 2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - 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: - -Timeclock - The time logging format of timeclock.el, as read by hledger. - - hledger can read time logs in timeclock format. As with Ledger, these - are (a subset of) timeclock.el's format, containing clock-in and clock- - out entries as in the example below. The date is a simple date. The - time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. - The timezone, if present, must be four digits and is ignored (currently - the time is always interpreted as a local time). Lines beginning with - # or ; or *, and blank lines, are ignored. - - i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: - 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 2 spaces ; optional comment, tags: - (some account) 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 - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is more convenient for quick, approxi- - mate, and retroactive time logging, and more human-readable (you can - see at a glance where time was spent). A quick example: - - 2023-05-01 - hom:errands .... .... ; two hours; the space is ignored - fos:hledger:timedot .. ; half an hour - per:admin:finance ; no time spent yet - - hledger reads this as a transaction on this day with three (unbalanced) - postings, where each dot represents "0.25". No commodity symbol is as- - sumed, but we typically interpret it as hours. - - $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required - 2023-05-01 * - (hom:errands) 2.00 ; two hours - (fos:hledger:timedot) 0.50 ; half an hour - (per:admin:finance) 0 - - A timedot file contains a series of transactions (usually one per day). - Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be - followed on the same line by a transaction description, and/or a trans- - action comment following a semicolon. - - After the date line are zero or more time postings, consisting of: - - o An account name - any hledger-style account name, optionally in- - dented. - - o Two or more spaces - required if there is an amount (as in journal - format). - - o A timedot amount, which can be - - o empty (representing zero) - - o a number, optionally followed by a unit s, m, h, d, w, mo, or y, - representing a precise number of seconds, minutes, hours, days - weeks, months or years (hours is assumed by default), which will be - converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = - 1w, 30d = 1mo, 365d = 1y. - - o one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can be - used for grouping/alignment. - - o one or more letters. These are like dots but they also generate a - tag t: (short for "type") with the letter as its value, and a sepa- - rate posting for each of the values. This provides a second dimen- - sion of categorisation, viewable in reports with --pivot t. - - o An optional comment following a semicolon (a hledger-style posting - comment). - - There is some flexibility to help with keeping time log data and notes - in the same file: - - o Blank lines and lines beginning with # or ; are ignored. - - o After the first date line, lines which do not contain a double space - are parsed as postings with zero amount. (hledger's register reports - will show these if you add -E). - - o Before the first date line, lines beginning with * (eg org headings) - are ignored. And from the first date line onward, Emacs org mode - heading prefixes at the start of lines (one or more *'s followed by a - space) will be ignored. This means the time log can also be a org - outline. - - Timedot examples - Numbers: - - 2016/2/3 - inc:client1 4 - fos:hledger 3h - biz:research 60m - - Dots: - - # 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 . - - $ 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 - - Letters: - - # Activity types: - # c cleanup/catchup/repair - # e enhancement - # s support - # l learning/research - - 2023-11-01 - work:adm ccecces - - $ hledger -f a.timedot print - 2023-11-01 - (work:adm) 1 ; t:c - (work:adm) 0.5 ; t:e - (work:adm) 0.25 ; t:s - - $ hledger -f a.timedot bal - 1.75 work:adm - -------------------- - 1.75 - - $ hledger -f a.timedot bal --pivot t - 1.00 c - 0.50 e - 0.25 s - -------------------- - 1.75 - - Org: - - * 2023 Work Diary - ** Q1 - *** 2023-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 - - Using . as account name separator: - - 2016/2/4 - fos.hledger.timedot 4h - fos.ledger .. - - $ hledger -f a.timedot --alias '/\./=:' bal -t - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger - -------------------- - 4.50 - -PART 3: REPORTING CONCEPTS -Amount formatting, parseability - If you're wondering why your print report sometimes shows trailing dec- - imal marks, with no decimal digits; it does this when showing amounts - that have digit group marks but no decimal digits, to disambiguate them - and allow them to be re-parsed reliably (see also Decimal marks, digit - group marks. Eg: - - commodity $1,000.00 - - 2023-01-02 - (a) $1000 - - $ hledger print - 2023-01-02 - (a) $1,000. - - If this is a problem (eg when exporting to Ledger), you can avoid it by - disabling digit group marks, eg with -c/--commodity (for each affected - commodity): - - $ hledger print -c '$1000.00' - 2023-01-02 - (a) $1000 - - or by forcing print to always show decimal digits, with --round: - - $ hledger print -c '$1,000.00' --round=soft - 2023-01-02 - (a) $1,000.00 - - More generally: hledger output falls into three rough categories, which - format amounts a little bit differently to suit different consumers: - - 1. "hledger-readable output" - should be readable by hledger (and by - humans) - - o This is produced by reports that show full journal entries: print, - import, close, rewrite etc. - - o It shows amounts with their original journal precisions, which may - not be consistent. - - o It adds a trailing decimal mark when needed to avoid showing ambigu- - ous amounts. - - o It can be parsed reliably (by hledger and ledger2beancount at least, - but perhaps not by Ledger..) - - 2. "human-readable output" - usually for humans - - o This is produced by all other reports. - - o It shows amounts with standard display precisions, which will be con- - sistent within each commodity. - - o It shows ambiguous amounts unmodified. - - o It can be parsed reliably in the context of a known report (when you - know decimals are consistently not being shown, you can assume a sin- - gle mark is a digit group mark). - - 3. "machine-readable output" - usually for other software - - o This is produced by all reports when an output format like csv, tsv, - json, or sql is selected. - - o It shows amounts as 1 or 2 do, but without digit group marks. - - o It can be parsed reliably (if needed, the decimal mark can be changed - with -c/--commodity-style). - -Time periods - Report start & end date - By default, most hledger reports will show the full span of time repre- - sented by the journal. The report start date will be the earliest - transaction or posting date, and the report end date will be the latest - transaction, posting, or market price date. - - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, - -e/--end, -p/--period or a date: query (described below). All of these - accept the smart date syntax (below). - - Some notes: - - 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 In some cases a report interval will adjust start/end dates to fall - on interval boundaries (see below). - - 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 re- - placed with -) - date:..12/1 - date:thismonth.. - date:thismonth - - Smart dates - hledger's user interfaces accept a "smart date" syntax for added conve- - nience. Smart dates optionally can be relative to today's date, be - written with english words, and have less-significant parts omitted - (missing parts are inferred as 1). Some examples: - - 2004/10/1, 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 - - Some counterexamples - malformed digit sequences might give surprising - results: - - 201813 6 digits with an invalid month is parsed as start of - 6-digit year - 20181301 8 digits with an invalid month is parsed as start of - 8-digit year - 20181232 8 digits with an invalid day gives an error - 201801012 9+ digits beginning with a valid YYYYMMDD gives an error - - "Today's date" can be overridden with the --today option, in case it's - needed for testing or for recreating old reports. (Except for periodic - transaction rules, which are not affected by --today.) - - Report intervals - A report interval can be specified so that reports like register, bal- - ance or activity become multi-period, showing each subperiod as a sepa- - rate row or column. - - The following standard intervals can be enabled with command-line - flags: - - o -D/--daily - - o -W/--weekly - - o -M/--monthly - - o -Q/--quarterly - - o -Y/--yearly - - More complex intervals can be specified using -p/--period, described - below. - - Date adjustment - When there is a report interval (other than daily), report start/end - dates which have been inferred, eg from the journal, are automatically - adjusted to natural period boundaries. This is convenient for produc- - ing simple periodic reports. More precisely: - - o an inferred start date will be adjusted earlier if needed to fall on - a natural period boundary - - o an inferred end date will be adjusted later if needed to make the - last period the same length as the others. - - By contrast, start/end dates which have been specified explicitly, with - -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This - makes it possible to specify non-standard report periods, but it also - means that if you are specifying a start date, you should pick one - that's on a period boundary if you want to see simple report period - headings. - - Period expressions - The -p/--period option specifies a period expression, which is a com- - pact way of expressing a start date, end date, and/or report interval. - - Here's a period expression with a start and end date (specifying the - first quarter of 2009): - - -p "from 2009/1/1 to 2009/4/1" - - Several keywords like "from" and "to" are supported for readability; - these are optional. "to" can also be written as ".." or "-". The - spaces are also optional, as long as you don't run two dates together. - So the following are equivalent to the above: - - -p "2009/1/1 2009/4/1" - -p2009/1/1to2009/4/1 - -p2009/1/1..2009/4/1 - - Dates are smart dates, so if the current year is 2009, these are also - equivalent to the above: - - -p "1/1 4/1" - -p "jan-apr" - -p "this year to 4/1" - - If you specify only one date, the missing start or end date will be the - earliest or latest transaction date in the journal: - - -p "from 2009/1/1" everything after january - 1, 2009 - -p "since 2009/1" the same, since is a syn- - onym - -p "from 2009" the same - -p "to 2009" everything before january - 1, 2009 - - You can also specify a period by writing a single partial or full date: - - -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to - 2009/2/1" - -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to - 2009/1/2" - - or by using the "Q" quarter-year syntax (case insensitive): - - -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to - 2009/4/1" - -p "q4" fourth quarter of the current year - - Period expressions with a report interval - A period expression can also begin with a report interval, separated - from the start/end dates (if any) by a space or the word in: - - -p "weekly from 2009/1/1 to 2009/4/1" - -p "monthly in 2008" - -p "quarterly" - - More complex report intervals - Some more complex intervals can be specified within period expressions, - such as: - - o biweekly (every two weeks) - - o fortnightly - - o bimonthly (every two months) - - o every day|week|month|quarter|year - - o every N days|weeks|months|quarters|years - - Weekly on a 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 a custom day: - - o every Nth day [of month] - - o every Nth WEEKDAYNAME [of month] - - Yearly on a 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 "bimonthly from 2008" - -p "every 2 weeks" - -p "every 5 months from - 2009/03" - -p "every 2nd day of week" periods will go from Tue to Tue - -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each - month - -p "every 2nd Monday" period boundaries will be on second Monday - of each month - -p "every 11/05" yearly periods with boundaries on 5th of - 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" - - Multiple weekday intervals - This special form is also supported: - - o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- - day names, case insensitive) - - Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and - sat,sun. - - This is mainly intended for use with --forecast, to generate periodic - transactions on arbitrary days of the week. It may be less useful with - -p, since it divides each week into subperiods of unequal length, which - is unusual. (Related: #1632) - - Examples: - - -p "every dates will be Mon, Wed, Fri; periods will be Mon- - 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), reports will show ac- - counts only to the specified depth, hiding deeper subaccounts. Use - this when you want a summary with less detail. This flag has the same - effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- - lent. - -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 ac- - count 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:202312- - status: - desc:amazon - cur:USD - "amt:>0" - - o Add a not: prefix to negate: - - not:cur:USD - - o Multiple unlike terms are AND-ed, multiple like terms are OR-ed - - date:2022 desc:amazon desc:amzn - (all transactions with "amazon" or "amzn" in description during 2022) - - 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 es- - caping. 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 in- - terval. 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. - - expr:"TERM AND NOT (TERM OR TERM)" (eg) - Match with a boolean combination of queries (which must be enclosed in - quotes). See Combining query terms below. - - 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 - When given multiple space-separated 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. - - The print command is a little different, showing 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. - - We also support more complex boolean queries with the 'expr:' prefix. - This allows one to combine queries using one of three operators: AND, - OR, and NOT, where NOT is different syntax for 'not:'. - - Examples of such queries are: - - o Match transactions with 'cool' in the description AND with the 'A' - tag - - expr:"desc:cool AND tag:A" - - o Match transactions NOT to the 'expenses:food' account OR with the 'A' - tag - - expr:"NOT expenses:food OR tag:A" - - o Match transactions NOT involving the 'expenses:food' account OR with - the 'A' tag AND involving the 'expenses:drink' account. (the AND is - implicitly added by space-separation, following the rules above) - - expr:"expenses:food OR (tag:A expenses:drink)" - - Queries and command options - Some queries can also be expressed as command-line options: depth:2 is - equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When - you mix command options and query arguments, generally the resulting - query is their intersection. - - Queries and valuation - When amounts are converted to other commodities in cost or value re- - ports, 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 re- - versed, 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 re- - ports, 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. - -Pivoting - Normally, hledger groups and sums amounts within each account. The - --pivot FIELD option substitutes some other transaction field for ac- - count names, causing amounts to be grouped and summed by that field's - value instead. FIELD can be any of the transaction fields acct, sta- - tus, code, desc, payee, note, or a tag name. When pivoting on a tag - and a posting has multiple values of that tag, only the first value is - displayed. Values containing colon:separated:parts will be displayed - hierarchically, like account names. Multiple, colon-delimited fields - can be pivoted simultaneously, generating a hierarchical account name. - - Some examples: - - 2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe, kind: Lifetime - - Normal balance report showing account names: - - $ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues - -------------------- - 0 - - Pivoted balance report, using member: tag values instead: - - $ hledger balance --pivot member - 2 EUR - -2 EUR John Doe - -------------------- - 0 - - One way to show only amounts with a member: value (using a query): - - $ hledger balance --pivot member tag:member=. - -2 EUR John Doe - -------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account - name"): - - $ hledger balance --pivot member acct:. - -2 EUR John Doe - -------------------- - -2 EUR - - Hierarchical reports can be generated with multiple pivots: - - $ hledger balance Income:Dues --pivot kind:member - -2 EUR Lifetime:John Doe - -------------------- - -2 EUR - -Generating data - hledger has several features for generating data, such as: - - o Periodic transaction rules can generate single or repeating transac- - tions following a template. These are usually dated in the future, - eg to help with forecasting. They are activated by the --forecast - option. - - o The balance command's --budget option uses these same periodic rules - to generate goals for the budget report. - - o Auto posting rules can generate extra postings on certain matched - transactions. They are always applied to forecast transactions; with - the --auto flag they are applied to transactions recorded in the - journal as well. - - o The --infer-equity flag infers missing conversion equity postings - from @/@@ costs. And the inverse --infer-costs flag infers missing - @/@@ costs from conversion equity postings. - - Generated data of this kind is temporary, existing only at report time. - But you can see it in the output of hledger print, and you can save - that to your journal, in effect converting it from temporary generated - data to permanent recorded data. This could be useful as a data entry - aid. - - If you are wondering what data is being generated and why, add the - --verbose-tags flag. In hledger print output you will see extra tags - like generated-transaction, generated-posting, and modified on gener- - ated/modified data. Also, even without --verbose-tags, generated data - always has equivalen hidden tags (with an underscore prefix), so eg you - could match generated transactions with tag:_generated-transaction. - -Forecasting - Forecasting, or speculative future reporting, can be useful for esti- - mating future balances, or for exploring different future scenarios. - - The simplest and most flexible way to do it with hledger is to manually - record a bunch of future-dated transactions. You could keep these in a - separate future.journal and include that with -f only when you want to - see them. - - --forecast - There is another way: with the --forecast option, hledger can generate - temporary "forecast transactions" for reporting purposes, according to - periodic transaction rules defined in the journal. Each rule can gen- - erate multiple recurring transactions, so by changing one rule you can - change many forecasted transactions. (These same rules can also gener- - ate budget goals, described in Budgeting.) - - Forecast transactions usually start after ordinary transactions end. - By default, they begin after your latest-dated ordinary transaction, or - today, whichever is later, and they end six months from today. (The - exact rules are a little more complicated, and are given below.) - - This is the "forecast period", which need not be the same as the report - period. You can override it - eg to forecast farther into the future, - or to force forecast transactions to overlap your ordinary transactions - - by giving the --forecast option a period expression argument, like - --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- - quired. - - Inspecting forecast transactions - print is the best command for inspecting and troubleshooting forecast - transactions. Eg: - - ~ monthly from 2022-12-20 rent - assets:bank:checking - expenses:rent $1000 - - $ hledger print --forecast --today=2023/4/21 - 2023-05-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-06-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-07-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-08-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-09-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - Here there are no ordinary transactions, so the forecasted transactions - begin on the first occurence after today's date. (You won't normally - use --today; it's just to make these examples reproducible.) - - Forecast reports - Forecast transactions affect all reports, as you would expect. Eg: - - $ hledger areg rent --forecast --today=2023/4/21 - Transactions in expenses:rent and subaccounts: - 2023-05-20 rent as:ba:checking $1000 $1000 - 2023-06-20 rent as:ba:checking $1000 $2000 - 2023-07-20 rent as:ba:checking $1000 $3000 - 2023-08-20 rent as:ba:checking $1000 $4000 - 2023-09-20 rent as:ba:checking $1000 $5000 - - $ hledger bal -M expenses --forecast --today=2023/4/21 - Balance changes in 2023-05-01..2023-09-30: - - || May Jun Jul Aug Sep - ===============++=================================== - expenses:rent || $1000 $1000 $1000 $1000 $1000 - ---------------++----------------------------------- - || $1000 $1000 $1000 $1000 $1000 - - Forecast tags - Forecast transactions generated by --forecast have a hidden tag, _gen- - erated-transaction. So if you ever need to match forecast transac- - tions, you could use tag:_generated-transaction (or just tag:generated) - in a query. - - For troubleshooting, you can add the --verbose-tags flag. Then, visi- - ble generated-transaction tags will be added also, so you can view them - with the print command. Their value indicates which periodic rule was - responsible. - - Forecast period, in detail - Forecast start/end dates are chosen so as to do something useful by de- - fault in almost all situations, while also being flexible. Here are - (with luck) the exact rules, to help with troubleshooting: - - The forecast period starts on: - - o the later of - - o the start date in the periodic transaction rule - - o the start date in --forecast's argument - - o otherwise (if those are not available): the later of - - o the report start date specified with -b/-p/date: - - o the day after the latest ordinary transaction in the journal - - o otherwise (if none of these are available): today. - - The forecast period ends on: - - o the earlier of - - o the end date in the periodic transaction rule - - o the end date in --forecast's argument - - o otherwise: the report end date specified with -e/-p/date: - - o otherwise: 180 days (~6 months) from today. - - Forecast troubleshooting - When --forecast is not doing what you expect, one of these tips should - help: - - o Remember to use the --forecast option. - - o Remember to have at least one periodic transaction rule in your jour- - nal. - - o Test with print --forecast. - - o Check for typos or too-restrictive start/end dates in your periodic - transaction rule. - - o Leave at least 2 spaces between the rule's period expression and de- - scription fields. - - o Check for future-dated ordinary transactions suppressing forecasted - transactions. - - o Try setting explicit report start and/or end dates with -b, -e, -p or - date: - - o Try adding the -E flag to encourage display of empty periods/zero - transactions. - - o Try setting explicit forecast start and/or end dates with --fore- - cast=START..END - - o Consult Forecast period, in detail, above. - - o Check inside the engine: add --debug=2 (eg). - -Budgeting - With the balance command's --budget report, each periodic transaction - rule generates recurring budget goals in specified accounts, and goals - and actual performance can be compared. See the balance command's doc - below. - - You can generate budget goals and forecast transactions at the same - time, from the same or different periodic transaction rules: hledger - bal -M --budget --forecast ... - - See also: Budgeting and Forecasting. - -Cost reporting - In some transactions - for example a currency conversion, or a purchase - or sale of stock - one commodity is exchanged for another. In these - transactions there is a conversion rate, also called the cost (when - buying) or selling price (when selling). In hledger docs we just say - "cost", for convenience; feel free to mentally translate to "conversion - rate" or "selling price" if helpful. - - Recording costs - We'll explore several ways of recording transactions involving costs. - These are also summarised at hledger Cookbook > Cost notation. - - Costs can be recorded explicitly in the journal, using the @ UNITCOST - or @@ TOTALCOST notation described in Journal > Costs: - - Variant 1 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 @ $1.35 ; $1.35 per euro (unit cost) - - Variant 2 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 @@ $135 ; $135 total cost - - Typically, writing the unit cost (variant 1) is preferable; it can be - more effort, requiring more attention to decimal digits; but it reveals - the per-unit cost basis, and makes stock sales easier. - - Costs can also be left implicit, and hledger will infer the cost that - is consistent with a balanced transaction: - - Variant 3 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 - - Here, hledger will attach a @@ 100 cost to the first amount (you can - see it with hledger print -x). This form looks convenient, but there - are downsides: - - o It sacrifices some error checking. For example, if you accidentally - wrote 10 instead of 100, hledger would not be able to detect the mis- - take. - - o It is sensitive to the order of postings - if they were reversed, a - different entry would be inferred and reports would be different. - - o The per-unit cost basis is not easy to read. - - So generally this kind of entry is not recommended. You can make sure - you have none of these by using -s (strict mode), or by running hledger - check balanced. - - Reporting at cost - Now when you add the -B/--cost flag to reports ("B" is from Ledger's - -B/--basis/--cost flag), any amounts which have been annotated with - costs will be converted to their cost's commodity (in the report out- - put). Ie they will be displayed "at cost" or "at sale price". - - Some things to note: - - o Costs are attached to specific posting amounts in specific transac- - tions, and once recorded they do not change. This contrasts with - market prices, which are ambient and fluctuating. - - o Conversion to cost is performed before conversion to market value - (described below). - - Equity conversion postings - There is a problem with the entries above - they are not conventional - Double Entry Bookkeeping (DEB) notation, and because of the "magical" - transformation of one commodity into another, they cause an imbalance - in the Accounting Equation. This shows up as a non-zero grand total in - balance reports like hledger bse. - - For most hledger users, this doesn't matter in practice and can safely - be ignored ! But if you'd like to learn more, keep reading. - - Conventional DEB uses an extra pair of equity postings to balance the - transaction. Of course you can do this in hledger as well: - - Variant 4 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 - equity:conversion $135 - equity:conversion -100 - - Now the transaction is perfectly balanced according to standard DEB, - and hledger bse's total will not be disrupted. - - And, hledger can still infer the cost for cost reporting, but it's not - done by default - you must add the --infer-costs flag like so: - - $ hledger print --infer-costs - 2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 @@ 100 - assets:euros 100 - equity:conversion $135 - equity:conversion -100 - - $ hledger bal --infer-costs -B - -100 assets:dollars - 100 assets:euros - -------------------- - 0 - - Here are some downsides of this kind of entry: - - o The per-unit cost basis is not easy to read. - - o Instead of -B you must remember to type -B --infer-costs. - - o --infer-costs works only where hledger can identify the two eq- - uity:conversion postings and match them up with the two non-equity - postings. So writing the journal entry in a particular format be- - comes more important. More on this below. - - Inferring equity conversion postings - Can we go in the other direction ? Yes, if you have transactions writ- - ten with the @/@@ cost notation, hledger can infer the missing equity - postings, if you add the --infer-equity flag. Eg: - - 2022-01-01 - assets:dollars -$135 - assets:euros 100 @ $1.35 - - $ hledger print --infer-equity - 2022-01-01 - assets:dollars $-135 - assets:euros 100 @ $1.35 - equity:conversion:$-: -100 - equity:conversion:$-:$ $135.00 - - The equity account names will be "equity:conversion:A-B:A" and "eq- - uity:conversion:A-B:B" where A is the alphabetically first commodity - symbol. You can customise the "equity:conversion" part by declaring an - account with the V/Conversion account type. - - Combining costs and equity conversion postings - Finally, you can use both the @/@@ cost notation and equity postings at - the same time. This in theory gives the best of all worlds - preserv- - ing the accounting equation, revealing the per-unit cost basis, and - providing more flexibility in how you write the entry: - - Variant 5 - - 2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion -100 - assets:euros 100 @ $1.35 - - All the other variants above can (usually) be rewritten to this final - form with: - - $ hledger print -x --infer-costs --infer-equity - - Downsides: - - o This was added in hledger-1.29 and is still somewhat experimental. - - o The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it - will give a transaction balancing error. - - o The add command does not yet accept this kind of entry (#2056). - - o This is the most verbose form. - - Requirements for detecting equity conversion postings - --infer-costs has certain requirements (unlike --infer-equity, which - always works). It will infer costs only in transactions with: - - o Two non-equity postings, in different commodities. Their order is - significant: the cost will be added to the first of them. - - o Two postings to equity conversion accounts, next to one another, - which balance the two non-equity postings. This balancing is checked - to the same precision (number of decimal places) used in the conver- - sion posting's amount. Equity conversion accounts are: - - o any accounts declared with account type V/Conversion, or their sub- - accounts - - o otherwise, accounts named equity:conversion, equity:trade, or eq- - uity:trading, or their subaccounts. - - And multiple such four-posting groups can coexist within a single - transaction. When --infer-costs fails, it does not infer a cost in - that transaction, and does not raise an error (ie, it infers costs - where it can). - - Reading variant 5 journal entries, combining cost notation and equity - postings, has all the same requirements. When reading such an entry - fails, hledger raises an "unbalanced transaction" error. - - Infer cost and equity by default ? - Should --infer-costs and --infer-equity be enabled by default ? Try - using them always, eg with a shell alias: - - alias h="hledger --infer-equity --infer-costs" - - and let us know what problems you find. - -Value reporting - 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] op- - tion, 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 - Market prices can change from day to day. hledger will use the prices - on a particular valuation date (or on more than one date). By default - hledger uses "end" dates for valuation. More specifically: - - o For single period reports (including normal print and register re- - ports): - - o If an explicit report end date is specified, that is used - - o Otherwise the latest transaction date or P directive date is used - (even if it's in the future) - - o For multiperiod reports, each period is valued on its last day. - - This can be customised with the --value option described below, which - can select either "then", "end", "now", or "custom" dates. (Note, this - has a bug in hledger-ui <=1.31: turning on valuation with the V key al- - ways resets it to "end".) - - Finding market price - To convert a commodity A to its market value in another commodity B, - hledger looks for a suitable market price (exchange rate) as follows, - in this order of preference: - - 1. A declared market price or inferred market price: A's latest market - price in B on or before the valuation date as declared by a P direc- - tive, or (with the --infer-market-prices flag) inferred from costs. - - 2. A reverse market price: the inverse of a declared or inferred market - price from B to A. - - 3. A forward chain of market prices: a synthetic price formed by 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 costs as additional market prices (as - Ledger does) ? Adding the --infer-market-prices flag to -V, -X or - --value enables this. - - So for example, hledger bs -V --infer-market-prices will get market - prices both from P directives and from transactions. If both occur on - the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, - read all of this Value reporting 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 multicommodity transactions with equity postings, if cost is inferred - with --infer-costs. - - There is a limitation (bug) currently: when a valuation commodity is - not specified, prices inferred with --infer-market-prices do not help - select a default valuation commodity, as P prices would. So conversion - might not happen because no valuation commodity was detected (--debug=2 - will show this). To be safe, specify the valuation commmodity, eg: - - 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 - - Signed costs and market prices can be confusing. For reference, here - is the current behaviour, since hledger 1.25. (If you think it should - work differently, see #1870.) - - 2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - - 2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - - 2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - - 2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - - 2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - - 2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each day, - the two transactions are considered equivalent). Here are the market - prices inferred for B: - - $ hledger -f- --infer-market-prices prices - P 2022-01-01 B A 1 - P 2022-01-01 B A 1.0 - P 2022-01-02 B A -1 - P 2022-01-02 B A -1.0 - P 2022-01-03 B A -1 - P 2022-01-03 B A -1.0 - - 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, - costs 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 $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 - - --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 - - 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. Re- - lated: #329, #1083. - - Report -B, --cost -V, -X --value=then --value=end --value=DATE, - type --value=now - -------------------------------------------------------------------------------------------- - print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today - today journal end - balance unchanged unchanged unchanged unchanged unchanged - asser- - tions/as- - signments - - register - starting cost value at re- valued at day value at re- value at - balance port or each historical port or DATE/today - (-H) journal end posting was made journal end - starting cost value at day valued at day value at day value at - balance before re- each historical before re- DATE/today - (-H) with port or posting was made port or - report journal journal - interval start start - posting cost value at re- value at posting value at re- value at - amounts port or date port or DATE/today - journal end journal end - summary summarised value at pe- sum of postings value at pe- value at - posting cost riod ends in interval, val- riod ends DATE/today - amounts ued at interval - with re- start - port in- - terval - running sum/average sum/average sum/average of sum/average sum/average - total/av- of displayed of displayed displayed values of displayed of displayed - erage values values values values - - balance - (bs, bse, - cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of - 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 - (--bud- - get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- - tal played val- played val- valued played val- played values - ues ues ues - - balance - (bs, bse, - cf, is) - with re- - port in- - terval - starting sums of value at re- sums of values of value at re- sums of post- - balances costs of port start postings before port start ings before - (-H) postings be- of sums of report start at of sums of report start - fore report all postings respective post- all postings - start before re- ing dates before re- - port start port start - balance sums of same as sums of values of balance value at - changes costs of --value=end postings in pe- change in DATE/today of - (bal, is, postings in riod at respec- each period, sums of post- - bs period tive posting valued at ings - --change, dates period ends - cf - --change) - end bal- sums of same as sums of values of period end value at - ances costs of --value=end postings from be- balances, DATE/today of - (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings - bs, cf) report start respective post- - to period ing dates - end - budget like balance like balance like balance like bal- like balance - amounts changes/end changes/end changes/end bal- ances changes/end - (--bud- balances balances ances balances - get) - row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- - averages played val- played val- played val- played values - (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- - totals played val- played val- values played val- played values - ues ues ues - grand to- sum, average sum, average sum, average of sum, average sum, average - tal, of column of column column totals of column of column to- - grand av- totals totals totals tals - erage - - - --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). - -PART 4: COMMANDS - Commands overview - Here are the built-in commands: - - DATA ENTRY - These data entry commands are the only ones which can modify your jour- - nal file. - - o add - add transactions using terminal prompts - - o import - add new transactions from other files, eg CSV files - - DATA CREATION - o close - generate balance-zeroing/restoring transactions - - o rewrite - generate auto postings, like print --auto - - DATA MANAGEMENT - o check - check for various kinds of error in the data - - o diff - compare account transactions in two journal files - - REPORTS, FINANCIAL - 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 - - REPORTS, VERSATILE - o balance (bal) - show balance changes, end balances, budgets, gains.. - - o print - show transactions or export journal data - - o register (reg) - show postings in one or more accounts & running to- - tal - - o roi - show return on investments - - REPORTS, BASIC - o accounts - show account names - - o activity - show bar charts of posting counts per period - - o codes - show transaction codes - - o commodities - show commodity/currency symbols - - o descriptions - show transaction descriptions - - o files - show input file paths - - o notes - show note parts of transaction descriptions - - o payees - show payee parts of transaction descriptions - - o prices - show market prices - - o stats - show journal statistics - - o tags - show tag names - - o test - run self tests - - HELP - o help - show the hledger manual with info/man/pager - - o demo - show small hledger demos in the terminal - - ADD-ONS - And here are some typical add-on commands. Some of these are installed - by the hledger-install script. If installed, they will appear in - hledger's commands list: - - o ui - run hledger's terminal UI - - o web - run hledger's web UI - - o iadd - add transactions using a TUI (currently hard to build) - - o interest - generate interest transactions - - o stockquotes - download market prices from AlphaVantage - - o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, - pijul, plot, and more.. - - Next, each command is described in detail, in alphabetical order. - - accounts - Show account names. - - This command lists account names. By default it shows all known ac- - counts, either used in transactions or declared with account direc- - tives. - - With query arguments, only matched account names and account names ref- - erenced by matched postings are shown. - - Or it can show just the used accounts (--used/-u), the declared ac- - counts (--declared/-d), the accounts declared but not used (--unused), - the accounts used but not declared (--undeclared), or the first account - matched by an account name pattern, if any (--find). - - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. In flat mode you can add --drop N to omit - the first few account name components. Account names can be depth- - clipped with depth:N or --depth N or -N. - - With --types, it also shows each account's type, if it's known. (See - Declaring accounts > Account types.) - - With --positions, it also shows the file and line number of each ac- - count's declaration, if any, and the account's overall declaration or- - der; these may be useful when troubleshooting account display order. - - With --directives, it adds the account keyword, showing valid account - directives which can be pasted into a journal file. This is useful to- - gether with --undeclared when updating your account declarations to - satisfy hledger check accounts. - - The --find flag can be used to look up a single account name, in the - same way that the aregister command does. It returns the alphanumeri- - cally-first matched account name, or if none can be found, it fails - with a non-zero exit code. - - Examples: - - $ hledger accounts - assets:bank:checking - assets:bank:saving - assets:cash - expenses:food - expenses:supplies - income:gifts - income:salary - liabilities:debts - - $ hledger accounts --undeclared --directives >> $LEDGER_FILE - $ hledger check accounts - - 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 - 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 de- - scription) 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, pay- - ees/descriptions, 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 https://hledger.org/add.html for a detailed tutorial): - - $ hledger add - Adding transactions to journal file /src/hledger/examples/sample.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to go one step backward. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2015/05/22]: - Description: supermarket - Account 1: expenses:food - Amount 1: $10 - Account 2: assets:checking - Amount 2 [$-10.0]: - Account 3 (or . or enter to finish this transaction): . - 2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2015/05/22]: $ - - On Microsoft Windows, the add command makes sure that no part of the - file path ends with a period, as that would cause problems (#1056). - - aregister - (areg) - - Show the transactions and running historical balance of a single ac- - count, 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 in- - cluded 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 ex- - pression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can be - surprising; eg if you have assets:per:checking 1 and assets:biz:check- - ing 2 accounts, hledger areg checking would select assets:biz:checking - 2. It's just a convenience to save typing, so if in doubt, write the - full account name, or a distinctive substring that matches uniquely. - - Transactions involving subaccounts of this account will also be shown. - aregister ignores depth limits, so its final total will always match a - balance report with similar arguments. - - Any additional arguments form a query which will filter the 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 op- - tions. The output formats supported are txt, csv, tsv, and json. - - aregister and posting dates - aregister always shows one line (and date and amount) per transaction. - But sometimes transactions have postings with different dates. Also, - not all of a transaction's postings may be within the report period. - To resolve this, aregister shows the earliest of the transaction's date - and posting dates that is in-period, and the sum of the in-period post- - ings. In other words it will show a combined line item with just the - earliest date, and the running balance will (temporarily, until the - transaction's last posting) be inaccurate. Use register -H if you need - to see the individual postings. - - There is also a --txn-dates flag, which filters strictly by transaction - date, ignoring posting dates. This too can cause an inaccurate running - 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) - - o or postings count (--count) - - ..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 (--in- - vert) - - 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, tsv, 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. ("Simple" here - means just one column of numbers, covering a single period. You can - also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end bal- - ance 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 (re- - vealing 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. - - Balance report line format - For single-period balance reports displayed in the terminal (only), you - can use --format FMT to customise the format and content of each line. - Eg: - - $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 - --------------------------------- - 0 - - The FMT format string specifies the formatting applied to each ac- - count/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 ef- - fect, 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 - - 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 - - Showing declared accounts - With --declared, accounts which have been declared with an account di- - rective 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 re- - port, even when you don't have transactions in all of your declared ac- - counts yet. - - 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 - biggest averaged monthly expenses first. When more than one commodity - is present, they will be sorted by the alphabetically earliest commod- - ity 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 --in- - vert 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. - - 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: - - 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 - - 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 ac- - count 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 - The balance command is quite flexible; here is the full detail on how - to control what it reports. If the following seems complicated, don't - worry - this is for advanced reporting, and it does take time and ex- - perimentation to get familiar with all the report modes. - - There are three important option groups: - - hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] - ... - - Calculation type - The basic calculation to perform for each table cell. It is one of: - - o --sum : sum the posting amounts (default) - - o --budget : sum the amounts, but also show the budget goal amount (for - each account/period) - - 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) - - o --count : show the count of postings - - Accumulation type - How amounts should accumulate across report periods. Another way to - say it: which time period's postings should contribute to each cell's - calculation. It is one of: - - o --change : calculate with postings from column start to column end, - ie "just this column". Typically used to see revenues/expenses. - (default for balance, incomestatement) - - o --cumulative : calculate with postings from report start to column - end, ie "previous columns plus this column". Typically used to show - changes accumulated since the report's start date. Not often used. - - o --historical/-H : calculate with postings from journal start to col- - umn end, ie "all postings from before report start date until this - column's end". Typically used to see historical end balances of as- - sets/liabilities/equity. (default for balancesheet, balancesheete- - quity, cashflow) - - Valuation type - Which kind of value or cost conversion should be applied, if any, be- - fore displaying the report. It is one of: - - o no valuation type : don't convert to cost or value (default) - - o --value=cost[,COMM] : convert amounts to cost (then optionally to - some other commodity) - - o --value=then[,COMM] : convert amounts to market value on transaction - dates - - o --value=end[,COMM] : convert amounts to market value on period end - date(s) - (default with --valuechange, --gain) - - o --value=now[,COMM] : convert amounts to market value on today's date - - o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- - other date - - or one of the equivalent simpler flags: - - o -B/--cost : like --value=cost (though, note --cost and --value are - independent options which can both be used at once) - - o -V/--market : like --value=end - - o -X COMM/--exchange COMM : like --value=end,COMM - - See Cost reporting and Value reporting for more about these. - - Combining balance report types - Most combinations of these options should produce reasonable reports, - but if you find any that seem wrong or misleading, let us know. The - following restrictions are applied: - - 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 pe- - ues in period in period riod - --cumu- change from re- sum of posting- period-end DATE-value of - lative port 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 - - Budget report - The --budget report type activates extra columns showing any budget - goals for each account and period. The budget goals are defined by pe- - riodic transactions. This is useful for comparing planned and actual - income, expenses, time usage, etc. - - For example, you can take average monthly expenses in the common ex- - pense 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. Cur- - rently: - - o Accounts with budget goals during the report period, and their par- - ents, are shown. - - o Their subaccounts are not shown (regardless of the depth setting). - - o Accounts without budget goals, if any, are aggregated and shown as - "". - - o Amounts are always inclusive (subaccount-including), even in list - mode. - - o After each actual amount, the corresponding goal amount and percent- - age of goal reached are also shown, in square brackets. - - This means that the numbers displayed will not always add up! Eg - above, the expenses actual amount includes the gifts and supplies - transactions, but the expenses:gifts and expenses:supplies accounts are - not shown, as they have no budget amounts declared. - - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted - ones, giving the full picture. Eg: - - $ hledger balance -M --budget --empty - Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - expenses:supplies || $20 0 - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] - ----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - You can roll over unspent budgets to next period with --cumulative: - - $ hledger balance -M --budget --cumulative - Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] - expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] - expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] - income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] - ----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - It's common to limit budgets/budget reports to just expenses - - hledger bal -M --budget expenses - - or just revenues and expenses (eg, using account types): - - hledger bal -M --budget type:rx - - It's also common to limit or convert them to a single currency - (cur:COMM or -X COMM [--infer-market-prices]). If showing multiple - currencies, --layout bare or --layout tall can help. - - For more examples and notes, see Budgeting. - - 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 to- - wards 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: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 ac- - count in each report subperiod. When troubleshooting, you can use - print --forecast to show these as forecasted transactions: - - $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated - - By default, the budget report uses all available periodic transaction - rules to generate goals. This includes rules with a different report - interval from your report. Eg if you have daily, weekly and monthly - periodic rules, all of these will contribute to the goals in a monthly - budget report. - - You can select a subset of periodic rules by providing an argument to - the --budget flag. --budget=DESCPAT will match all periodic rules - whose description contains DESCPAT, a case-insensitive substring (not a - regular expression or query). This means you can give your periodic - rules descriptions (remember that two spaces are needed), and then se- - lect from multiple budgets defined in your journal. - - Budget vs forecast - hledger --forecast ... and hledger balance --budget ... are separate - features, though both of them use the periodic transaction rules de- - fined in the journal, and both of them generate temporary transactions - for reporting purposes ("forecast transactions" and "budget goal trans- - actions", respectively). You can use both features at the same time if - you want. Here are some differences between them, as of hledger 1.29: - - CLI: - - o --forecast is a general hledger option, usable with any command - - o --budget is a balance command option, usable only with that command. - - Visibility of generated transactions: - - o forecast transactions are visible in any report, like ordinary trans- - actions - - o budget goal transactions are invisible except for the goal amounts - they produce in --budget reports. - - Periodic transaction rules: - - o --forecast uses all available periodic transaction rules - - o --budget uses all periodic rules (--budget) or a selected subset - (--budget=DESCPAT) - - Period of generated transactions: - - o --forecast generates forecast transactions - - o from after the last regular transaction to the end of the report - period (--forecast) - - o or, during a specified period (--forecast=PERIODEXPR) - - o possibly further restricted by a period specified in the periodic - transaction rule - - o and always restricted within the bounds of the report period - - o --budget generates budget goal transactions - - o throughout the report period - - o possibly restricted by a period specified in the periodic transac- - tion rule. - - Balance report layout - The --layout option affects how balance reports show multi-commodity - amounts and commodity symbols, which can improve readability. It can - also normalise the data for easy consumption by other programs. It has - four possible values: - - o --layout=wide[,WIDTH]: commodities are shown on a single line, op- - tionally elided to WIDTH - - o --layout=tall: each commodity is shown on a separate line - - o --layout=bare: commodity symbols are in their own column, amounts are - bare numbers - - o --layout=tidy: data is normalised to easily-consumed "tidy" form, - with one row per data value - - Here are the --layout modes supported by each output format; note only - CSV output supports all of them: - - - txt csv html json sql - ------------------------------------- - wide Y Y Y - tall Y Y Y - bare Y Y Y - tidy Y - - Examples: - - 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 for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - o Note: bare layout will sometimes display an extra row for the no-sym- - bol commodity, because of zero amounts (hledger treats zeroes as com- - modity-less, usually). This can break hledger-bar confusingly - (workaround: add a cur: query to exclude the no-symbol row). - - o Tidy layout produces normalised "tidy data", where every variable has - its own column and each row represents a single data point. See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- - data.html for more. This is the easiest kind of data for other soft- - ware to consume. Here's how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - 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 - - 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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - 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 in- - sensitive, 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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - 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 al- - lowed) - - o whose name contains some variation of cash, bank, checking or saving. - - More precisely: all accounts matching this case insensitive regular ex- - pression: - - ^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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - check - Check for various kinds of errors in your data. - - hledger provides a number of built-in error checks to help prevent - problems in your data. Some of these are run automatically; or, you - can use this check command to run them on demand, with no output and a - zero exit code if all is well. Specify their names (or a prefix) as - argument(s). - - Some examples: - - hledger check # basic checks - hledger check -s # basic + strict checks - hledger check ordereddates payees # basic + two other checks - - If you are an Emacs user, you can also configure flycheck-hledger to - run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available: - - Default checks - These checks are run automatically by (almost) all hledger commands: - - o parseable - data files are in a supported format, with no syntax er- - rors and no invalid include directives. - - o autobalanced - all transactions are balanced, after converting to - cost. Missing amounts and missing costs are inferred automatically - where possible. - - 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 balanced - all transactions are balanced after converting to cost, - without inferring missing costs. If conversion costs are required, - they must be explicit. - - o accounts - all account names used by transactions have been declared - - o commodities - all commodity symbols used have been declared - - 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: - - o ordereddates - transactions are ordered by date within each file - - o payees - all payees used by transactions have been declared - - o recentassertions - all accounts with balance assertions have a bal- - ance assertion within 7 days of their latest posting - - o tags - all tags 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. - - More about specific checks - hledger check recentassertions will complain if any balance-asserted - account has postings more than 7 days after its latest balance asser- - tion. This aims to prevent the situation where you are regularly up- - dating your journal, but forgetting to check your balances against the - real world, then one day must dig back through months of data to find - an error. It assumes that adding a balance assertion requires/reminds - you to check the real-world balance. (That may not be true if you - auto-generate balance assertions from bank data; in that case, I recom- - mend to import transactions uncleared, and when you manually review and - clear them, also check the latest assertion against the real-world bal- - ance.) - - close - (equity) - - Generate transactions which transfer account balances to and/or from - another account (typically equity). This can be useful for migrating - balances to a new journal file, or for merging earnings into equity at - end of accounting period. - - By default, it prints a transaction that zeroes out ALE accounts (as- - set, liability, equity accounts; this requires account types to be con- - figured); or if ACCTQUERY is provided, the accounts matched by that. - - (experimental) - - This command has four main modes, corresponding to the most common use - cases: - - 1. With --close (default), it prints a "closing balances" transaction - that zeroes out ALE (asset, liability, equity) accounts by default - (this requires account types to be inferred or declared); or, the - accounts matched by the provided ACCTQUERY arguments. - - 2. With --open, it prints an opposite "opening balances" transaction - that restores those balances from zero. This is similar to Ledger's - equity command. - - 3. With --migrate, it prints both the closing and opening transactions. - This is the preferred way to migrate balances to a new file: run - hledger close --migrate, add the closing transaction at the end of - the old file, and add the opening transaction at the start of the - new file. The matching closing/opening transactions cancel each - other out, preserving correct balances during multi-file reporting. - - 4. With --retain, it prints a "retain earnings" transaction that trans- - fers RX (revenue and expense) balances to equity:retained earnings. - Businesses traditionally do this at the end of each accounting pe- - riod; it is less necessary with computer-based accounting, but it - could still be useful if you want to see the accounting equation - (A=L+E) satisfied. - - In all modes, the defaults can be overridden: - - o the transaction descriptions can be changed with --close-desc=DESC - and --open-desc=DESC - - o the account to transfer to/from can be changed with --close-acct=ACCT - and --open-acct=ACCT - - o the accounts to be closed/opened can be changed with ACCTQUERY (ac- - count query arguments). - - o the closing/opening dates can be changed with -e DATE (a report end - date) - - By default just one destination/source posting will be used, with its - amount left implicit. With --x/--explicit, the amount will be shown - explicitly, and if it involves multiple commodities, a separate posting - will be generated for each of them (similar to print -x). - - With --show-costs, any amount costs are shown, with separate postings - for each cost. This is currently the best way to view investment lots. - If you have many currency conversion or investment transactions, it can - generate very large journal entries. - - With --interleaved, each individual transfer is shown with source and - destination postings next to each other. This could be useful for - troubleshooting. - - The default closing date is yesterday, or the journal's end date, - whichever is later. You can change this by specifying a report end - date with -e. The last day of the report period will be the closing - date, eg -e 2024 means "close on 2023-12-31". The opening date is al- - ways the day after the closing date. - - close and balance assertions - Balance assertions will be generated, verifying that the accounts have - been reset to zero (and then restored to their previous balances, if - there is an opening transaction). - - These provide useful error checking, but you can ignore them temporar- - ily with -I, or remove them if you prefer. - - You probably should avoid filtering transactions by status or realness - (-C, -R, status:), or generating postings (--auto), with this command, - since the balance assertions would depend on these. - - Note custom posting dates spanning the file boundary will disrupt the - balance assertions: - - 2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve that you can transfer the money to and from a temporary ac- - count, in effect splitting the multi-day transaction into two single- - day transactions: - - ; in 2022.journal: - 2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - - ; in 2023.journal: - 2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - Example: retain earnings - Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- - pending the generated transaction to the journal: - - $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - Note 2022's income statement will now show only zeroes, because rev- - enues and expenses have been moved entirely to equity. To see them - again, you could exclude the retain transaction: - - $ hledger -f 2022.journal is not:desc:'retain earnings' - - Example: migrate balances to a new file - Close assets/liabilities/equity on 2022-12-31 and re-open them on - 2023-01-01: - - $ hledger close --migrate -f 2022.journal -p 2022 - # copy/paste the closing transaction to the end of 2022.journal - # copy/paste the opening transaction to the start of 2023.journal - - Now 2022's balance sheet will show only zeroes, indicating a balanced - accounting equation. (Unless you are using @/@@ notation - in that - case, try adding --infer-equity.) To see the end-of-year balances - again, you could exclude the closing transaction: - - $ hledger -f 2022.journal bs not:desc:'closing balances' - - Example: excluding closing/opening transactions - When combining many files for multi-year reports, the closing/opening - transactions cause some noise in transaction-oriented reports like - print and register. You can exclude them as shown above, but - not:desc:... is not ideal as it depends on consistent descriptions; - also you will want to avoid excluding the very first opening transac- - tion, which could be awkward. Here is one alternative, using tags: - - Add clopen: tags to all opening/closing balances transactions except - the first, like this: - - ; 2021.journal - 2021-06-01 first opening balances - ... - 2021-12-31 closing balances ; clopen:2022 - ... - - ; 2022.journal - 2022-01-01 opening balances ; clopen:2022 - ... - 2022-12-31 closing balances ; clopen:2023 - ... - - ; 2023.journal - 2023-01-01 opening balances ; clopen:2023 - ... - - Now, assuming a combined journal like: - - ; all.journal - include 2021.journal - include 2022.journal - include 2023.journal - - The clopen: tag can exclude all but the first opening transaction. To - show a clean multi-year checking register: - - $ hledger -f all.journal areg checking not:tag:clopen - - And the year values allow more precision. To show 2022's year-end bal- - ance sheet: - - $ hledger -f all.journal bs -e2023 not:tag:clopen=2023 - - codes - List the codes seen in transactions, in the order parsed. - - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often - used to store a cheque number, order number or similar. - - Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be - printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - - 2022/1/1 (123) Supermarket - Food $5.00 - Checking - - 2022/1/2 (124) Post Office - Postage $8.32 - Checking - - 2022/1/3 Supermarket - Food $11.23 - Checking - - 2022/1/4 (126) Post Office - Postage $3.21 - Checking - - $ hledger codes - 123 - 124 - 126 - - $ hledger codes -E - 123 - 124 - - 126 - - commodities - List all commodity/currency symbols used or declared in the journal. - - demo - Play demos of hledger usage in the terminal, if asciinema is installed. - - Run this command with no argument to list the demos. To play a demo, - write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/--speed SPEED option to set your preferred playback speed, - eg -s4 to play at 4x original speed or -s.5 to play at half speed. The - default speed is 2x. - - Other asciinema options can be added following a double dash, eg -- - -i.1 to limit pauses or -- -h to list asciinema's other options. - - During playback, several keys are available: SPACE to pause/unpause, . - to step forward (while paused), CTRL-c quit. - - Examples: - - $ hledger demo # list available demos - $ hledger demo 1 # play the first demo at default speed (2x) - $ hledger demo install -s4 # play the "install" demo at 4x speed - - 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 - 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 - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - help - Show the hledger user manual in the terminal, with info, man, or a - pager. With a TOPIC argument, open it at that topic if possible. - TOPIC can be any heading in the manual, or a heading prefix, case in- - sensitive. Eg: commands, print, forecast, journal, amount, "auto post- - ings". - - This command shows the hledger manual built in to your hledger version. - It can be useful when offline, or when you prefer the terminal to a web - browser, or when the appropriate hledger manual or viewing tools are - not installed on your system. - - By default it chooses the best viewer found in $PATH, trying (in this - order): info, man, $PAGER, less, more. You can force the use of info, - man, or a pager with the -i, -m, or -p flags, If no viewer can be - found, or the command is run non-interactively, it just prints the man- - ual to stdout. - - If using info, note that version 6 or greater is needed for TOPIC - lookup. If you are on mac you will likely have info 4.8, and should - consider installing a newer version, eg with brew install texinfo - (#1770). - - Examples - - $ hledger help --help # show how the help command works - $ hledger help # show the hledger manual with info, man or $PAGER - $ hledger help journal # show the journal topic in the hledger manual - $ hledger help -m journal # show it with man, even if info is installed - - import - Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. - - 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 - import does time-based deduplication, to detect only the new transac- - tions since the last successful import. (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 periodi- - cally importing downloaded data, which may overlap with previous down- - loads. Eg if every week (or every day) you download a bank's last - three months of CSV data, you can safely run hledger import thebank.csv - each time and only new transactions will be imported. - - 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.FILE" file in FILE's directory (after a succesful - import). - - Eg when reading finance/bank.csv, it will look for and update the fi- - nance/.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 cer- - tain date. - - Note deduplication (and updating of state files) can also be done by - print --new, but this is less often used. - - Related: CSV > Working with CSV > Deduplicating, importing. - - Import testing - With --dry-run, the transactions that will be imported are printed to - the terminal, without updating your journal or state files. The output - is valid journal format, like the print command, so you can re-parse - it. Eg, to see any importable transactions which CSV rules have not - categorised: - - $ hledger import --dry bank.csv | hledger -f- -I print unknown - - or (live updating): - - $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' - - Note: when importing from multiple files at once, it's currently possi- - ble for some .latest files to be updated successfully, while the actual - import fails because of a problem in one of the files, leaving them out - of sync (and causing some transactions to be missed). To prevent this, - do a --dry-run first and fix any problems before the real import. - - 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 - (is) - - This command displays an income statement, showing revenues and ex- - penses during one or more periods. Amounts are shown with normal posi- - tive 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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - notes - List the unique notes that appear in transactions. - - This command lists the unique notes that appear in transactions, in al- - phabetic 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 - 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 - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With - --show-reverse, also show additional prices inferred by reversing known - prices. - - Price amounts are always displayed with their full precision, except - for reverse prices which are limited to 8 decimal digits. - - Prices can be filtered by a date:, cur: or amt: query. - - Generally if you run this command with --infer-market-prices --show-re- - verse, it will show the same prices used internally to calculate value - reports. But if in doubt, you can inspect those directly by running - the value report with --debug=2. - - 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). - - 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/regenerate your journal you should take care to also copy - over the directives and inter-transaction comments. - - Eg: - - $ hledger print -f examples/sample.journal date:200806 - 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 - - print explicitness - Normally, whether posting amounts are implicit or explicit is pre- - served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, if a conversion cost is implied - but not written, it will not appear in the output. - - You can use the -x/--explicit flag to force explicit display of all - amounts and costs. This can be useful for troubleshooting or for mak- - ing your journal more readable and robust against data entry errors. - -x is also implied by using any of -B,-V,-X,--value. - - The -x/--explicit flag will cause any postings with a multi-commodity - amount (which can arise when a multi-commodity transaction has an im- - plicit amount) to be split into multiple single-commodity postings, - keeping the output parseable. - - print amount style - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can do that with ledger-mode in - Emacs). - - Amounts will be (mostly) normalised to their commodity display style: - their symbol placement, decimal mark, and digit group marks will be - made consistent. By default, decimal digits are shown as they are - written in the journal. - - With the --round option, print will try increasingly hard to display - decimal digits according to the commodity display styles: - - o --round=none show amounts with original precisions (default) - - o --round=soft add/remove decimal zeros in amounts (except costs) - - o --round=hard round amounts (except costs), possibly hiding signifi- - cant digits - - o --round=all round all amounts and costs - - soft is good for non-lossy cleanup, formatting amounts more consis- - tently where it's safe to do so. - - hard and all can cause print to show invalid unbalanced journal en- - tries; they may be useful eg for stronger cleanup, with manual fixups - when needed. - - print parseability - 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 (though the same can be achieved with expr: queries - now): - - # 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 Value reporting affects posting amounts but not balance assertion or - balance 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. - - print, other features - With -B/--cost, amounts with costs are shown converted to cost. - - With --new, print shows 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.) - - With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription is most similar to DESC. DESC should contain at least two - characters. If there is no similar-enough match, no transaction will - be shown and the program exit code will be non-zero. - - print output format - This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount, csv, tsv, json - and sql. - - Experimental: The beancount format tries to produce Beancount-compati- - ble output, as follows: - - o Transaction and postings with unmarked status are converted to - cleared (*) status. - - o Transactions' payee and note are backslash-escaped and double-quote- - escaped and wrapped in double quotes. - - o Transaction tags are copied to Beancount #tag format. - - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency - names. - - o Account name parts are capitalised and unsupported characters are re- - placed with -. If an account name part does not begin with a letter, - or if the first part is not Assets, Liabilities, Equity, Income, or - Expenses, an error is raised. (Use --alias options to bring your ac- - counts into compliance.) - - o An open directive is generated for each account used, on the earliest - transaction date. - - Some limitations: - - o Balance assertions are removed. - - o Balance assignments become missing amounts. - - o Virtual and balanced virtual postings become regular postings. - - o Directives are not converted. - - 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.) - - 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 ac- - count 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 to- - gether with the related account: - - $ hledger register --related --invert assets:checking - - With a reporting interval, register shows summary postings, one per in- - terval, 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 op- - tion 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 in- - tervals. This ensures that the first and last intervals are full - length and comparable to the others in the report. - - With -m DESC/--match=DESC, register does a fuzzy search for one recent - posting whose description is most similar to DESC. DESC should contain - at least two characters. If there is no similar-enough match, no post- - ing will be shown and the program exit code will be non-zero. - - 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 de- - scription 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 op- - tions The output formats supported are txt, csv, tsv, and (experimen- - tal) json. - - 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 in- - cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- - ity. - - 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 - 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 ac- - count 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, also known as money-weighted rate of return) and time-weighted - rate of return (TWR) for your investments for the time period re- - quested. IRR is always annualized due to the way it is computed, but - TWR is reported both as a rate over the chosen reporting period and as - an annual rate. - - 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 be- - comes 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 as- - sets, 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 re- - turn. - - 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, and the - time between them. Investment at a particular fixed interest rate is - going to give you more interest than the same amount invested at the - same interest rate, but made later in time. 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, - so your IRR will be smaller. And if you are adding to your investment, - you will receive bigger absolute gains, which will be a bigger percent- - age of your initial investment, so your IRR will be larger. - - 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 ac- - count for the effect of your in-flows and out-flows, but unlike IRR it - will try to compute the true rate of return of the underlying asset, - compensating for the effect that deposits and withdrawas have on the - apparent rate of growth of your investment. - - 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, and make TWR less sensitive than IRR to the effects of - cash in-flows and out-flows. - - References: - - o Explanation of rate of return - - o Explanation of IRR - - o Explanation of TWR - - o IRR vs TWR - - o Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - stats - Show journal and performance statistics. - - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report - for each report period. - - At the end, it shows (in the terminal) the overall run time and number - of transactions processed per second. Note these are approximate and - will vary based on machine, current load, data size, hledger version, - haskell lib versions, GHC version.. but they may be of interest. The - stats command's run time is similar to that of a single-column balance - report. - - Example: - - $ hledger stats -f examples/1000x1000x10.journal - Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal - Included files : - Transactions span : 2000-01-01 to 2002-09-27 (1000 days) - Last transaction : 2002-09-26 (6995 days ago) - Transactions : 1000 (1.0 per day) - Transactions last 30 days: 0 (0.0 per day) - Transactions last 7 days : 0 (0.0 per day) - Payees/descriptions : 1000 - Accounts : 1000 (depth 10) - Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) - Market prices : 1000 (A) - - Run time : 0.12 s - Throughput : 8342 txns/s - - This command supports the -o/--output-file option (but not -O/--output- - format selection). - - 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 - 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). - -PART 5: COMMON TASKS - Here are some quick examples of how to do some basic tasks with - hledger. - - Getting help - Here's how to list commands and view options and command docs: - - $ hledger # show available commands - $ hledger --help # show common options - $ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version's manual in several formats by - using the help command. Eg: - - $ hledger help # show the hledger manual with info, man or $PAGER (best available) - $ hledger help journal # show the journal topic in the hledger manual - $ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit - https://hledger.org. Chat and mail list support and discussion - archives can be found at https://hledger.org/support. - - Constructing command lines - hledger has a flexible command line interface. We strive to keep it - simple and ergonomic, but if you run into one of the sharp edges de- - scribed in OPTIONS, here are some tips that might help: - - o command-specific options must go after the command (it's fine to put - common options there too: 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 line 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 - (see below). 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 2023.journal - $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile - $ source ~/.profile - $ hledger stats - Main file : /Users/simon/finance/2023.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 LEDGER_FILE - How to set LEDGER_FILE permanently depends on your setup: - - On unix and mac, running these commands in the terminal will work for - many people; adapt as needed: - - $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile - $ source ~/.profile - - When correctly configured, in a new terminal window env | grep - LEDGER_FILE will show your file, and so will hledger files. - - On mac, this additional step might be helpful for GUI applications - (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- - ment.plist like - - { - "LEDGER_FILE" : "~/finance/2023.journal" - } - - and then run killall Dock in a terminal window (or restart the ma- - chine). - - On Windows, see https://www.java.com/en/download/help/path.html, or try - running these commands in a powershell window (let us know if it per- - sists across a reboot, and if you need to be an Administrator): - - > CD - > MKDIR finance - > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - 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 re- - cent starting date, like today or the start of the week. You can al- - ways 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: - - 2023-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/2023.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 [2023-02-07]: 2023-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): . - 2023-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 [2023-01-01]: . - - If you're using version control, this could be a good time to commit - the journal. Eg: - - $ git commit -m 'initial balances' 2023.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: - - 2023/1/10 * gift received - assets:cash $20 - income:gifts - - 2023.1.12 * farmers market - expenses:food $13 - assets:cash - - 2023-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 al- - ready-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: - - 2023-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 re- - ported by hledger reg checking -C. This will be easier if you gen- - erally record transaction dates quite similar to your bank's clear- - ing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a live-up- - dating register while you edit the journal: hledger-ui --watch --regis- - ter 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 2023-01-15 and paycheck - - If you're using version control, this can be another good time to com- - mit: - - $ git commit -m 'txns' 2023.journal - - Reporting - Here are some basic reports. - - Show all transactions: - - $ hledger print - 2023-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - - 2023-01-10 * gift received - assets:cash $20 - income:gifts - - 2023-01-12 * farmers market - expenses:food $13 - assets:cash - - 2023-01-15 * paycheck - income:salary - assets:bank:checking $1000 - - 2023-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - - $ hledger accounts --tree - assets - bank - checking - savings - cash - equity - opening/closing balances - expenses - food - misc - income - gifts - salary - liabilities - creditcard - - Show all account totals: - - $ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard - -------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to - depth 2: - - $ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard - -------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple - balance sheet: - - $ hledger bs -2 - Balance Sheet 2023-01-16 - - || 2023-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 2023-01-01-2023-01-16 - - || 2023-01-01-2023-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 - 2023-01-01 opening balances assets:cash $100 $100 - 2023-01-10 gift received assets:cash $20 $120 - 2023-01-12 farmers market assets:cash $-13 $107 - 2023-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - - $ hledger activity -W - 2019-12-30 ***** - 2023-01-06 **** - 2023-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. - -BUGS - We welcome bug reports in the hledger issue tracker (shortcut: - http://bugs.hledger.org), or on the #hledger chat or hledger mail list - (https://hledger.org/support). - - Some known issues and limitations: - - The need to precede add-on command options with -- when invoked from - hledger is awkward. (See Command options, Constructing command lines.) - - A UTF-8-aware system locale must be configured to work with non-ascii - data. (See Unicode characters, Troubleshooting.) - - On Microsoft Windows, depending whether you are running in a CMD window - or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii - characters and colours may not be supported, and the tab key may not be - supported by hledger add. (Running in a WSL window should resolve - these.) - - When processing large data files, hledger uses more memory than Ledger. - - Troubleshooting - Here are some common issues you might encounter when you run hledger, - and how to resolve them (and remember also you can usually get quick - Support): - - PATH issues: I get an error like "No command 'hledger' found" - Depending how you installed hledger, the executables may not be in your - shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- - cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one - of these directories to your shell's PATH, and/or open a new terminal - window. - - LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using - it - o LEDGER_FILE should be a real environment variable, not just a shell - variable. Eg on unix, the command env | grep LEDGER_FILE should show - it. You may need to use export (see https://stackover- - flow.com/a/7411509). - - o You may need to force your shell to see the new configuration. A - simple way is to close your terminal window and open a new one. - - LANG issues: I get errors like "Illegal byte sequence" or "Invalid or - incomplete multibyte or wide character" or "commitAndReleaseBuffer: in- - valid argument (invalid character)" - Programs compiled with GHC (hledger, haskell build tools, etc.) need - the system locale to be UTF-8-aware, or they will fail when they en- - counter non-ascii characters. To fix it, set the LANG environment - variable to a locale which supports UTF-8 and which is installed on - your system. - - On unix, locale -a lists the installed locales. Look for one which - mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8, - fr_FR.utf8. If necessary, use your system package manager to install - one. Then select it by setting the LANG environment variable. Note, - exact spelling and capitalisation of the locale name may be important: - Here's one common way to configure this permanently for your shell: - - $ echo "export LANG=en_US.utf8" >>~/.profile - # close and re-open terminal window - - If you are using Nix (not NixOS) for GHC and Hledger, you might need to - set the LOCALE_ARCHIVE variable: - - $ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile - # close and re-open terminal window - - COMPATIBILITY ISSUES: hledger gives an error with my Ledger file - Not all of Ledger's journal file syntax or feature set is supported. - See hledger and Ledger for full details. - - - -AUTHORS - Simon Michael and contributors. - See http://hledger.org/CREDITS.html - - -COPYRIGHT - Copyright 2007-2023 Simon Michael and contributors. - - -LICENSE - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), ledger(1) - -hledger-1.32 December 2023 HLEDGER(1) + This manual is for hledger's command line interface, version 1.32.1. + It also describes the common options, file formats and concepts used by + all hledger programs. It might accidentally teach you some bookkeep- + ing/accounting as well! You don't need to know everything in here to + use hledger productively, but when you have a question about function- + ality, this doc should answer it. It is detailed, so do skip ahead or + skim when needed. You can read it on hledger.org, or as an info manual + or man page on your system. You can also get it from hledger itself + with + hledger --man, hledger --info or hledger help [TOPIC]. + + The main function of the hledger CLI is to read plain text files de- + scribing financial transactions, crunch the numbers, and print a useful + report on the terminal (or save it as HTML, CSV, JSON or SQL). Many + reports are available, as subcommands. hledger will also detect other + hledger-* executables as extra subcommands. + + hledger usually reads from (and appends to) a journal file specified by + the LEDGER_FILE environment variable (defaulting to + $HOME/.hledger.journal); or you can specify files with -f options. It + can also read timeclock files, timedot files, or any CSV/SSV/TSV file + with a date field. + + Here is a small journal file describing one transaction: + + 2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more + accounts: bank accounts, your wallet, revenue/expense categories, peo- + ple, etc. You can choose any account names you wish, using : to indi- + cate subaccounts. There must be at least two spaces between account + name and amount. Positive amounts are inflow to that account (debit), + negatives are outflow from it (credit). (Some reports show revenue, + liability and equity account balances as negative numbers as a result; + this is normal.) + + hledger's add command can help you add transactions, or you can install + other data entry UIs like hledger-web or hledger-iadd. For more exten- + sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM + + vim-ledger, or VS Code + hledger-vscode are some good choices (see + https://hledger.org/editors.html). + + To get started, run hledger add and follow the prompts, or save some + entries like the above in $HOME/.hledger.journal, then try commands + like: + hledger print -x + hledger aregister assets + hledger balance + hledger balancesheet + hledger incomestatement. + Run hledger to list the commands. See also the "Starting a journal + file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +PART 1: USER INTERFACE +Input + hledger reads one or more data files, each time you run it. You can + specify a file with -f, like so + + $ hledger -f FILE print + + Files are most often in hledger's journal format, with the .journal + file extension (.hledger or .j also work); these files describe trans- + actions, like an accounting general journal. + + When no file is specified, hledger looks for .hledger.journal in your + home directory. + + But most people prefer to keep financial files in a dedicated folder, + perhaps with version control. Also, starting a new journal file each + year is common (it's not required, but helps keep things fast and or- + ganised). So we usually configure a different journal file, by setting + the LEDGER_FILE environment variable, to something like ~/fi- + nance/2023.journal. For more about how to do that on your system, see + Common tasks > Setting LEDGER_FILE. + + 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 .journal .j .hledger .ledger + Ledger journals, for transac- + tions + timeclock timeclock files, for precise .timeclock + time logging + timedot timedot files, for approximate .timedot + time logging + csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules + rated values, for data import .ssv.rules .tsv.rules + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a + recognised file extension, so as to either read successfully or to show + relevant error messages. + + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg, to read a .dat file as csv format: + + $ hledger -f csv:/some/csv-file.dat stats + + Standard input + The file name - means standard input: + + $ cat FILE | hledger -f- print + + If reading non-journal data in this way, you'll need to add a file for- + mat prefix, like: + + $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- + + Multiple files + You can specify multiple -f options, to read multiple files as one big + journal. When doing this, note that certain features (described below) + will be affected: + + o Balance assertions will not see the effect of transactions in previ- + ous files. (Usually this doesn't matter as each file will set the + corresponding opening balances.) + + o Some directives will not affect previous or subsequent files. + + If needed, you can work around these by using a single parent file + which includes the others, or concatenating the files into one, 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. + +Commands + hledger provides various subcommands for getting things done. Most of + these commands do not change the journal file; they just read it and + output a report. A few commands assist with adding data and file man- + agement. + + To show the commands list, run hledger with no arguments. The commands + are described in detail in PART 4: COMMANDS, below. + + To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], + + o CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + o CMDOPTS are command-specific options, if any. Command-specific op- + tions must be written after the command name. Eg: hledger print -x. + + o CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit the + data in some way. Eg: hledger reg assets:checking. + + To list a command's options, arguments, and documentation in the termi- + nal, run hledger CMD -h. Eg: hledger bal -h. + + Add-on commands + In addition to the built-in commands, you can install add-on commands: + programs or scripts named "hledger-SOMETHING", which will also appear + in hledger's commands list. If you used the hledger-install script, + you will have several add-ons installed already. Some more can be + found in hledger's bin/ directory, documented at + https://hledger.org/scripts.html. + + More precisely, add-on commands are programs or scripts in your shell's + PATH, whose name starts with "hledger-" and ends with no extension or a + recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", + ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix + and mac) which has executable permission for the current user. + + You can run add-on commands using hledger, much like built-in commands: + hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double + hyphen argument, required before add-on-specific options. Eg: hledger + ui -- --watch or hledger web -- --serve. If this causes difficulty, + you can always run the add-on directly, without using hledger: hledger- + ui --watch or hledger-web --serve. + +Options + Run hledger -h to see general command line help, and general options + which are common to most hledger commands. These options can be writ- + ten anywhere on the command line. They can be grouped into help, in- + put, and reporting options: + + 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 de- + clared) + + 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 ef- + fects) + + --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-equity + infer conversion equity postings from costs + + --infer-costs + infer costs from conversion equity postings + + --infer-market-prices + use costs as additional market prices, as if they were P direc- + tives + + --forecast + generate transactions from periodic rules, between the latest + recorded txn and 6 months from today, or during the specified + PERIOD (= is required). Auto posting rules will be applied to + these transactions as well. Also, in hledger-ui make future- + dated transactions visible. + + --auto generate extra postings by applying auto posting rules to all + txns (not just forecast txns) + + --verbose-tags + add visible tags indicating transactions or postings which have + been generated/modified + + --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 line tips + Here are some details useful to know about for hledger command lines + (and elsewhere). Feel free to skip this section until you need it. + + Option repetition + If options are repeated in a command line, hledger will generally use + the last (right-most) occurence. + + 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 ac- + count 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 be- + low), 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:\\$ + + 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 de- + code 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 + A regular expression (regexp) is a small piece of text where certain + characters (like ., ^, $, +, *, (), |, [], \) have special meanings, + forming a tiny language for matching text precisely - very useful in + hledger and elsewhere. To learn all about them, visit regular-expres- + sions.info. + + hledger supports regexps whenever you are entering a pattern to match + something, eg in query arguments, account aliases, CSV if rules, + hledger-web's search form, hledger-ui's / search, etc. You may need to + wrap them in quotes, especially at the command line (see Special char- + acters above). Here are some examples: + + Account name queries (quoted for command line use): + + Regular expression: Matches: + ------------------- ------------------------------------------------------------ + bank assets:bank, assets:bank:savings, expenses:art:banksy, ... + :bank assets:bank:savings, expenses:art:banksy + :bank: assets:bank:savings + '^bank' none of those ( ^ matches beginning of text ) + 'bank$' assets:bank ( $ matches end of text ) + 'big \$ bank' big $ bank ( \ disables following character's special meaning ) + '\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) + '(sav|check)ing' saving or checking ( (|) matches either alternative ) + 'saving|checking' saving or checking ( outer parentheses are not needed ) + 'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) + 'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) + 'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) + 'b.nk' bank, bonk, b nk, ... ( . matches any character ) + + Some other queries: + + desc:'amazon|amzn|audible' Amazon transactions + cur:EUR amounts with commodity symbol containing EUR + cur:'\$' amounts with commodity symbol containing $ + cur:'^\$$' only $ amounts, not eg AU$ or CA$ + cur:....? amounts with 4-or-more-character symbols + tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 + + Account name aliases: accept . instead of : as account separator: + + alias /\./=: replaces all periods in account names with colons + + Show multiple top-level accounts combined as one: + + --alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) + + Show accounts with the second-level part removed: + + --alias '/^([^:]+):[^:]+/ = \1' + match a top-level account and a second-level account + and replace those with just the top-level account + ( \1 in the replacement text means "whatever was matched + by the first parenthesised part of the regexp" + + CSV rules: match CSV records containing dining-related MCC codes: + + if \?MCC581[124] + + Match CSV records with a specific amount around the end/start of month: + + if %amount \b3\.99 + & %date (29|30|31|01|02|03)$ + + hledger's regular expressions + 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. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the re- + placement string to reference capturing groups in the search regexp. + Otherwise, if you write \1, it will match the digit 1. + + 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. + + Argument files + You can save a set of command line options and arguments in a file, and + then reuse them by writing @FILENAME as a command line argument. Eg: + hledger bal @foo.args. + + Inside the argument file, each line should contain just one option or + argument. Don't use spaces except inside quotes (or you'll see a con- + fusing error); write = (or nothing) between a flag and its argument. + For the special characters mentioned above, use one less level of quot- + ing than you would at the command prompt. + +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) + + Output format + Some commands offer other kinds of output, not just text on the termi- + nal. Here are those commands and the formats currently supported: + + - txt csv/tsv html json sql + -------------------------------------------------------------------------------------- + aregister Y Y Y Y + balance Y 1 Y 1 Y 1,2 Y + balancesheet Y 1 Y 1 Y 1 Y + balancesheete- Y 1 Y 1 Y 1 Y + quity + 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 + + 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 + + Some notes about the various output formats: + + 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 This is not yet much used; real-world feedback is welcome. + + o Our JSON is rather large and verbose, since it is a faithful repre- + sentation 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 This is not yet much used; real-world feedback is welcome. + + o SQL output is expected to work at least with SQLite, MySQL and Post- + gres. + + o For SQLite, it will be more useful if you modify the generated id + field to be a PRIMARY KEY. Eg: + + $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... + + 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 + When displaying amounts, hledger infers a standard display style for + each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a -c/--commodity-style option (ex- + cept for cost amounts and amounts displayed by the print command, which + are always displayed with all decimal digits). For example, the fol- + lowing will force dollar amounts to be displayed as shown: + + $ hledger print -c '$1.000,0' + + This option can repeated to set the display style for multiple commodi- + ties/currencies. Its argument is as described in the commodity direc- + tive. + + Colour + In terminal output, some commands can produce colour when the terminal + supports it: + + o if the --color/--colour option is given a value of yes or always (or + no or never), colour will (or will not) be used; + + o otherwise, if the NO_COLOR environment variable is set, colour will + not be used; + + o otherwise, colour will be used if the output (terminal or file) sup- + ports it. + + Box-drawing + In terminal output, you can enable unicode box-drawing characters to + render prettier tables: + + o if the --pretty option is given a value of yes or always (or no or + never), unicode characters will (or will not) be used; + + o otherwise, unicode characters will not be used. + + Paging + When showing long output in the terminal, hledger will try to use the + pager specified by the PAGER environment variable, or less, or more. + (A pager is a helper program that shows one page at a time rather than + scrolling everything off screen). Currently it does this only for help + output, not for reports; specifically, + + o when listing commands, with hledger + + o when showing help with hledger [CMD] --help, + + o when viewing manuals with hledger help or hledger --man. + + Note the pager is expected to handle ANSI codes, which hledger uses eg + for bold emphasis. For the common pager less (and its more compatibil- + ity mode), we add R to the LESS and MORE environment variables to make + this work. If you use a different pager, you might need to configure + it similarly, to avoid seeing junk on screen (let us know). Otherwise, + you can set the NO_COLOR environment variable to 1 to disable all ANSI + output (see Colour). + + Debug output + We intend hledger to be relatively easy to troubleshoot, introspect and + develop. You can add --debug[=N] to any hledger command line to see + additional debug output. N ranges from 1 (least output, the default) + to 9 (maximum output). Typically you would start with 1 and increase + until you are seeing enough. Debug output goes to stderr, and is not + affected by -o/--output-file (unless you redirect stderr to stdout, eg: + 2>&1). It will be interleaved with normal output, which can help re- + veal when parts of the code are evaluated. To capture debug output in + a log file instead, you can usually redirect stderr, eg: + + hledger bal --debug=3 2>hledger.log + +Environment + These environment variables affect hledger: + + COLUMNS This is normally set by your terminal; some hledger commands + (register) will format their output to this width. If not set, they + will try to use the available terminal width. + + LEDGER_FILE The main journal file to use when not specified with + -f/--file. Default: $HOME/.hledger.journal. + + NO_COLOR If this environment variable is set (with any value), hledger + will not use ANSI color codes in terminal output, unless overridden by + an explicit --color/--colour option. + +PART 2: DATA FORMATS +Journal + hledger's default file format, representing a General Journal. Here's + a cheatsheet/mini-tutorial, or you can skip ahead to About journal for- + mat. + + Journal cheatsheet + # Here is the main syntax of hledger's journal format + # (omitting extra Ledger compatibility syntax). + # hledger journals contain comments, directives, and transactions, in any order: + + ############################################################################### + # 1. Comment lines are for notes or temporarily disabling things. + # They begin with #, ;, or a line containing the word "comment". + + # hash comment line + ; semicolon comment line + comment + These lines + are commented. + end comment + + # Some but not all hledger entries can have same-line comments attached to them, + # from ; (semicolon) to end of line. + + ############################################################################### + # 2. Directives modify parsing or reports in some way. + # They begin with a word or letter (or symbol). + + account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. + account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) + alias chkg = assets:checking + commodity $0.00 + decimal-mark . + include /dev/null + payee Whole Foods + P 2022-01-01 AAAA $1.40 + ~ monthly budget goals ; <- 2+ spaces between period expression and description + expenses:food $400 + expenses:home $1000 + budgeted + + ############################################################################### + # 3. Transactions are what it's all about; they are dated events, + # usually describing movements of money. + # They begin with a date. + + # DATE DESCRIPTION ; This is a transaction comment. + # ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. + # ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. + # ; ^^ At least 2 spaces between account and amount. + # ... ; Any number of postings is allowed. The amounts must balance (sum to 0). + + 2022-01-01 opening balances are declared this way + assets:checking $1000 ; Account names can be anything. lower case is easy to type. + assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. + assets:cash:wallet $100 ; : indicates subaccounts. + liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. + equity ; One amount can be left blank; $-1900 is inferred here. + + 2022-04-15 * (#12345) pay taxes + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a transaction code (text in parentheses) after the date/status. + ; Amounts' sign represents direction of flow, or credit/debit: + assets:checking $-500 ; minus means removed from this account (credit) + expenses:tax:us:2021 $500 ; plus means added to this account (debit) + ; revenue/expense categories are also "accounts" + + 2022-01-01 ; The description is optional. + ; Any currency/commodity symbols are allowed, on either side. + assets:cash:wallet GBP -10 + expenses:clothing GBP 10 + assets:gringotts -10 gold + assets:pouch 10 gold + revenues:gifts -2 "Liquorice Wands" ; Complex symbols + assets:bag 2 "Liquorice Wands" ; must be double-quoted. + + 2022-01-01 Cost in another commodity can be noted with @ or @@ + assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments 3.0 AAAA @@ $4 ; @@ means total cost + assets:checking $-7.00 + + 2022-01-02 assert balances + ; Balances can be asserted for extra error checking, in any transaction. + assets:investments 0 AAAA = 5.0 AAAA + assets:pouch 0 gold = 10 gold + assets:savings $0 = $1000 + + 1999-12-31 Ordering transactions by date is recommended but not required. + ; Postings are not required. + + 2022.01.01 These date + 2022/1/1 formats are + 12/31 also allowed (but consistent YYYY-MM-DD is recommended). + + About journal format + hledger's usual data source is a plain text file containing journal en- + tries in hledger journal format. This file represents a standard ac- + counting 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 compatible with most of Ledger's journal + format, but not all of it. The differences and interoperation tips are + described at hledger and Ledger. With some care, and by avoiding in- + compatible features, you can keep your hledger journal readable by + Ledger and vice versa. This can useful eg for comparing the behaviour + of one app against the other. + + 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). + + A hledger journal file can contain three kinds of thing: file comments, + transactions, and/or directives (counting periodic transaction rules + and auto posting rules as directives). + + Comments + Lines in the journal will be ignored if they begin with a hash (#) or a + semicolon (;). (See also Other syntax.) hledger will also ignore re- + gions beginning with a comment line and ending with an end comment line + (or file end). Here's a suggestion for choosing between them: + + o # for top-level notes + + o ; for commenting out things temporarily + + o comment for quickly commenting large regions (remember it's there, or + you might get confused) + + Eg: + + # a comment line + ; another commentline + comment + A multi-line comment block, + continuing until "end comment" directive + or the end of the current file. + end comment + + Some hledger entries can have same-line comments attached to them, from + ; (semicolon) to end of line. See Transaction comments, Posting com- + ments, and Account comments below. + + 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 op- + tional 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 Y directive, or the cur- + rent 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.) + + 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 re- + ports, and the deduction from checking should be reported on 6/1 for + easy bank reconciliation: + + 2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + + $ hledger -f t.j register food + 2015-05-30 expenses:food $10 $10 + + $ hledger -f t.j register checking + 2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. + The date: tag must have a valid simple date value if it is present, eg + a date: tag with no value is not allowed. + + Status + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction de- + scription or posting account name, separated from it by a space, indi- + cating 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 un- + marked 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 un- + cashed 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 (af- + ter the first |). This may be worthwhile if you need to do more pre- + cise querying and pivoting by payee or by note. + + Transaction comments + Text following ;, after a transaction description, and/or on indented + lines immediately below it, form comments for that transaction. They + are reproduced by print but otherwise ignored, except they may contain + tags, which are not ignored. + + 2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + 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 + spaces. But if you accidentally leave only one space (or tab) before + the amount, the amount will be considered part of the account name. + + Account names + Accounts are the main way of categorising things in hledger. As in + Double Entry Bookkeeping, they can represent real world accounts (such + as a bank account), or more abstract categories such as "money borrowed + from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the + traditional accounting categories, which in english are assets, liabil- + ities, equity, revenues, expenses. (You might see these referred to as + A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts + into more detailed subaccounts, by writing a full colon between account + name parts. For example, from the account names assets:bank:checking + and expenses:food, hledger will infer this hierarchy of five accounts: + + assets + assets:bank + assets:bank:checking + expenses + expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + + assets + bank + checking + expenses + food + + hledger reports can summarise the account tree to any depth, so you can + go as deep as you like with subcategories, but keeping your account + names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, num- + bers, symbols, or single spaces. Note, when an account name and an + amount are written on the same line, they must be separated by two or + more spaces (or tabs). + + Parentheses or brackets enclosing the full account name indicate vir- + tual postings, described below. Parentheses or brackets internal to + the account name have no special meaning. + + Account names can be altered temporarily or permanently by account + aliases. + + Amounts + After the account name, there is usually an amount. (Important: be- + tween 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,23 + + 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 + + hledger is not biased towards period or comma decimal marks, so a num- + ber containing just one period or comma, like 1,000 or 1.000, is am- + biguous. In such cases hledger assumes it is a decimal mark, parsing + both of these as 1. + + To disambiguate these and ensure accurate number parsing, especially if + you use digit group marks, we recommend declaring the decimal mark. + You can declare it for each file with decimal-mark directives, or for + each commodity with commodity directives (described 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, but here's a quick example: + + # the decimal mark character used by all amounts in this file (all commodities) + decimal-mark . + + # display styles for the $, EUR, INR and no-symbol commodities: + commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.00 + commodity 1 000 000.9455 + + Commodity display style + For the amounts in each commodity, hledger chooses a consistent display + style (symbol placement, decimal mark and digit group marks, number of + decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a D directive declaring a default commodity, that + commodity symbol and amount format is applied to all no-symbol amounts + in the journal. + + Then each commodity's display style is determined from its commodity + directive. We recommend always declaring commodities with commodity + directives, since they help ensure consistent display styles and preci- + sions, and bring other benefits such as error checking for commodity + symbols. + + But if a commodity directive is not present, hledger infers a commod- + ity's display styles from its amounts as they are written in the jour- + nal (excluding cost amounts and amounts in periodic transaction rules + or auto posting rules). It uses + + o the symbol placement and decimal mark of the first amount seen + + o the digit group marks of the first amount with digit group marks + + o and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a de- + fault style, like $1000.00 (symbol on the left with no space, period as + decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the -c/--commodity-style + command line option. + + Rounding + Amounts are stored internally as decimal numbers with up to 255 decimal + places. They are displayed with their original journal precisions by + print and print-like reports, and rounded to their display precision + (the number of decimal digits specified by the commodity display style) + by other reports. When rounding, hledger uses banker's rounding (it + rounds to the nearest even digit). So eg 0.5 displayed with zero deci- + mal digits appears as "0". + + Costs + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + tion, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, + discussions, or code; that term was directionally neutral and reminded + that it is a price specific to a transaction, but we now just call it + "cost", with the understanding that the transaction could be a purchase + or a sale.) + + Costs are usually written explicitly with @ or @@, but can also be in- + ferred automatically for simple multi-commodity transactions. Note, if + costs are inferred, the order of postings is significant; the first + posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign + currency in hledger, using the cost notation either explicitly or im- + plicitly: + + 1. Write the price per unit, as @ UNITPRICE after the amount: + + 2009/1/1 + assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as @@ TOTALPRICE after the amount: + + 2009/1/1 + assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction. Note the + effect of posting order: the price is added to first posting, making + it 100 @@ $135, as in example 2: + + 2009/1/1 + assets:euros 100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the -B/--cost + flag; this is discussed more in the Cost reporting section. + + Note that the cost normally should be a positive amount, though it's + not required to be. This can be a little confusing, see discussion at + --infer-market-prices: market prices from transactions. + + Other cost/lot notations + A slight digression for Ledger and Beancount users. Ledger has a num- + ber of cost/lot-related notations: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a conversion rate, as in hledger + + o when buying, also creates a lot than can be selected at selling + time + + o (@) UNITCOST and (@@) TOTALCOST (virtual cost) + + o like the above, but also means "this cost was exceptional, don't + use it when inferring market prices". + + Currently, hledger treats the above like @ and @@; the parentheses are + ignored. + + o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) + + o when buying, means "this cost is also the fixed price, don't let it + fluctuate in value reports" + + o {UNITCOST} and {{TOTALCOST}} (lot price) + + o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- + ates a lot + + o when selling, combined with @ ..., specifies an investment lot by + its cost basis; does not check if that lot is present + + o and related: [YYYY/MM/DD] (lot date) + + o when buying, attaches this acquisition date to the lot + + o when selling, selects a lot by its acquisition date + + o (SOME TEXT) (lot note) + + o when buying, attaches this note to the lot + + o when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after + the posting amount, but ignores them. (This can break transaction bal- + ancing.) + + For Beancount users, the notation and behaviour is different: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a cost without creating a lot, as in hledger + + o when buying (augmenting) or selling (reducing) a lot, combined with + {...}: documents the cost/selling price (not used for transaction + balancing) + + o {UNITCOST} and {{TOTALCOST}} + + o when buying (augmenting), expresses the cost for transaction bal- + ancing, and also creates a lot with this cost basis attached + + o when selling (reducing), + + o selects a lot by its cost basis + + o raises an error if that lot is not present or can not be selected + unambiguously (depending on booking method configured) + + o expresses the selling price for transaction balancing + + Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but + ignores it. + + o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- + COST, YYYY-MM-DD, "LABEL"} etc. + + Currently, hledger rejects these. + + 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, described 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 or- + der 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 in- + clude, 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 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 + + Assertions and prices + Balance assertions ignore costs, and should normally be written without + one: + + 2019/1/1 + (a) $1 @ 1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance 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. + + Posting comments + Text following ;, at the end of a posting line, and/or on indented + lines immediately below it, form comments for that posting. They are + reproduced by print but otherwise ignored, except they may contain + tags, which are not ignored. + + 2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + Tags + Tags are a way to add extra labels or labelled data to transactions, + postings, or accounts, which you can then search or pivot on. + + They are written as a word (optionally hyphenated) immediately followed + by a full colon, in a transaction or posting or account directive's + comment. (This is an exception to the usual rule that things in com- + ments are ignored.) Eg, here four different tags are recorded: one on + the checking account, two on the transaction, and one on the expenses + posting: + + account assets:checking ; accounttag: + + 2017/1/16 bought groceries ; transactiontag-1: + ; transactiontag-2: + assets:checking $-1 + expenses:food $1 ; postingtag: + + Postings also inherit tags from their transaction and their account. + And transactions also acquire tags from their postings (and postings' + accounts). So in the example above, the expenses posting effectively + has all four tags (by inheriting from account and transaction), and the + transaction also has all four tags (by acquiring from the expenses + posting). + + You can list tag names with hledger tags [NAMEREGEX], or match by tag + name with a tag:NAMEREGEX query. + + Tag values + Tags can have a value, which is any text after the colon up until a + comma or end of line (with surrounding whitespace removed). Note this + means that hledger tag values can not contain commas. Eg in the fol- + lowing posting, the three tags' values are "value 1", "value 2", and "" + (empty) respectively: + + expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz + + Note that tags can be repeated, and are additive rather than overrid- + ing: when the same tag name is seen again with a new value, the new + name:value pair is added to the tags. (It is not possible to override + a tag's value or remove a tag.) + + You can list a tag's values with hledger tags TAGNAME --values, or + match by tag value with a tag:NAMEREGEX=VALUEREGEX query. + + Directives + Besides transactions, there is something else you can put in a journal + file: directives. These are declarations, beginning with a keyword, + that modify hledger's behaviour. Some directives can have more spe- + cific subdirectives, indented below them. hledger's directives are + similar to Ledger's in many cases, but there are also many differences. + Directives are not required, but can be useful. Here are the main di- + rectives: + + purpose directive + -------------------------------------------------------------------------- + READING DATA: + Rewrite account names alias + Comment out sections of the file comment + Declare file's decimal mark, to help decimal-mark + parse amounts accurately + Include other data files include + GENERATING DATA: + Generate recurring transactions or bud- ~ + get goals + Generate extra postings on existing = + transactions + CHECKING FOR ERRORS: + Define valid entities to provide more account, commodity, payee, tag + error checking + REPORTING: + Declare accounts' type and display order account + Declare commodity display styles commodity + Declare market prices P + + Directives and multiple files + Directives vary in their scope, ie which journal entries and which in- + put files they affect. Most often, a directive will affect the follow- + ing entries and included files if any, until the end of the current + file - and no further. You might find this inconvenient! For example, + alias directives do not affect parent or sibling files. But there are + usually workarounds; for example, put alias directives in your top-most + file, before including other files. + + The restriction, though it may be annoying at first, is in a good + cause; it allows reports to be stable and deterministic, independent of + the order of input. Without it, reports could show different numbers + depending on the order of -f options, or the positions of include di- + rectives in your files. + + Directive effects + Here are all hledger's directives, with their effects and scope sum- + marised - nine main directives, plus four others which we consider non- + essential: + + di- what it does ends + rec- at + tive file + end? + -------------------------------------------------------------------------------------- + ac- Declares an account, for checking all entries in all files; and N + count its display order and type. Subdirectives: any text, ignored. + alias Rewrites account names, in following entries until end of cur- Y + rent file or end aliases. Command line equivalent: --alias + com- Ignores part of the journal file, until end of current file or Y + ment end comment. + com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N + mod- all amounts in all files 2. the decimal mark for parsing + ity amounts of this commodity, in the following entries until end of + current file (if there is no decimal-mark directive) 3. and the + display style for amounts of this commodity 4. which is also + the precision to use for balanced-transaction checking in this + commodity. Takes precedence over D. Subdirectives: format + (Ledger-compatible syntax). Command line equivalent: -c/--com- + modity-style + deci- Declares the decimal mark, for parsing amounts of all commodi- Y + mal- ties in following entries until next decimal-mark or end of cur- + mark rent file. Included files can override. Takes precedence over + commodity and D. + in- Includes entries and directives from another file, as if they N + clude were written inline. Command line alternative: multiple + -f/--file + payee Declares a payee name, for checking all entries in all files. N + P Declares the market price of a commodity on some date, for value N + reports. + ~ Declares a periodic transaction rule that generates future N + (tilde) transactions with --forecast and budget goals with balance + --budget. + Other + syntax: + apply Prepends a common parent account to all account names, in fol- Y + account lowing entries until end of current file or end apply account. + D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no commodity directive for this commodity: its decimal + mark, balancing precision, and display style, as above. + Y Sets a default year to use for any yearless dates, in following Y + entries until end of current file. + = Declares an auto posting rule that generates extra postings on partly + (equals) matched transactions with --auto, in current, parent, and child + files (but not sibling files, see #1212). + Other Other directives from Ledger's file format are accepted but ig- + Ledger nored. + direc- + tives + + account directive + 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 In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + + o They control account display order in reports, allowing non-alpha- + betic sorting (eg Revenues to appear above Expenses). + + o They help with account name completion (in hledger add, hledger-web, + hledger-iadd, ledger-mode, etc.) + + o They can store additional account information as comments, or as tags + which can be used to filter or pivot reports. + + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), affecting reports like balancesheet and + incomestatement. + + They are written as the word account followed by a hledger-style ac- + count name, eg: + + account assets:bank:checking + + Note, however, that accounts declared in account directives are not al- + lowed to have surrounding brackets and parentheses, unlike accounts + used in postings. So the following journal will not parse: + + account (assets:bank:checking) + + Account comments + Text following two or more spaces and ; at the end of an account direc- + tive line, and/or following ; on indented lines immediately below it, + form comments for that account. They are ignored except they may con- + tain tags, which are not ignored. + + The two-space requirement for same-line account comments is because ; + is allowed in account names. + + account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + Account subdirectives + Ledger-style indented subdirectives are also accepted, but currently + ignored: + + account assets:bank:checking + format subdirective is ignored + + Account error checking + By default, accounts need not be declared; they come into existence + when a posting references them. This is convenient, but it means + hledger can't warn you when you mis-spell an account name in the jour- + nal. Usually you'll find that error later, as an extra account in bal- + ance 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 de- + clared 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 ac- + count 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 in- + cluded files of all types. + + o It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + Account display order + The order in which account directives are written influences the order + in which accounts appear in reports, hledger-ui, hledger-web etc. By + default accounts appear in alphabetical order, but if you add these ac- + count directives to the journal file: + + account assets + account liabilities + account equity + account revenues + account expenses + + those accounts will be displayed in declaration order: + + $ hledger accounts -1 + assets + liabilities + equity + revenues + expenses + + Any undeclared accounts are displayed last, in alphabetical order. + + Sorting is done at each level of the account tree, within each group of + sibling accounts under the same parent. And currently, this directive: + + account other:zoo + + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: + + o you will sometimes declare parent accounts (eg account other above) + that you don't intend to post to, just to customize their display or- + der + + o sibling accounts stay together (you couldn't display x:y in between + a:b and a:c). + + 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 (de- + scribed below). But generally we recommend you declare types explic- + itly, by adding a type: tag to your top-level account directives. Sub- + accounts 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 Cost re- + porting).) + + 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. + + 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 ac- + count for all of the account types, 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] + + alias directive + You can define account alias rules which rewrite your account names, or + parts of them, before generating reports. This can be useful for: + + 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 re- + place any occurrence of the old account name with the new one. Subac- + counts 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 ex- + pression.) + + Eg: + + alias /REGEX/ = REPLACEMENT + + or: + + $ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by RE- + PLACEMENT. 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. In- + cluding the aliases doesn't work either: + + include a.aliases + + 2023-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 + + 2023-01-01 ; affected by aliases above + foo 1 + bar + + include c.journal ; also affected + + end aliases directive + 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 ef- + fect. + + 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 + + commodity directive + The commodity directive performs several functions: + + 1. It declares which commodity symbols may be used in the journal, en- + abling useful error checking with strict mode or the check command. + (See Commodity error checking below.) + + 2. It declares the precision with which this commodity's amounts should + be compared when checking for balanced transactions. + + 3. It declares how this commodity's amounts should be displayed, eg + their symbol placement, digit group mark if any, digit group sizes, + decimal mark (period or comma), and the number of decimal places. + (See Commodity display style above.) + + 4. It sets which decimal mark (period or comma) to expect when parsing + subsequent amounts in this commodity (if there is no decimal-mark + directive in effect. See Decimal marks, digit group marks above. + For related dev discussion, see #793.) + + Declaring commodities solves several common parsing/display problems, + so we recommend it. Generally you should put commodity directives at + the top of your journal file (because function 4 is position-sensi- + tive). + + Commodity directive syntax + A commodity directive is normally the word commodity followed by a sam- + ple amount (and optionally a comment). Only the amount's symbol and + format is significant. Eg: + + commodity $1000.00 + commodity 1.000,00 EUR + commodity 1 000 000.0000 ; the no-symbol commodity + + Commodities do not have tags (tags in the comment will be ignored). + + A commodity directive's sample amount must always include a period or + comma decimal mark (this rule helps disambiguate decimal marks and + digit group marks). If you don't want to show any decimal digits, + write the decimal mark at the end: + + commodity 1000. AAAA ; show AAAA with no decimals + + Commodity symbols containing spaces, numbers, or punctuation must be + enclosed in double quotes, as usual: + + commodity 1.0000 "AAAA 2023" + + Commodity directives normally include a sample amount, but can declare + only a symbol (ie, just function 1 above): + + commodity $ + commodity INR + commodity "AAAA 2023" + commodity "" ; the no-symbol commodity + + Commodity directives may also be written with an indented format subdi- + rective, as in Ledger. The symbol is repeated and must be the same in + both places. Other subdirectives are currently ignored: + + ; 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 + an unsupported subdirective ; ignored by hledger + + Commodity error checking + In strict mode (-s/--strict) (or when you run hledger check commodi- + ties), hledger will report an error if an undeclared commodity symbol + is used. (With one exception: zero amounts are always allowed to have + no commodity symbol.) It works like account error checking (described + above). + + decimal-mark directive + You can use a decimal-mark directive - usually one per file, at the top + of the file - to declare which character represents a decimal mark when + parsing amounts in this file. It can look like + + decimal-mark . + + or + + decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we + recommend it, especially if the file contains digit group marks (eg + thousands separators). + + include directive + You can pull in the content of additional files by writing an include + directive, like this: + + include FILEPATH + + Only journal files can include, and only journal, timeclock or timedot + files can be included (not CSV files, currently). + + If the file path does not begin with a slash, it is relative to the + current file's folder. + + A tilde means home directory, eg: include ~/main.journal. + + The path may contain glob patterns to match multiple files, eg: include + *.journal. + + There is limited support for recursive wildcards: **/ (the slash is re- + quired) 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 Data formats): include time- + dot:~/notes/2023*.md. + + P directive + The P directive declares a market price, which is a conversion rate be- + tween two commodities on a certain date. This allows value reports to + convert amounts of one commodity to their value in another, on or after + that date. These prices are often obtained from a stock exchange, + cryptocurrency exchange, the or foreign exchange market. + + The format is: + + P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity + being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) + of commodity 2 that one unit of commodity 1 is worth on this date. Ex- + amples: + + # 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 Value reporting. + + payee directive + payee PAYEE NAME + + This directive can be used to declare a limited set of payees which may + appear in transaction descriptions. The "payees" check will report an + error if any transaction refers to a payee that has not been declared. + Eg: + + payee Whole Foods ; a comment + + Payees do not have tags (tags in the comment will be ignored). + + To declare the empty payee name, use "". + + payee "" + + Ledger-style indented subdirectives, if any, are currently ignored. + + tag directive + tag TAGNAME + + This directive can be used to declare a limited set of tag names al- + lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + + tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is + used. It is quite easy to accidentally create a tag through normal use + of colons in comments(#comments]; if you want to prevent this, you can + declare and check your tags . + + Periodic transactions + The ~ directive declares recurring transactions. Such directives allow + hledger to generate temporary future transactions (visible in reports, + not in the journal file) to help with forecasting or budgeting. + + Periodic transactions can be a little tricky, so before you use them, + read this whole section, or at least these tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast + tag:generated. + + 3. Forecasted transactions will begin only after the last non-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 im- + provement, 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 + 2023/01, which is equivalent to ~ every 10th day of month from + 2023/01/01, will be adjusted to start on 2019/12/10. + + Periodic rule syntax + A periodic transaction rule looks like a normal journal entry, with the + date replaced by a tilde (~) followed by a period expression (mnemonic: + ~ looks like a recurring sine wave.): + + # every first of month + ~ monthly + expenses:rent $2000 + assets:bank:checking + + # every 15th of month in 2023's first quarter: + ~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying multi-pe- + riod reports, just interpreted differently; there, it specifies report + periods; here it specifies recurrence dates (the periods' start dates). + + 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 re- + sults 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 2023" + ; || + ; vv + ~ every 2 months in 2023, 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 ex- + pression. + + Auto postings + The = directive declares a rule for generating temporary extra postings + on transactions. Wherever the rule matches an existing posting, it can + add one or more companion postings below that one, optionally influ- + enced by the matched posting's amount. This can be useful for generat- + ing tax postings with a standard percentage, for example. + + Note that depending on generated data is not ideal for financial + records (it's less portable, less future-proof, less auditable by oth- + ers, and less robust, since other features like balance assertions will + depend on using or not using --auto). + + 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". + + Auto postings on forecast transactions only + Tip: you can can make auto postings that will apply to forecast trans- + actions but not recorded transactions, by adding tag:_generated-trans- + action to their QUERY. This can be useful when generating new journal + entries to be saved in the journal. + + Other syntax + hledger journal format supports quite a few other features, mainly to + make interoperating with or converting from Ledger easier. Note some + of the features below are powerful and can be useful in special cases, + but in general, features in this section are considered less important + or even not recommended for most users. Downsides are mentioned to + help you decide if you want to use them. + + 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). + + Downsides: using balance assignments makes your journal less explicit; + to know the exact amount posted, you have to run hledger or do the cal- + culations yourself, instead of just reading it. Also balance assign- + ments' forcing of balances can hide errors. These things make your fi- + nancial data less portable, less future-proof, and less trustworthy in + an audit. + + Balance assignments and prices + A cost in a balance assignment will cause the calculated amount to have + that price attached: + + 2019/1/1 + (a) = $1 @ 2 + + $ hledger print --explicit + 2019-01-01 + (a) $1 @ 2 = $1 @ 2 + + Balance assignments and multiple files + Balance assignments handle multiple files like balance assertions. + They see balance from other files previously included from the current + file, but not from previous sibling or parent files. + + Bracketed posting dates + For setting posting dates and secondary posting dates, Ledger's brack- + eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in + posting comments. hledger will attempt to parse any square-bracketed + sequence of the 0123456789/-.= characters in this way. With this syn- + tax, DATE infers its year from the transaction and DATE2 infers its + year from DATE. + + Downsides: another syntax to learn, redundant with hledger's + date:/date2: tags, and confusingly similar to Ledger's lot date syntax. + + D directive + D AMOUNT + + This directive sets a default commodity, to be used for any subsequent + commodityless amounts (ie, plain numbers) seen while parsing the 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 di- + rective (setting the commodity's decimal mark for parsing and display + style for output). So its argument is not just a commodity symbol, but + a full amount demonstrating the style. The amount must include a deci- + mal mark (either period or comma). Eg: + + ; commodity-less amounts should be treated as dollars + ; (and displayed with the dollar sign on the left, thousands separators and two decimal places) + D $1,000.00 + + 1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity's display style, a commodity directive has + highest priority, then a D directive. + + For detecting a commodity's decimal mark during parsing, decimal-mark + has highest priority, then commodity, then D. + + For checking commodity symbols with the check command, a commodity di- + rective is required (hledger check commodities ignores D directives). + + Downsides: omitting commodity symbols makes your financial data less + explicit, less portable, and less trustworthy in an audit. It is usu- + ally an unsustainable shortcut; sooner or later you will want to track + multiple commodities. D is overloaded with functions redundant with + commodity and decimal-mark. And it works differently from Ledger's D. + + apply account directive + This directive sets a default parent account, which will be prepended + to all accounts in following entries, until an end apply account direc- + tive or end of current file. Eg: + + apply account home + + 2010/1/1 + food $10 + cash + + end apply account + + is equivalent to: + + 2010/01/01 + home:food $10 + home:cash $-10 + + account directives are also affected, and so is any included content. + + Account names entered via hledger add or hledger-web are not affected. + + Account aliases, if any, are applied after the parent account is + prepended. + + Downsides: this can make your financial data less explicit, less + portable, and less trustworthy in an audit. + + Y directive + Y YEAR + + or (deprecated backward-compatible forms): + + year YEAR apply year YEAR + + The space is optional. This sets a default year to be used for subse- + quent dates which don't specify a year. Eg: + + Y2009 ; set default year to 2009 + + 12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + + year 2010 ; change default year to 2010 + + 2009/1/30 ; specifies the year, not affected + expenses 1 + assets + + 1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at least) + makes your financial data less explicit, less portable, and less trust- + worthy in an audit. Such dates can get separated from their corre- + sponding Y directive, eg when evaluating a region of the journal in + your editor. A missing Y directive makes reports dependent on today's + date. + + Secondary dates + A secondary date is written after the primary date, following an equals + sign. If the year is omitted, the primary date's year is assumed. + When running reports, the primary (left) date is used by default, but + with the --date2 flag (or --aux-date or --effective), the secondary + (right) date will be used instead. + + The meaning of secondary dates is up to you, but it's best to follow a + consistent rule. Eg "primary = the bank's clearing date, secondary = + date the transaction was initiated, if different". + + Downsides: makes your financial data more complicated, less portable, + and less trustworthy in an audit. Keeping the meaning of the two dates + consistent requires discipline, and you have to remember which report- + ing mode is appropriate for a given report. Posting dates are simpler + and better. + + Star comments + Lines beginning with * (star/asterisk) are also comment lines. This + feature allows Emacs users to insert org headings in their journal, al- + lowing them to fold/unfold/navigate it like an outline when viewed with + org mode. + + Downsides: another, unconventional comment syntax to learn. Decreases + your journal's portability. And switching to Emacs org mode just for + folding/unfolding meant losing the benefits of ledger mode; nowadays + you can add outshine mode to ledger mode to get folding without losing + ledger mode's features. + + Valuation expressions + Ledger allows a valuation function or value to be written in double + parentheses after an amount. hledger ignores these. + + Virtual postings + A posting with parentheses around the account name ((some:account)) is + called a unbalanced virtual posting. Such postings do not participate + in transaction balancing. (And if you write them without an amount, a + zero amount is always inferred.) These can occasionally be convenient + for special circumstances, but they violate double entry bookkeeping + and make your data less portable across applications, so many people + avoid using them at all. + + A posting with brackets around the account name ([some:account]) is + called a balanced virtual posting. The balanced virtual postings in a + transaction must add up to zero, just like ordinary postings, but sepa- + rately from them. These are not part of double entry bookkeeping ei- + ther, but they are at least balanced. An example: + + 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Ordinary postings, whose account names are neither parenthesised nor + bracketed, are called real postings. You can exclude virtual postings + from reports with the -R/--real flag or a real:1 query. + + Other Ledger directives + These other Ledger directives are currently accepted but ignored. This + allows hledger to read more Ledger files, but be aware that hledger's + reports may differ from Ledger's if you use these. + + apply fixed COMM AMT + apply tag TAG + assert EXPR + bucket / A ACCT + capture ACCT REGEX + check EXPR + define VAR=EXPR + end apply fixed + end apply tag + end apply year + end tag + eval / expr EXPR + python + PYTHONCODE + tag NAME + value EXPR + --command-line-flags + + See also https://hledger.org/ledger.html for a detailed hledger/Ledger + syntax comparison. + +CSV + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records, automatically converting + each record into a transaction. + + (To learn about writing CSV, see CSV output.) + + For best error messages when reading CSV/TSV/SSV files, make sure they + have a corresponding .csv, .tsv or .ssv file extension or use a hledger + file prefix (see File Extension below). + + Each CSV file must be described by a corresponding rules file. + This contains rules describing the CSV data (header line, fields lay- + out, date format etc.), how to construct hledger transactions from it, + and how to categorise transactions based on description or other at- + tributes. + + By default hledger looks for a rules file named like the CSV file with + an extra .rules extension, in the same directory. Eg when asked to + read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec- + ify a different rules file with the --rules-file option. If no rules + file is found, hledger will create a sample rules file, which you'll + need to adjust. + + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines + there are. Here's a simple CSV file and a rules file for it: + + Date, Description, Id, Amount + 12/11/2019, Foo, 123, 10.23 + + # basic.csv.rules + skip 1 + fields date, description, , amount + date-format %d/%m/%Y + + $ hledger print -f basic.csv + 2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There's an introductory Importing CSV data tutorial on hledger.org, and + more CSV rules examples below, and a larger collection at + https://github.com/simonmichael/hledger/tree/master/examples/csv. + + CSV rules cheatsheet + The following kinds of rule can appear in the rules file, in any order. + (Blank lines and lines beginning with # or ; or * are ignored.) + + source optionally declare which file to read data + from + separator declare the field separator, instead of rely- + ing on file extension + skip skip one or more header lines at start of file + date-format declare how to parse CSV dates/date-times + timezone declare the time zone of ambiguous CSV date- + times + newest-first improve txn order when: there are multiple + records, newest first, all with the same date + intra-day-reversed improve txn order when: same-day txns are in + opposite order to the overall file + decimal-mark declare the decimal mark used in CSV amounts, + when ambiguous + fields list name CSV fields for easy reference, and op- + tionally assign their values to hledger fields + Field assignment assign a CSV value or interpolated text value + to a hledger field + if block conditionally assign values to hledger fields, + or skip a record or end (skip rest of file) + if table conditionally assign values to hledger fields, + using compact syntax + balance-type select which type of balance assertions/as- + signments to generate + include inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are + evaluated. + + source + If you tell hledger to read a csv file with -f foo.csv, it will look + for rules in foo.csv.rules. Or, you can tell it to read the rules + file, with -f foo.csv.rules, and it will look for data in foo.csv + (since 1.30). + + These are mostly equivalent, but the second method provides some extra + features. For one, the data file can be missing, without causing an + error; it is just considered empty. And, you can specify a different + data file by adding a "source" rule: + + source ./Checking1.csv + + If you specify just a file name with no path, hledger will look for it + in your system's downloads directory (~/Downloads, currently): + + source Checking1.csv + + And if you specify a glob pattern, hledger will read the most recent of + the matched files (useful with repeated downloads): + + source Checking1*.csv + + See also "Working with CSV > Reading files specified by rule". + + 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. + + skip + skip N + + The word skip followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines at the start of the input + data. You'll need this whenever your CSV data contains header lines. + Note, empty and blank lines are skipped automatically, so you don't + need to count those. + + skip has a second meaning: it can be used inside if blocks (described + below), to skip one or more records whenever the condition is true. + Records skipped in this way are ignored, except they are still required + to be valid CSV. + + date-format + date-format DATEFMT + + This is a helper for the date (and date2) fields. If your CSV dates + are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll + need to add a date-format rule describing them with a strptime-style + date parsing pattern - see https://hackage.haskell.org/pack- + age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must + parse the CSV date value completely. Some examples: + + # MM/DD/YY + date-format %m/%d/%y + + # D/M/YYYY + # The - makes leading zeros optional. + date-format %-d/%-m/%Y + + # YYYY-Mmm-DD + date-format %Y-%h-%d + + # M/D/YYYY HH:MM AM some other junk + # Note the time and junk must be fully parsed, though only the date is used. + date-format %-m/%-d/%Y %l:%M %p some other junk + + timezone + timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone + other than yours, but containing no explicit time zone information, you + can use this rule to declare the CSV's native time zone, which helps + prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don't + need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see + the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware conversion, + localising the CSV date-times to your current system time zone. If you + prefer to localise to some other time zone, eg for reproducibility, you + can (on unix at least) set the output timezone with the TZ environment + variable, eg: + + $ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + timezone currently does not understand timezone names, except "UTC", + "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For + others, use numeric format: +HHMM or -HHMM. + + newest-first + hledger tries to ensure that the generated transactions will be ordered + chronologically, including same-day transactions. Usually it can auto- + detect how the CSV records are ordered. But if it encounters CSV where + all records are on the same date, it assumes that the records are old- + est first. If in fact the CSV's records are normally newest first, + like: + + 2022-10-01, txn 3... + 2022-10-01, txn 2... + 2022-10-01, txn 1... + + you can add the newest-first rule to help hledger generate the transac- + tions in correct order. + + # same-day CSV records are newest first + newest-first + + intra-day-reversed + If CSV records within a single day are ordered opposite to the overall + record order, you can add the intra-day-reversed rule to improve the + order of journal entries. Eg, here the overall record order is newest + first, but same-day records are oldest first: + + 2022-10-02, txn 3... + 2022-10-02, txn 4... + 2022-10-01, txn 1... + 2022-10-01, txn 2... + + # transactions within each day are reversed with respect to the overall date order + intra-day-reversed + + 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. + + fields list + fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word fields followed by comma-separated field names) + is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say %SomeField + instead of remembering %13. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and + build a transaction. + + Here's an example that says "use the 1st, 2nd and 4th fields as the + transaction's date, description and amount; name the last two fields + for later reference; and ignore the others": + + fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to the + CSV file's separator. Also: + + o 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 Fields you don't care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it's convenient to use these for + your field names, suitably modified (eg lower-cased with spaces re- + placed by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning to + a hledger field with the same name. Eg you could call the CSV's "bal- + ance" field balance_ to avoid directly setting hledger's balance field + (and generating a balance assertion). + + Field assignment + HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to + hledger fields. They can be used instead of or in addition to a fields + list (see above). + + To assign a value to a hledger field, write the field name (any of the + standard hledger field/pseudo-field names, defined below), a space, + followed by a text value on the same line. This text value may inter- + polate CSV fields, referenced either by their 1-based position in the + CSV record (%N) or by the name they were given in the fields list + (%CSVFIELD), and regular expression match groups (\N). + + 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 " be- + comes 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 + Note the two kinds of field names mentioned here, and used only in + hledger CSV rules files: + + 1. CSV field names (CSVFIELD in these docs): you can optionally name + the CSV columns for easy reference (since hledger doesn't yet auto- + matically recognise column headings in a CSV file), by writing arbi- + trary names in a fields list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special hledger field names (HLEDGERFIELD in these docs): you must + set at least some of these to generate the hledger transaction from + a CSV record, by writing them as the left hand side of a field as- + signment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a fields list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what hap- + pens when you assign values to them: + + 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. + + 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. + + account field + Assigning to accountN, where N is 1 to 99, sets the account name of the + Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you'll want to set account1 and + account2. Typically account1 is associated with the CSV file, and is + set once with a top-level assignment, while account2 is set based on + each transaction's description, in conditional rules. + + If a posting's account name is left unset but its amount is set (see + below), a default account name will be chosen (like "expenses:unknown" + or "income:unknown"). + + amount field + There are several ways to set posting amounts from CSV, useful in dif- + ferent situations. + + 1. amount is the oldest and simplest. Assigning to this sets the + amount of the first and second postings. In the second posting, the + amount will be negated; also, if it has a cost attached, it will be + converted to cost. + + 2. amount-in and amount-out work exactly like the above, but should be + used when the CSV has two amount fields (such as "Debit" and + "Credit", or "Inflow" and "Outflow"). Whichever field has a non- + zero value will be used as the amount of the first and second post- + ings. Here are some tips to avoid confusion: + + o It's not "amount-in for posting 1 and amount-out for posting 2", + it is "extract a single amount from the amount-in or amount-out + field, and use that for posting 1 and (negated) for posting 2". + + o Don't use both amount and amount-in/amount-out in the same rules + file; choose based on whether the amount is in a single CSV field + or spread across two fields. + + o In each record, at most one of the two CSV fields should contain + a non-zero amount; the other field must contain a zero or noth- + ing. + + o hledger assumes both CSV fields contain unsigned numbers, and it + automatically negates the amount-out values. + + o If the data doesn't fit these requirements, you'll probably need + an if rule (see below). + + 3. amountN (where N is a number from 1 to 99) sets the amount of only a + single posting: the Nth posting in the transaction. You'll usually + need at least two such assignments to make a balanced transaction. + You can also generate more than two postings, to represent more com- + plex transactions. The posting numbers don't have to be consecu- + tive; with if rules, higher posting numbers can be useful to ensure + a certain order of postings. + + 4. amountN-in and amountN-out work exactly like the above, but should + be used when the CSV has two amount fields. This is analogous to + amount-in and amount-out, and those tips also apply here. + + 5. Remember that a fields list can also do assignments. So in a fields + list if you name a CSV field "amount", that counts as assigning to + amount. (If you don't want that, call it something else in the + fields list, like "amount_".) + + 6. The above don't handle every situation; if you need more flexibil- + ity, use an if rule to set amounts conditionally. See "Working with + CSV > Setting amounts" below for more on this and on amount-setting + generally. + + 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. + + if block + Rules can be applied conditionally, depending on patterns in the CSV + data. This allows flexibility; in particular, it is how you can cate- + gorise transactions, selecting an appropriate account name based on + their description (for example). There are two ways to write condi- + tional rules: "if blocks", described here, and "if tables", described + below. + + An if block is the word if and one or more "matcher" expressions (can + be a word or phrase), one per line, starting either on the same or next + line; followed by one or more indented rules. Eg, + + if MATCHER + RULE + + or + + if + MATCHER + MATCHER + MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be ap- + plied. They are usually field assignments, but the following special + rules may also be used within an if block: + + o skip - skips the matched CSV record (generating no transaction from + it) + + o end - skips the rest of the current CSV file. + + Some examples: + + # if the record contains "groceries", set account2 to "expenses:groceries" + if groceries + account2 expenses:groceries + + # if the record contains any of these phrases, set account2 and a transaction comment as shown + if + monthly service fee + atm transaction fee + banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + # if an empty record is seen (assuming five fields), ignore the rest of the CSV file + if ,,,, + end + + Matchers + There are two kinds: + + 1. A record matcher is a word or single-line text fragment or regular + expression (REGEX), which hledger will try to match case-insensi- + tively anywhere within the CSV record. + Eg: whole foods + + 2. A field matcher is preceded with a percent sign and CSV field name + (%CSVFIELD REGEX). hledger will try to match these just within the + named CSV field. + Eg: %date 2023 + + The regular expression is (as usual in hledger) a POSIX extended regu- + lar expression, that also supports GNU word boundaries (\b, \B, \<, + \>), and nothing else. If you have trouble, see "Regular expressions" + in the hledger manual (https://hledger.org/hledger.html#regular-expres- + sions). + + What matchers match + With record matchers, it's important to know that the record matched is + not the original CSV record, but a modified one: separators will be + converted to commas, and enclosing double quotes (but not enclosing + whitespace) are removed. So for example, when reading an SSV file, if + the original record was: + + 2023-01-01; "Acme, Inc."; 1,000 + + the regex would see, and try to match, this modified record text: + + 2023-01-01,Acme, Inc., 1,000 + + Combining matchers + When an if block has multiple matchers, they are combined as follows: + + o By default they are OR'd (any one of them can match) + + o When a matcher is preceded by ampersand (&) it will be AND'ed with + the previous matcher (both of them must match) + + o When a matcher is preceded by an exclamation mark (!), the matcher is + negated (it may not match). + + Currently there is a limitation: you can't use both & and ! on the same + line (you can't AND a negated matcher). + + Match groups + Matchers can define match groups: parenthesised portions of the regular + expression which are available for reference in field assignments. + Groups are enclosed in regular parentheses (( and )) and can be nested. + Each group is available in field assignments using the token \N, where + N is an index into the match groups for this conditional block (e.g. + \1, \2, etc.). + + Example: Warp credit card payment postings to the beginning of the + billing period (Month start), to match how they are presented in state- + ments, using posting dates: + + if %date (....-..)-.. + comment2 date:\1-01 + + Another example: Read the expense account from the CSV field, but throw + away a prefix: + + if %account1 liabilities:family:(expenses:.*) + account1 \1 + + if table + "if tables" are an alternative to if blocks; they can express many + matchers and field assignments in a more compact tabular format, like + this: + + if,HLEDGERFIELD1,HLEDGERFIELD2,... + MATCHERA,VALUE1,VALUE2,... + MATCHERB,VALUE1,VALUE2,... + MATCHERC,VALUE1,VALUE2,... + + + The first character after if is taken to be this if table's field sepa- + rator. It is unrelated to the separator used in the CSV file. It + should be a non-alphanumeric character like , or | that does not appear + anywhere else in the table (it should not be used in field names or + matchers or values, and it cannot be escaped with a backslash). + + Each line must contain the same number of separators; empty values are + allowed. Whitespace can be used in the matcher lines for readability + (but not in the if line, currently). The table must be terminated by + an empty line (or end of file). + + An if table like the above is interpreted as follows: try all of the + matchers; whenever a matcher succeeds, assign all of the values on that + line to the corresponding hledger fields; later lines can overrider + earlier ones. It is equivalent to this sequence of if blocks: + + if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + if MATCHERB + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + if MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + + if,account2,comment + atm transaction fee,expenses:business:banking,deductible? check it + %description groceries,expenses:groceries, + 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + 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 + + 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 + + Working with CSV + Some 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 + Note that hledger will only accept valid CSV conforming to RFC 4180, + and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or + tab as separators). This means, eg: + + o Values may be enclosed in double quotes, or not. Enclosing in single + quotes is not allowed. (Eg 'A','B' is rejected.) + + o When values are enclosed in double quotes, spaces outside the quotes + are not allowed. (Eg "A", "B" is rejected.) + + o When values are not enclosed in quotes, they may not contain double + quotes. (Eg A"A, B is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- + form it before reading with hledger. Try using sed, or a more permis- + sive CSV parser like python's csv lib. + + File Extension + To help hledger choose the CSV file reader and show the right error + messages (and choose the right field separator character by default), + it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv + filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV + reader (and the default field separator) by prefixing the file path + with csv:, ssv: or tsv:: Eg: + + $ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator rule + if needed. + + Reading CSV from standard input + You'll need the file format prefix when reading CSV from stdin also, + since hledger assumes journal format by default. Eg: + + $ cat foo.dat | hledger -f ssv:- print + + 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. + + Reading files specified by rule + Instead of specifying a CSV file in the command line, you can specify a + rules file, as in hledger -f foo.csv.rules CMD. By default this will + read data from foo.csv in the same directory, but you can add a source + rule to specify a different data file, perhaps located in your web + browser's download directory. + + This feature was added in hledger 1.30, so you won't see it in most CSV + rules examples. But it helps remove some of the busywork of managing + CSV downloads. Most of your financial institutions's default CSV file- + names are different and can be recognised by a glob pattern. So you + can put a rule like source Checking1*.csv in foo-checking.csv.rules, + and then periodically follow a workflow like: + + 1. Download CSV from Foo's website, using your browser's defaults + + 2. Run hledger import foo-checking.csv.rules to import any new transac- + tions + + After import, you can: discard the CSV, or leave it where it is for a + while, or move it into your archives, as you prefer. If you do noth- + ing, next time your browser will save something like Checking1-2.csv, + and hledger will use that because of the * wild card and because it is + the most recent. + + 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 as- + sertions 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 + Continuing from amount field above, here are more tips for amount-set- + ting: + + 1. If the amount is in a single CSV field: + a. If its sign indicates direction of flow: + Assign it to amountN, to set the Nth posting's amount. N is usu- + ally 1 or 2 but can go up to 99. + + b. If another field indicates direction of flow: + Use one or more conditional rules to set the appropriate amount + sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. If the amount is in two CSV fields (such as Debit and Credit, or In + and Out): + a. If both fields are unsigned: + Assign one field to amountN-in and the other to amountN-out. + hledger will automatically negate the "out" field, and will use + whichever field value is non-zero as posting N's amount. + + b. If either field is signed: + You will probably need to override hledger's sign for one or the + other field, as in the following example: + + # Negate the -out value, but only if it is not empty: + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. If both fields can contain a non-zero value (or both can be + empty): + The -in/-out rules normally choose the value which is non-zero/non- + empty. Some value pairs can be ambiguous, such as 1 and none. For + such cases, use conditional rules to help select the amount. Eg, + to handle the above you could select the value containing non-zero + digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. If you want posting 2's amount converted to cost: + Use the unnumbered amount (or amount-in and amount-out) syntax. + + 4. If the CSV has only balance amounts, not transaction amounts: + Assign to balanceN, to set a balance assignment on the Nth posting, + causing the posting's amount to be calculated automatically. balance + with no number is equivalent to balance1. In this situation hledger is + more likely to guess the wrong default account name, so you may need to + set that explicitly. + + Amount signs + There is some special handling making it easier to parse and to reverse + amount signs. (This only works for whole amounts, not for cost amounts + such as COST in amount1 AMT @ COST): + + 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 + "". + + It's not possible (without preprocessing the CSV) to set an amount to + its absolute value, ie discard its sign. + + Setting currency/commodity + If the currency/commodity symbol is included in the CSV's amount + field(s): + + 2023-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 + + 2023-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + + 2023-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 + + 2023-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 + + 2023-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 re- + peated, 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 re- + maining 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 as- + signed to it (and interpolate the %CSVFIELD references), or a default + + o generate a hledger transaction (journal entry) from these values. + + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the + user specified. + + Well factored rules + Some things than can help reduce duplication and complexity in rules + files: + + o Extracting common rules usable with multiple CSV files into a com- + mon.rules, and adding include common.rules to each CSV's rules file. + + o Splitting if blocks into smaller if blocks, extracting the frequently + used parts. + + CSV rules examples + 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. + + Coinbase + A simple example with some CSV from Coinbase. The spot price is + recorded using cost notation. The legacy amount field name conve- + niently sets amount 2 (posting 2's amount) to the total cost. + + # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes + # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + + # coinbase.csv.rules + skip 1 + fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes + date %Timestamp + date-format %Y-%m-%dT%T%Z + description %Notes + account1 assets:coinbase:cc + amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + + $ hledger print -f coinbase.csv + 2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + 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: + +Timeclock + The time logging format of timeclock.el, as read by hledger. + + hledger can read time logs in timeclock format. As with Ledger, these + are (a subset of) timeclock.el's format, containing clock-in and clock- + out entries as in the example below. The date is a simple date. The + time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. + The timezone, if present, must be four digits and is ignored (currently + the time is always interpreted as a local time). Lines beginning with + # or ; or *, and blank lines, are ignored. + + i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: + 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 2 spaces ; optional comment, tags: + (some account) 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 + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is more convenient for quick, approxi- + mate, and retroactive time logging, and more human-readable (you can + see at a glance where time was spent). A quick example: + + 2023-05-01 + hom:errands .... .... ; two hours; the space is ignored + fos:hledger:timedot .. ; half an hour + per:admin:finance ; no time spent yet + + hledger reads this as a transaction on this day with three (unbalanced) + postings, where each dot represents "0.25". No commodity symbol is as- + sumed, but we typically interpret it as hours. + + $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required + 2023-05-01 * + (hom:errands) 2.00 ; two hours + (fos:hledger:timedot) 0.50 ; half an hour + (per:admin:finance) 0 + + A timedot file contains a series of transactions (usually one per day). + Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be + followed on the same line by a transaction description, and/or a trans- + action comment following a semicolon. + + After the date line are zero or more time postings, consisting of: + + o An account name - any hledger-style account name, optionally in- + dented. + + o Two or more spaces - required if there is an amount (as in journal + format). + + o A timedot amount, which can be + + o empty (representing zero) + + o a number, optionally followed by a unit s, m, h, d, w, mo, or y, + representing a precise number of seconds, minutes, hours, days + weeks, months or years (hours is assumed by default), which will be + converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = + 1w, 30d = 1mo, 365d = 1y. + + o one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can be + used for grouping/alignment. + + o one or more letters. These are like dots but they also generate a + tag t: (short for "type") with the letter as its value, and a sepa- + rate posting for each of the values. This provides a second dimen- + sion of categorisation, viewable in reports with --pivot t. + + o An optional comment following a semicolon (a hledger-style posting + comment). + + There is some flexibility to help with keeping time log data and notes + in the same file: + + o Blank lines and lines beginning with # or ; are ignored. + + o After the first date line, lines which do not contain a double space + are parsed as postings with zero amount. (hledger's register reports + will show these if you add -E). + + o Before the first date line, lines beginning with * (eg org headings) + are ignored. And from the first date line onward, Emacs org mode + heading prefixes at the start of lines (one or more *'s followed by a + space) will be ignored. This means the time log can also be a org + outline. + + Timedot examples + Numbers: + + 2016/2/3 + inc:client1 4 + fos:hledger 3h + biz:research 60m + + Dots: + + # 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 . + + $ 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 + + Letters: + + # Activity types: + # c cleanup/catchup/repair + # e enhancement + # s support + # l learning/research + + 2023-11-01 + work:adm ccecces + + $ hledger -f a.timedot print + 2023-11-01 + (work:adm) 1 ; t:c + (work:adm) 0.5 ; t:e + (work:adm) 0.25 ; t:s + + $ hledger -f a.timedot bal + 1.75 work:adm + -------------------- + 1.75 + + $ hledger -f a.timedot bal --pivot t + 1.00 c + 0.50 e + 0.25 s + -------------------- + 1.75 + + Org: + + * 2023 Work Diary + ** Q1 + *** 2023-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 + + Using . as account name separator: + + 2016/2/4 + fos.hledger.timedot 4h + fos.ledger .. + + $ hledger -f a.timedot --alias '/\./=:' bal -t + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger + -------------------- + 4.50 + +PART 3: REPORTING CONCEPTS +Amount formatting, parseability + If you're wondering why your print report sometimes shows trailing dec- + imal marks, with no decimal digits; it does this when showing amounts + that have digit group marks but no decimal digits, to disambiguate them + and allow them to be re-parsed reliably (see also Decimal marks, digit + group marks. Eg: + + commodity $1,000.00 + + 2023-01-02 + (a) $1000 + + $ hledger print + 2023-01-02 + (a) $1,000. + + If this is a problem (eg when exporting to Ledger), you can avoid it by + disabling digit group marks, eg with -c/--commodity (for each affected + commodity): + + $ hledger print -c '$1000.00' + 2023-01-02 + (a) $1000 + + or by forcing print to always show decimal digits, with --round: + + $ hledger print -c '$1,000.00' --round=soft + 2023-01-02 + (a) $1,000.00 + + More generally: hledger output falls into three rough categories, which + format amounts a little bit differently to suit different consumers: + + 1. "hledger-readable output" - should be readable by hledger (and by + humans) + + o This is produced by reports that show full journal entries: print, + import, close, rewrite etc. + + o It shows amounts with their original journal precisions, which may + not be consistent. + + o It adds a trailing decimal mark when needed to avoid showing ambigu- + ous amounts. + + o It can be parsed reliably (by hledger and ledger2beancount at least, + but perhaps not by Ledger..) + + 2. "human-readable output" - usually for humans + + o This is produced by all other reports. + + o It shows amounts with standard display precisions, which will be con- + sistent within each commodity. + + o It shows ambiguous amounts unmodified. + + o It can be parsed reliably in the context of a known report (when you + know decimals are consistently not being shown, you can assume a sin- + gle mark is a digit group mark). + + 3. "machine-readable output" - usually for other software + + o This is produced by all reports when an output format like csv, tsv, + json, or sql is selected. + + o It shows amounts as 1 or 2 do, but without digit group marks. + + o It can be parsed reliably (if needed, the decimal mark can be changed + with -c/--commodity-style). + +Time periods + Report start & end date + By default, most hledger reports will show the full span of time repre- + sented by the journal. The report start date will be the earliest + transaction or posting date, and the report end date will be the latest + transaction, posting, or market price date. + + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, + -e/--end, -p/--period or a date: query (described below). All of these + accept the smart date syntax (below). + + Some notes: + + 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 In some cases a report interval will adjust start/end dates to fall + on interval boundaries (see below). + + 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 re- + placed with -) + date:..12/1 + date:thismonth.. + date:thismonth + + Smart dates + hledger's user interfaces accept a "smart date" syntax for added conve- + nience. Smart dates optionally can be relative to today's date, be + written with english words, and have less-significant parts omitted + (missing parts are inferred as 1). Some examples: + + 2004/10/1, 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 + + Some counterexamples - malformed digit sequences might give surprising + results: + + 201813 6 digits with an invalid month is parsed as start of + 6-digit year + 20181301 8 digits with an invalid month is parsed as start of + 8-digit year + 20181232 8 digits with an invalid day gives an error + 201801012 9+ digits beginning with a valid YYYYMMDD gives an error + + "Today's date" can be overridden with the --today option, in case it's + needed for testing or for recreating old reports. (Except for periodic + transaction rules, which are not affected by --today.) + + Report intervals + A report interval can be specified so that reports like register, bal- + ance or activity become multi-period, showing each subperiod as a sepa- + rate row or column. + + The following standard intervals can be enabled with command-line + flags: + + o -D/--daily + + o -W/--weekly + + o -M/--monthly + + o -Q/--quarterly + + o -Y/--yearly + + More complex intervals can be specified using -p/--period, described + below. + + Date adjustment + When there is a report interval (other than daily), report start/end + dates which have been inferred, eg from the journal, are automatically + adjusted to natural period boundaries. This is convenient for produc- + ing simple periodic reports. More precisely: + + o an inferred start date will be adjusted earlier if needed to fall on + a natural period boundary + + o an inferred end date will be adjusted later if needed to make the + last period the same length as the others. + + By contrast, start/end dates which have been specified explicitly, with + -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This + makes it possible to specify non-standard report periods, but it also + means that if you are specifying a start date, you should pick one + that's on a period boundary if you want to see simple report period + headings. + + Period expressions + The -p/--period option specifies a period expression, which is a com- + pact way of expressing a start date, end date, and/or report interval. + + Here's a period expression with a start and end date (specifying the + first quarter of 2009): + + -p "from 2009/1/1 to 2009/4/1" + + Several keywords like "from" and "to" are supported for readability; + these are optional. "to" can also be written as ".." or "-". The + spaces are also optional, as long as you don't run two dates together. + So the following are equivalent to the above: + + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1..2009/4/1 + + Dates are smart dates, so if the current year is 2009, these are also + equivalent to the above: + + -p "1/1 4/1" + -p "jan-apr" + -p "this year to 4/1" + + If you specify only one date, the missing start or end date will be the + earliest or latest transaction date in the journal: + + -p "from 2009/1/1" everything after january + 1, 2009 + -p "since 2009/1" the same, since is a syn- + onym + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 + + You can also specify a period by writing a single partial or full date: + + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to + 2009/1/2" + + or by using the "Q" quarter-year syntax (case insensitive): + + -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to + 2009/4/1" + -p "q4" fourth quarter of the current year + + Period expressions with a report interval + A period expression can also begin with a report interval, separated + from the start/end dates (if any) by a space or the word in: + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "quarterly" + + More complex report intervals + Some more complex intervals can be specified within period expressions, + such as: + + o biweekly (every two weeks) + + o fortnightly + + o bimonthly (every two months) + + o every day|week|month|quarter|year + + o every N days|weeks|months|quarters|years + + Weekly on a 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 a custom day: + + o every Nth day [of month] + + o every Nth WEEKDAYNAME [of month] + + Yearly on a 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 "bimonthly from 2008" + -p "every 2 weeks" + -p "every 5 months from + 2009/03" + -p "every 2nd day of week" periods will go from Tue to Tue + -p "every Tue" same + -p "every 15th day" period boundaries will be on 15th of each + month + -p "every 2nd Monday" period boundaries will be on second Monday + of each month + -p "every 11/05" yearly periods with boundaries on 5th of + 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" + + Multiple weekday intervals + This special form is also supported: + + o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- + day names, case insensitive) + + Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and + sat,sun. + + This is mainly intended for use with --forecast, to generate periodic + transactions on arbitrary days of the week. It may be less useful with + -p, since it divides each week into subperiods of unequal length, which + is unusual. (Related: #1632) + + Examples: + + -p "every dates will be Mon, Wed, Fri; periods will be Mon- + 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), reports will show ac- + counts only to the specified depth, hiding deeper subaccounts. Use + this when you want a summary with less detail. This flag has the same + effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- + lent. + +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 ac- + count 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:202312- + status: + desc:amazon + cur:USD + "amt:>0" + + o Add a not: prefix to negate: + + not:cur:USD + + o Multiple unlike terms are AND-ed, multiple like terms are OR-ed + + date:2022 desc:amazon desc:amzn + (all transactions with "amazon" or "amzn" in description during 2022) + + 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 es- + caping. 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 in- + terval. 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. + + expr:"TERM AND NOT (TERM OR TERM)" (eg) + Match with a boolean combination of queries (which must be enclosed in + quotes). See Combining query terms below. + + 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 + When given multiple space-separated 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. + + The print command is a little different, showing 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. + + We also support more complex boolean queries with the 'expr:' prefix. + This allows one to combine queries using one of three operators: AND, + OR, and NOT, where NOT is different syntax for 'not:'. + + Examples of such queries are: + + o Match transactions with 'cool' in the description AND with the 'A' + tag + + expr:"desc:cool AND tag:A" + + o Match transactions NOT to the 'expenses:food' account OR with the 'A' + tag + + expr:"NOT expenses:food OR tag:A" + + o Match transactions NOT involving the 'expenses:food' account OR with + the 'A' tag AND involving the 'expenses:drink' account. (the AND is + implicitly added by space-separation, following the rules above) + + expr:"expenses:food OR (tag:A expenses:drink)" + + Queries and command options + Some queries can also be expressed as command-line options: depth:2 is + equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When + you mix command options and query arguments, generally the resulting + query is their intersection. + + Queries and valuation + When amounts are converted to other commodities in cost or value re- + ports, 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 re- + versed, 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 re- + ports, 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. + +Pivoting + Normally, hledger groups and sums amounts within each account. The + --pivot FIELD option substitutes some other transaction field for ac- + count names, causing amounts to be grouped and summed by that field's + value instead. FIELD can be any of the transaction fields acct, sta- + tus, code, desc, payee, note, or a tag name. When pivoting on a tag + and a posting has multiple values of that tag, only the first value is + displayed. Values containing colon:separated:parts will be displayed + hierarchically, like account names. Multiple, colon-delimited fields + can be pivoted simultaneously, generating a hierarchical account name. + + Some examples: + + 2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe, kind: Lifetime + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + + Hierarchical reports can be generated with multiple pivots: + + $ hledger balance Income:Dues --pivot kind:member + -2 EUR Lifetime:John Doe + -------------------- + -2 EUR + +Generating data + hledger has several features for generating data, such as: + + o Periodic transaction rules can generate single or repeating transac- + tions following a template. These are usually dated in the future, + eg to help with forecasting. They are activated by the --forecast + option. + + o The balance command's --budget option uses these same periodic rules + to generate goals for the budget report. + + o Auto posting rules can generate extra postings on certain matched + transactions. They are always applied to forecast transactions; with + the --auto flag they are applied to transactions recorded in the + journal as well. + + o The --infer-equity flag infers missing conversion equity postings + from @/@@ costs. And the inverse --infer-costs flag infers missing + @/@@ costs from conversion equity postings. + + Generated data of this kind is temporary, existing only at report time. + But you can see it in the output of hledger print, and you can save + that to your journal, in effect converting it from temporary generated + data to permanent recorded data. This could be useful as a data entry + aid. + + If you are wondering what data is being generated and why, add the + --verbose-tags flag. In hledger print output you will see extra tags + like generated-transaction, generated-posting, and modified on gener- + ated/modified data. Also, even without --verbose-tags, generated data + always has equivalen hidden tags (with an underscore prefix), so eg you + could match generated transactions with tag:_generated-transaction. + +Forecasting + Forecasting, or speculative future reporting, can be useful for esti- + mating future balances, or for exploring different future scenarios. + + The simplest and most flexible way to do it with hledger is to manually + record a bunch of future-dated transactions. You could keep these in a + separate future.journal and include that with -f only when you want to + see them. + + --forecast + There is another way: with the --forecast option, hledger can generate + temporary "forecast transactions" for reporting purposes, according to + periodic transaction rules defined in the journal. Each rule can gen- + erate multiple recurring transactions, so by changing one rule you can + change many forecasted transactions. (These same rules can also gener- + ate budget goals, described in Budgeting.) + + Forecast transactions usually start after ordinary transactions end. + By default, they begin after your latest-dated ordinary transaction, or + today, whichever is later, and they end six months from today. (The + exact rules are a little more complicated, and are given below.) + + This is the "forecast period", which need not be the same as the report + period. You can override it - eg to forecast farther into the future, + or to force forecast transactions to overlap your ordinary transactions + - by giving the --forecast option a period expression argument, like + --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- + quired. + + Inspecting forecast transactions + print is the best command for inspecting and troubleshooting forecast + transactions. Eg: + + ~ monthly from 2022-12-20 rent + assets:bank:checking + expenses:rent $1000 + + $ hledger print --forecast --today=2023/4/21 + 2023-05-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-06-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-07-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-08-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-09-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + Here there are no ordinary transactions, so the forecasted transactions + begin on the first occurence after today's date. (You won't normally + use --today; it's just to make these examples reproducible.) + + Forecast reports + Forecast transactions affect all reports, as you would expect. Eg: + + $ hledger areg rent --forecast --today=2023/4/21 + Transactions in expenses:rent and subaccounts: + 2023-05-20 rent as:ba:checking $1000 $1000 + 2023-06-20 rent as:ba:checking $1000 $2000 + 2023-07-20 rent as:ba:checking $1000 $3000 + 2023-08-20 rent as:ba:checking $1000 $4000 + 2023-09-20 rent as:ba:checking $1000 $5000 + + $ hledger bal -M expenses --forecast --today=2023/4/21 + Balance changes in 2023-05-01..2023-09-30: + + || May Jun Jul Aug Sep + ===============++=================================== + expenses:rent || $1000 $1000 $1000 $1000 $1000 + ---------------++----------------------------------- + || $1000 $1000 $1000 $1000 $1000 + + Forecast tags + Forecast transactions generated by --forecast have a hidden tag, _gen- + erated-transaction. So if you ever need to match forecast transac- + tions, you could use tag:_generated-transaction (or just tag:generated) + in a query. + + For troubleshooting, you can add the --verbose-tags flag. Then, visi- + ble generated-transaction tags will be added also, so you can view them + with the print command. Their value indicates which periodic rule was + responsible. + + Forecast period, in detail + Forecast start/end dates are chosen so as to do something useful by de- + fault in almost all situations, while also being flexible. Here are + (with luck) the exact rules, to help with troubleshooting: + + The forecast period starts on: + + o the later of + + o the start date in the periodic transaction rule + + o the start date in --forecast's argument + + o otherwise (if those are not available): the later of + + o the report start date specified with -b/-p/date: + + o the day after the latest ordinary transaction in the journal + + o otherwise (if none of these are available): today. + + The forecast period ends on: + + o the earlier of + + o the end date in the periodic transaction rule + + o the end date in --forecast's argument + + o otherwise: the report end date specified with -e/-p/date: + + o otherwise: 180 days (~6 months) from today. + + Forecast troubleshooting + When --forecast is not doing what you expect, one of these tips should + help: + + o Remember to use the --forecast option. + + o Remember to have at least one periodic transaction rule in your jour- + nal. + + o Test with print --forecast. + + o Check for typos or too-restrictive start/end dates in your periodic + transaction rule. + + o Leave at least 2 spaces between the rule's period expression and de- + scription fields. + + o Check for future-dated ordinary transactions suppressing forecasted + transactions. + + o Try setting explicit report start and/or end dates with -b, -e, -p or + date: + + o Try adding the -E flag to encourage display of empty periods/zero + transactions. + + o Try setting explicit forecast start and/or end dates with --fore- + cast=START..END + + o Consult Forecast period, in detail, above. + + o Check inside the engine: add --debug=2 (eg). + +Budgeting + With the balance command's --budget report, each periodic transaction + rule generates recurring budget goals in specified accounts, and goals + and actual performance can be compared. See the balance command's doc + below. + + You can generate budget goals and forecast transactions at the same + time, from the same or different periodic transaction rules: hledger + bal -M --budget --forecast ... + + See also: Budgeting and Forecasting. + +Cost reporting + In some transactions - for example a currency conversion, or a purchase + or sale of stock - one commodity is exchanged for another. In these + transactions there is a conversion rate, also called the cost (when + buying) or selling price (when selling). In hledger docs we just say + "cost", for convenience; feel free to mentally translate to "conversion + rate" or "selling price" if helpful. + + Recording costs + We'll explore several ways of recording transactions involving costs. + These are also summarised at hledger Cookbook > Cost notation. + + Costs can be recorded explicitly in the journal, using the @ UNITCOST + or @@ TOTALCOST notation described in Journal > Costs: + + Variant 1 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 @ $1.35 ; $1.35 per euro (unit cost) + + Variant 2 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 @@ $135 ; $135 total cost + + Typically, writing the unit cost (variant 1) is preferable; it can be + more effort, requiring more attention to decimal digits; but it reveals + the per-unit cost basis, and makes stock sales easier. + + Costs can also be left implicit, and hledger will infer the cost that + is consistent with a balanced transaction: + + Variant 3 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 + + Here, hledger will attach a @@ 100 cost to the first amount (you can + see it with hledger print -x). This form looks convenient, but there + are downsides: + + o It sacrifices some error checking. For example, if you accidentally + wrote 10 instead of 100, hledger would not be able to detect the mis- + take. + + o It is sensitive to the order of postings - if they were reversed, a + different entry would be inferred and reports would be different. + + o The per-unit cost basis is not easy to read. + + So generally this kind of entry is not recommended. You can make sure + you have none of these by using -s (strict mode), or by running hledger + check balanced. + + Reporting at cost + Now when you add the -B/--cost flag to reports ("B" is from Ledger's + -B/--basis/--cost flag), any amounts which have been annotated with + costs will be converted to their cost's commodity (in the report out- + put). Ie they will be displayed "at cost" or "at sale price". + + Some things to note: + + o Costs are attached to specific posting amounts in specific transac- + tions, and once recorded they do not change. This contrasts with + market prices, which are ambient and fluctuating. + + o Conversion to cost is performed before conversion to market value + (described below). + + Equity conversion postings + There is a problem with the entries above - they are not conventional + Double Entry Bookkeeping (DEB) notation, and because of the "magical" + transformation of one commodity into another, they cause an imbalance + in the Accounting Equation. This shows up as a non-zero grand total in + balance reports like hledger bse. + + For most hledger users, this doesn't matter in practice and can safely + be ignored ! But if you'd like to learn more, keep reading. + + Conventional DEB uses an extra pair of equity postings to balance the + transaction. Of course you can do this in hledger as well: + + Variant 4 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 + equity:conversion $135 + equity:conversion -100 + + Now the transaction is perfectly balanced according to standard DEB, + and hledger bse's total will not be disrupted. + + And, hledger can still infer the cost for cost reporting, but it's not + done by default - you must add the --infer-costs flag like so: + + $ hledger print --infer-costs + 2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 @@ 100 + assets:euros 100 + equity:conversion $135 + equity:conversion -100 + + $ hledger bal --infer-costs -B + -100 assets:dollars + 100 assets:euros + -------------------- + 0 + + Here are some downsides of this kind of entry: + + o The per-unit cost basis is not easy to read. + + o Instead of -B you must remember to type -B --infer-costs. + + o --infer-costs works only where hledger can identify the two eq- + uity:conversion postings and match them up with the two non-equity + postings. So writing the journal entry in a particular format be- + comes more important. More on this below. + + Inferring equity conversion postings + Can we go in the other direction ? Yes, if you have transactions writ- + ten with the @/@@ cost notation, hledger can infer the missing equity + postings, if you add the --infer-equity flag. Eg: + + 2022-01-01 + assets:dollars -$135 + assets:euros 100 @ $1.35 + + $ hledger print --infer-equity + 2022-01-01 + assets:dollars $-135 + assets:euros 100 @ $1.35 + equity:conversion:$-: -100 + equity:conversion:$-:$ $135.00 + + The equity account names will be "equity:conversion:A-B:A" and "eq- + uity:conversion:A-B:B" where A is the alphabetically first commodity + symbol. You can customise the "equity:conversion" part by declaring an + account with the V/Conversion account type. + + Combining costs and equity conversion postings + Finally, you can use both the @/@@ cost notation and equity postings at + the same time. This in theory gives the best of all worlds - preserv- + ing the accounting equation, revealing the per-unit cost basis, and + providing more flexibility in how you write the entry: + + Variant 5 + + 2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion -100 + assets:euros 100 @ $1.35 + + All the other variants above can (usually) be rewritten to this final + form with: + + $ hledger print -x --infer-costs --infer-equity + + Downsides: + + o This was added in hledger-1.29 and is still somewhat experimental. + + o The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it + will give a transaction balancing error. + + o The add command does not yet accept this kind of entry (#2056). + + o This is the most verbose form. + + Requirements for detecting equity conversion postings + --infer-costs has certain requirements (unlike --infer-equity, which + always works). It will infer costs only in transactions with: + + o Two non-equity postings, in different commodities. Their order is + significant: the cost will be added to the first of them. + + o Two postings to equity conversion accounts, next to one another, + which balance the two non-equity postings. This balancing is checked + to the same precision (number of decimal places) used in the conver- + sion posting's amount. Equity conversion accounts are: + + o any accounts declared with account type V/Conversion, or their sub- + accounts + + o otherwise, accounts named equity:conversion, equity:trade, or eq- + uity:trading, or their subaccounts. + + And multiple such four-posting groups can coexist within a single + transaction. When --infer-costs fails, it does not infer a cost in + that transaction, and does not raise an error (ie, it infers costs + where it can). + + Reading variant 5 journal entries, combining cost notation and equity + postings, has all the same requirements. When reading such an entry + fails, hledger raises an "unbalanced transaction" error. + + Infer cost and equity by default ? + Should --infer-costs and --infer-equity be enabled by default ? Try + using them always, eg with a shell alias: + + alias h="hledger --infer-equity --infer-costs" + + and let us know what problems you find. + +Value reporting + 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] op- + tion, 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 + Market prices can change from day to day. hledger will use the prices + on a particular valuation date (or on more than one date). By default + hledger uses "end" dates for valuation. More specifically: + + o For single period reports (including normal print and register re- + ports): + + o If an explicit report end date is specified, that is used + + o Otherwise the latest transaction date or P directive date is used + (even if it's in the future) + + o For multiperiod reports, each period is valued on its last day. + + This can be customised with the --value option described below, which + can select either "then", "end", "now", or "custom" dates. (Note, this + has a bug in hledger-ui <=1.31: turning on valuation with the V key al- + ways resets it to "end".) + + Finding market price + To convert a commodity A to its market value in another commodity B, + hledger looks for a suitable market price (exchange rate) as follows, + in this order of preference: + + 1. A declared market price or inferred market price: A's latest market + price in B on or before the valuation date as declared by a P direc- + tive, or (with the --infer-market-prices flag) inferred from costs. + + 2. A reverse market price: the inverse of a declared or inferred market + price from B to A. + + 3. A forward chain of market prices: a synthetic price formed by 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 costs as additional market prices (as + Ledger does) ? Adding the --infer-market-prices flag to -V, -X or + --value enables this. + + So for example, hledger bs -V --infer-market-prices will get market + prices both from P directives and from transactions. If both occur on + the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in confus- + ing/undesired ways by your journal entries. If this happens to you, + read all of this Value reporting 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 multicommodity transactions with equity postings, if cost is inferred + with --infer-costs. + + There is a limitation (bug) currently: when a valuation commodity is + not specified, prices inferred with --infer-market-prices do not help + select a default valuation commodity, as P prices would. So conversion + might not happen because no valuation commodity was detected (--debug=2 + will show this). To be safe, specify the valuation commmodity, eg: + + 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 + + Signed costs and market prices can be confusing. For reference, here + is the current behaviour, since hledger 1.25. (If you think it should + work differently, see #1870.) + + 2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + + 2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + + 2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + + 2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + + 2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + + 2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each day, + the two transactions are considered equivalent). Here are the market + prices inferred for B: + + $ hledger -f- --infer-market-prices prices + P 2022-01-01 B A 1 + P 2022-01-01 B A 1.0 + P 2022-01-02 B A -1 + P 2022-01-02 B A -1.0 + P 2022-01-03 B A -1 + P 2022-01-03 B A -1.0 + + 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, + costs 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 $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 + + --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 + + 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. Re- + lated: #329, #1083. + + Report -B, --cost -V, -X --value=then --value=end --value=DATE, + type --value=now + -------------------------------------------------------------------------------------------- + print + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today + today journal end + balance unchanged unchanged unchanged unchanged unchanged + asser- + tions/as- + signments + + register + starting cost value at re- valued at day value at re- value at + balance port or each historical port or DATE/today + (-H) journal end posting was made journal end + starting cost value at day valued at day value at day value at + balance before re- each historical before re- DATE/today + (-H) with port or posting was made port or + report journal journal + interval start start + posting cost value at re- value at posting value at re- value at + amounts port or date port or DATE/today + journal end journal end + summary summarised value at pe- sum of postings value at pe- value at + posting cost riod ends in interval, val- riod ends DATE/today + amounts ued at interval + with re- start + port in- + terval + running sum/average sum/average sum/average of sum/average sum/average + total/av- of displayed of displayed displayed values of displayed of displayed + erage values values values values + + balance + (bs, bse, + cf, is) + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of + 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 + (--bud- + get) + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + tal played val- played val- valued played val- played values + ues ues ues + + balance + (bs, bse, + cf, is) + with re- + port in- + terval + starting sums of value at re- sums of values of value at re- sums of post- + balances costs of port start postings before port start ings before + (-H) postings be- of sums of report start at of sums of report start + fore report all postings respective post- all postings + start before re- ing dates before re- + port start port start + balance sums of same as sums of values of balance value at + changes costs of --value=end postings in pe- change in DATE/today of + (bal, is, postings in riod at respec- each period, sums of post- + bs period tive posting valued at ings + --change, dates period ends + cf + --change) + end bal- sums of same as sums of values of period end value at + ances costs of --value=end postings from be- balances, DATE/today of + (bal -H, postings fore period start valued at sums of post- + is --H, from before to period end at period ends ings + bs, cf) report start respective post- + to period ing dates + end + budget like balance like balance like balance like bal- like balance + amounts changes/end changes/end changes/end bal- ances changes/end + (--bud- balances balances ances balances + get) + row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + averages played val- played val- played val- played values + (-T, -A) ues ues ues + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + totals played val- played val- values played val- played values + ues ues ues + grand to- sum, average sum, average sum, average of sum, average sum, average + tal, of column of column column totals of column of column to- + grand av- totals totals totals tals + erage + + + --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). + +PART 4: COMMANDS + Commands overview + Here are the built-in commands: + + DATA ENTRY + These data entry commands are the only ones which can modify your jour- + nal file. + + o add - add transactions using terminal prompts + + o import - add new transactions from other files, eg CSV files + + DATA CREATION + o close - generate balance-zeroing/restoring transactions + + o rewrite - generate auto postings, like print --auto + + DATA MANAGEMENT + o check - check for various kinds of error in the data + + o diff - compare account transactions in two journal files + + REPORTS, FINANCIAL + 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 + + REPORTS, VERSATILE + o balance (bal) - show balance changes, end balances, budgets, gains.. + + o print - show transactions or export journal data + + o register (reg) - show postings in one or more accounts & running to- + tal + + o roi - show return on investments + + REPORTS, BASIC + o accounts - show account names + + o activity - show bar charts of posting counts per period + + o codes - show transaction codes + + o commodities - show commodity/currency symbols + + o descriptions - show transaction descriptions + + o files - show input file paths + + o notes - show note parts of transaction descriptions + + o payees - show payee parts of transaction descriptions + + o prices - show market prices + + o stats - show journal statistics + + o tags - show tag names + + o test - run self tests + + HELP + o help - show the hledger manual with info/man/pager + + o demo - show small hledger demos in the terminal + + ADD-ONS + And here are some typical add-on commands. Some of these are installed + by the hledger-install script. If installed, they will appear in + hledger's commands list: + + o ui - run hledger's terminal UI + + o web - run hledger's web UI + + o iadd - add transactions using a TUI (currently hard to build) + + o interest - generate interest transactions + + o stockquotes - download market prices from AlphaVantage + + o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + pijul, plot, and more.. + + Next, each command is described in detail, in alphabetical order. + + accounts + Show account names. + + This command lists account names. By default it shows all known ac- + counts, either used in transactions or declared with account direc- + tives. + + With query arguments, only matched account names and account names ref- + erenced by matched postings are shown. + + Or it can show just the used accounts (--used/-u), the declared ac- + counts (--declared/-d), the accounts declared but not used (--unused), + the accounts used but not declared (--undeclared), or the first account + matched by an account name pattern, if any (--find). + + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. In flat mode you can add --drop N to omit + the first few account name components. Account names can be depth- + clipped with depth:N or --depth N or -N. + + With --types, it also shows each account's type, if it's known. (See + Declaring accounts > Account types.) + + With --positions, it also shows the file and line number of each ac- + count's declaration, if any, and the account's overall declaration or- + der; these may be useful when troubleshooting account display order. + + With --directives, it adds the account keyword, showing valid account + directives which can be pasted into a journal file. This is useful to- + gether with --undeclared when updating your account declarations to + satisfy hledger check accounts. + + The --find flag can be used to look up a single account name, in the + same way that the aregister command does. It returns the alphanumeri- + cally-first matched account name, or if none can be found, it fails + with a non-zero exit code. + + Examples: + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + $ hledger accounts --undeclared --directives >> $LEDGER_FILE + $ hledger check accounts + + 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 + 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 de- + scription) 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, pay- + ees/descriptions, 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 https://hledger.org/add.html for a detailed tutorial): + + $ hledger add + Adding transactions to journal file /src/hledger/examples/sample.journal + Any command line arguments will be used as defaults. + Use tab key to complete, readline keys to edit, enter to accept defaults. + An optional (CODE) may follow transaction dates. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to go one step backward. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2015/05/22]: + Description: supermarket + Account 1: expenses:food + Amount 1: $10 + Account 2: assets:checking + Amount 2 [$-10.0]: + Account 3 (or . or enter to finish this transaction): . + 2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2015/05/22]: $ + + On Microsoft Windows, the add command makes sure that no part of the + file path ends with a period, as that would cause problems (#1056). + + aregister + (areg) + + Show the transactions and running historical balance of a single ac- + count, 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 in- + cluded 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 ex- + pression which will select the alphabetically first matched account. + + When there are multiple matches, the alphabetically-first choice can be + surprising; eg if you have assets:per:checking 1 and assets:biz:check- + ing 2 accounts, hledger areg checking would select assets:biz:checking + 2. It's just a convenience to save typing, so if in doubt, write the + full account name, or a distinctive substring that matches uniquely. + + Transactions involving subaccounts of this account will also be shown. + aregister ignores depth limits, so its final total will always match a + balance report with similar arguments. + + Any additional arguments form a query which will filter the 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 op- + tions. The output formats supported are txt, csv, tsv, and json. + + aregister and posting dates + aregister always shows one line (and date and amount) per transaction. + But sometimes transactions have postings with different dates. Also, + not all of a transaction's postings may be within the report period. + To resolve this, aregister shows the earliest of the transaction's date + and posting dates that is in-period, and the sum of the in-period post- + ings. In other words it will show a combined line item with just the + earliest date, and the running balance will (temporarily, until the + transaction's last posting) be inaccurate. Use register -H if you need + to see the individual postings. + + There is also a --txn-dates flag, which filters strictly by transaction + date, ignoring posting dates. This too can cause an inaccurate running + 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) + + o or postings count (--count) + + ..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 (--in- + vert) + + 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, tsv, 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. ("Simple" here + means just one column of numbers, covering a single period. You can + also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end bal- + ance 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 (re- + vealing 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. + + Balance report line format + For single-period balance reports displayed in the terminal (only), you + can use --format FMT to customise the format and content of each line. + Eg: + + $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 + --------------------------------- + 0 + + The FMT format string specifies the formatting applied to each ac- + count/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 ef- + fect, 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 + + 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 + + Showing declared accounts + With --declared, accounts which have been declared with an account di- + rective 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 re- + port, even when you don't have transactions in all of your declared ac- + counts yet. + + 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 + biggest averaged monthly expenses first. When more than one commodity + is present, they will be sorted by the alphabetically earliest commod- + ity 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 --in- + vert 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. + + 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: + + 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 + + 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 ac- + count 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 + The balance command is quite flexible; here is the full detail on how + to control what it reports. If the following seems complicated, don't + worry - this is for advanced reporting, and it does take time and ex- + perimentation to get familiar with all the report modes. + + There are three important option groups: + + hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] + ... + + Calculation type + The basic calculation to perform for each table cell. It is one of: + + o --sum : sum the posting amounts (default) + + o --budget : sum the amounts, but also show the budget goal amount (for + each account/period) + + 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) + + o --count : show the count of postings + + Accumulation type + How amounts should accumulate across report periods. Another way to + say it: which time period's postings should contribute to each cell's + calculation. It is one of: + + o --change : calculate with postings from column start to column end, + ie "just this column". Typically used to see revenues/expenses. + (default for balance, incomestatement) + + o --cumulative : calculate with postings from report start to column + end, ie "previous columns plus this column". Typically used to show + changes accumulated since the report's start date. Not often used. + + o --historical/-H : calculate with postings from journal start to col- + umn end, ie "all postings from before report start date until this + column's end". Typically used to see historical end balances of as- + sets/liabilities/equity. (default for balancesheet, balancesheete- + quity, cashflow) + + Valuation type + Which kind of value or cost conversion should be applied, if any, be- + fore displaying the report. It is one of: + + o no valuation type : don't convert to cost or value (default) + + o --value=cost[,COMM] : convert amounts to cost (then optionally to + some other commodity) + + o --value=then[,COMM] : convert amounts to market value on transaction + dates + + o --value=end[,COMM] : convert amounts to market value on period end + date(s) + (default with --valuechange, --gain) + + o --value=now[,COMM] : convert amounts to market value on today's date + + o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- + other date + + or one of the equivalent simpler flags: + + o -B/--cost : like --value=cost (though, note --cost and --value are + independent options which can both be used at once) + + o -V/--market : like --value=end + + o -X COMM/--exchange COMM : like --value=end,COMM + + See Cost reporting and Value reporting for more about these. + + Combining balance report types + Most combinations of these options should produce reasonable reports, + but if you find any that seem wrong or misleading, let us know. The + following restrictions are applied: + + 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 pe- + ues in period in period riod + --cumu- change from re- sum of posting- period-end DATE-value of + lative port 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 + + Budget report + The --budget report type activates extra columns showing any budget + goals for each account and period. The budget goals are defined by pe- + riodic transactions. This is useful for comparing planned and actual + income, expenses, time usage, etc. + + For example, you can take average monthly expenses in the common ex- + pense 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. Cur- + rently: + + o Accounts with budget goals during the report period, and their par- + ents, are shown. + + o Their subaccounts are not shown (regardless of the depth setting). + + o Accounts without budget goals, if any, are aggregated and shown as + "". + + o Amounts are always inclusive (subaccount-including), even in list + mode. + + o After each actual amount, the corresponding goal amount and percent- + age of goal reached are also shown, in square brackets. + + This means that the numbers displayed will not always add up! Eg + above, the expenses actual amount includes the gifts and supplies + transactions, but the expenses:gifts and expenses:supplies accounts are + not shown, as they have no budget amounts declared. + + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted + ones, giving the full picture. Eg: + + $ hledger balance -M --budget --empty + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with --cumulative: + + $ hledger balance -M --budget --cumulative + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + It's common to limit budgets/budget reports to just expenses + + hledger bal -M --budget expenses + + or just revenues and expenses (eg, using account types): + + hledger bal -M --budget type:rx + + It's also common to limit or convert them to a single currency + (cur:COMM or -X COMM [--infer-market-prices]). If showing multiple + currencies, --layout bare or --layout tall can help. + + For more examples and notes, see Budgeting. + + 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 to- + wards 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: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 ac- + count in each report subperiod. When troubleshooting, you can use + print --forecast to show these as forecasted transactions: + + $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated + + By default, the budget report uses all available periodic transaction + rules to generate goals. This includes rules with a different report + interval from your report. Eg if you have daily, weekly and monthly + periodic rules, all of these will contribute to the goals in a monthly + budget report. + + You can select a subset of periodic rules by providing an argument to + the --budget flag. --budget=DESCPAT will match all periodic rules + whose description contains DESCPAT, a case-insensitive substring (not a + regular expression or query). This means you can give your periodic + rules descriptions (remember that two spaces are needed), and then se- + lect from multiple budgets defined in your journal. + + Budget vs forecast + hledger --forecast ... and hledger balance --budget ... are separate + features, though both of them use the periodic transaction rules de- + fined in the journal, and both of them generate temporary transactions + for reporting purposes ("forecast transactions" and "budget goal trans- + actions", respectively). You can use both features at the same time if + you want. Here are some differences between them, as of hledger 1.29: + + CLI: + + o --forecast is a general hledger option, usable with any command + + o --budget is a balance command option, usable only with that command. + + Visibility of generated transactions: + + o forecast transactions are visible in any report, like ordinary trans- + actions + + o budget goal transactions are invisible except for the goal amounts + they produce in --budget reports. + + Periodic transaction rules: + + o --forecast uses all available periodic transaction rules + + o --budget uses all periodic rules (--budget) or a selected subset + (--budget=DESCPAT) + + Period of generated transactions: + + o --forecast generates forecast transactions + + o from after the last regular transaction to the end of the report + period (--forecast) + + o or, during a specified period (--forecast=PERIODEXPR) + + o possibly further restricted by a period specified in the periodic + transaction rule + + o and always restricted within the bounds of the report period + + o --budget generates budget goal transactions + + o throughout the report period + + o possibly restricted by a period specified in the periodic transac- + tion rule. + + Balance report layout + The --layout option affects how balance reports show multi-commodity + amounts and commodity symbols, which can improve readability. It can + also normalise the data for easy consumption by other programs. It has + four possible values: + + o --layout=wide[,WIDTH]: commodities are shown on a single line, op- + tionally elided to WIDTH + + o --layout=tall: each commodity is shown on a separate line + + o --layout=bare: commodity symbols are in their own column, amounts are + bare numbers + + o --layout=tidy: data is normalised to easily-consumed "tidy" form, + with one row per data value + + Here are the --layout modes supported by each output format; note only + CSV output supports all of them: + + - txt csv html json sql + ------------------------------------- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y + + Examples: + + 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 for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + o Note: bare layout will sometimes display an extra row for the no-sym- + bol commodity, because of zero amounts (hledger treats zeroes as com- + modity-less, usually). This can break hledger-bar confusingly + (workaround: add a cur: query to exclude the no-symbol row). + + o Tidy layout produces normalised "tidy data", where every variable has + its own column and each row represents a single data point. See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- + data.html for more. This is the easiest kind of data for other soft- + ware to consume. Here's how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + 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 + + 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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + 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 in- + sensitive, 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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + 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 al- + lowed) + + o whose name contains some variation of cash, bank, checking or saving. + + More precisely: all accounts matching this case insensitive regular ex- + pression: + + ^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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + check + Check for various kinds of errors in your data. + + hledger provides a number of built-in error checks to help prevent + problems in your data. Some of these are run automatically; or, you + can use this check command to run them on demand, with no output and a + zero exit code if all is well. Specify their names (or a prefix) as + argument(s). + + Some examples: + + hledger check # basic checks + hledger check -s # basic + strict checks + hledger check ordereddates payees # basic + two other checks + + If you are an Emacs user, you can also configure flycheck-hledger to + run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available: + + Default checks + These checks are run automatically by (almost) all hledger commands: + + o parseable - data files are in a supported format, with no syntax er- + rors and no invalid include directives. + + o autobalanced - all transactions are balanced, after converting to + cost. Missing amounts and missing costs are inferred automatically + where possible. + + 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 balanced - all transactions are balanced after converting to cost, + without inferring missing costs. If conversion costs are required, + they must be explicit. + + o accounts - all account names used by transactions have been declared + + o commodities - all commodity symbols used have been declared + + 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: + + o ordereddates - transactions are ordered by date within each file + + o payees - all payees used by transactions have been declared + + o recentassertions - all accounts with balance assertions have a bal- + ance assertion within 7 days of their latest posting + + o tags - all tags 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. + + More about specific checks + hledger check recentassertions will complain if any balance-asserted + account has postings more than 7 days after its latest balance asser- + tion. This aims to prevent the situation where you are regularly up- + dating your journal, but forgetting to check your balances against the + real world, then one day must dig back through months of data to find + an error. It assumes that adding a balance assertion requires/reminds + you to check the real-world balance. (That may not be true if you + auto-generate balance assertions from bank data; in that case, I recom- + mend to import transactions uncleared, and when you manually review and + clear them, also check the latest assertion against the real-world bal- + ance.) + + close + (equity) + + Generate transactions which transfer account balances to and/or from + another account (typically equity). This can be useful for migrating + balances to a new journal file, or for merging earnings into equity at + end of accounting period. + + By default, it prints a transaction that zeroes out ALE accounts (as- + set, liability, equity accounts; this requires account types to be con- + figured); or if ACCTQUERY is provided, the accounts matched by that. + + (experimental) + + This command has four main modes, corresponding to the most common use + cases: + + 1. With --close (default), it prints a "closing balances" transaction + that zeroes out ALE (asset, liability, equity) accounts by default + (this requires account types to be inferred or declared); or, the + accounts matched by the provided ACCTQUERY arguments. + + 2. With --open, it prints an opposite "opening balances" transaction + that restores those balances from zero. This is similar to Ledger's + equity command. + + 3. With --migrate, it prints both the closing and opening transactions. + This is the preferred way to migrate balances to a new file: run + hledger close --migrate, add the closing transaction at the end of + the old file, and add the opening transaction at the start of the + new file. The matching closing/opening transactions cancel each + other out, preserving correct balances during multi-file reporting. + + 4. With --retain, it prints a "retain earnings" transaction that trans- + fers RX (revenue and expense) balances to equity:retained earnings. + Businesses traditionally do this at the end of each accounting pe- + riod; it is less necessary with computer-based accounting, but it + could still be useful if you want to see the accounting equation + (A=L+E) satisfied. + + In all modes, the defaults can be overridden: + + o the transaction descriptions can be changed with --close-desc=DESC + and --open-desc=DESC + + o the account to transfer to/from can be changed with --close-acct=ACCT + and --open-acct=ACCT + + o the accounts to be closed/opened can be changed with ACCTQUERY (ac- + count query arguments). + + o the closing/opening dates can be changed with -e DATE (a report end + date) + + By default just one destination/source posting will be used, with its + amount left implicit. With --x/--explicit, the amount will be shown + explicitly, and if it involves multiple commodities, a separate posting + will be generated for each of them (similar to print -x). + + With --show-costs, any amount costs are shown, with separate postings + for each cost. This is currently the best way to view investment lots. + If you have many currency conversion or investment transactions, it can + generate very large journal entries. + + With --interleaved, each individual transfer is shown with source and + destination postings next to each other. This could be useful for + troubleshooting. + + The default closing date is yesterday, or the journal's end date, + whichever is later. You can change this by specifying a report end + date with -e. The last day of the report period will be the closing + date, eg -e 2024 means "close on 2023-12-31". The opening date is al- + ways the day after the closing date. + + close and balance assertions + Balance assertions will be generated, verifying that the accounts have + been reset to zero (and then restored to their previous balances, if + there is an opening transaction). + + These provide useful error checking, but you can ignore them temporar- + ily with -I, or remove them if you prefer. + + You probably should avoid filtering transactions by status or realness + (-C, -R, status:), or generating postings (--auto), with this command, + since the balance assertions would depend on these. + + Note custom posting dates spanning the file boundary will disrupt the + balance assertions: + + 2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve that you can transfer the money to and from a temporary ac- + count, in effect splitting the multi-day transaction into two single- + day transactions: + + ; in 2022.journal: + 2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + + ; in 2023.journal: + 2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + Example: retain earnings + Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- + pending the generated transaction to the journal: + + $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + Note 2022's income statement will now show only zeroes, because rev- + enues and expenses have been moved entirely to equity. To see them + again, you could exclude the retain transaction: + + $ hledger -f 2022.journal is not:desc:'retain earnings' + + Example: migrate balances to a new file + Close assets/liabilities/equity on 2022-12-31 and re-open them on + 2023-01-01: + + $ hledger close --migrate -f 2022.journal -p 2022 + # copy/paste the closing transaction to the end of 2022.journal + # copy/paste the opening transaction to the start of 2023.journal + + Now 2022's balance sheet will show only zeroes, indicating a balanced + accounting equation. (Unless you are using @/@@ notation - in that + case, try adding --infer-equity.) To see the end-of-year balances + again, you could exclude the closing transaction: + + $ hledger -f 2022.journal bs not:desc:'closing balances' + + Example: excluding closing/opening transactions + When combining many files for multi-year reports, the closing/opening + transactions cause some noise in transaction-oriented reports like + print and register. You can exclude them as shown above, but + not:desc:... is not ideal as it depends on consistent descriptions; + also you will want to avoid excluding the very first opening transac- + tion, which could be awkward. Here is one alternative, using tags: + + Add clopen: tags to all opening/closing balances transactions except + the first, like this: + + ; 2021.journal + 2021-06-01 first opening balances + ... + 2021-12-31 closing balances ; clopen:2022 + ... + + ; 2022.journal + 2022-01-01 opening balances ; clopen:2022 + ... + 2022-12-31 closing balances ; clopen:2023 + ... + + ; 2023.journal + 2023-01-01 opening balances ; clopen:2023 + ... + + Now, assuming a combined journal like: + + ; all.journal + include 2021.journal + include 2022.journal + include 2023.journal + + The clopen: tag can exclude all but the first opening transaction. To + show a clean multi-year checking register: + + $ hledger -f all.journal areg checking not:tag:clopen + + And the year values allow more precision. To show 2022's year-end bal- + ance sheet: + + $ hledger -f all.journal bs -e2023 not:tag:clopen=2023 + + codes + List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often + used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty codes + will not be shown by default. With the -E/--empty flag, they will be + printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + + 2022/1/1 (123) Supermarket + Food $5.00 + Checking + + 2022/1/2 (124) Post Office + Postage $8.32 + Checking + + 2022/1/3 Supermarket + Food $11.23 + Checking + + 2022/1/4 (126) Post Office + Postage $3.21 + Checking + + $ hledger codes + 123 + 124 + 126 + + $ hledger codes -E + 123 + 124 + + 126 + + commodities + List all commodity/currency symbols used or declared in the journal. + + demo + Play demos of hledger usage in the terminal, if asciinema is installed. + + Run this command with no argument to list the demos. To play a demo, + write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/--speed SPEED option to set your preferred playback speed, + eg -s4 to play at 4x original speed or -s.5 to play at half speed. The + default speed is 2x. + + Other asciinema options can be added following a double dash, eg -- + -i.1 to limit pauses or -- -h to list asciinema's other options. + + During playback, several keys are available: SPACE to pause/unpause, . + to step forward (while paused), CTRL-c quit. + + Examples: + + $ hledger demo # list available demos + $ hledger demo 1 # play the first demo at default speed (2x) + $ hledger demo install -s4 # play the "install" demo at 4x speed + + 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 + 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 + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + help + Show the hledger user manual in the terminal, with info, man, or a + pager. With a TOPIC argument, open it at that topic if possible. + TOPIC can be any heading in the manual, or a heading prefix, case in- + sensitive. Eg: commands, print, forecast, journal, amount, "auto post- + ings". + + This command shows the hledger manual built in to your hledger version. + It can be useful when offline, or when you prefer the terminal to a web + browser, or when the appropriate hledger manual or viewing tools are + not installed on your system. + + By default it chooses the best viewer found in $PATH, trying (in this + order): info, man, $PAGER, less, more. You can force the use of info, + man, or a pager with the -i, -m, or -p flags, If no viewer can be + found, or the command is run non-interactively, it just prints the man- + ual to stdout. + + If using info, note that version 6 or greater is needed for TOPIC + lookup. If you are on mac you will likely have info 4.8, and should + consider installing a newer version, eg with brew install texinfo + (#1770). + + Examples + + $ hledger help --help # show how the help command works + $ hledger help # show the hledger manual with info, man or $PAGER + $ hledger help journal # show the journal topic in the hledger manual + $ hledger help -m journal # show it with man, even if info is installed + + import + Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. + + 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 + import does time-based deduplication, to detect only the new transac- + tions since the last successful import. (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 periodi- + cally importing downloaded data, which may overlap with previous down- + loads. Eg if every week (or every day) you download a bank's last + three months of CSV data, you can safely run hledger import thebank.csv + each time and only new transactions will be imported. + + 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.FILE" file in FILE's directory (after a succesful + import). + + Eg when reading finance/bank.csv, it will look for and update the fi- + nance/.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 cer- + tain date. + + Note deduplication (and updating of state files) can also be done by + print --new, but this is less often used. + + Related: CSV > Working with CSV > Deduplicating, importing. + + Import testing + With --dry-run, the transactions that will be imported are printed to + the terminal, without updating your journal or state files. The output + is valid journal format, like the print command, so you can re-parse + it. Eg, to see any importable transactions which CSV rules have not + categorised: + + $ hledger import --dry bank.csv | hledger -f- -I print unknown + + or (live updating): + + $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' + + Note: when importing from multiple files at once, it's currently possi- + ble for some .latest files to be updated successfully, while the actual + import fails because of a problem in one of the files, leaving them out + of sync (and causing some transactions to be missed). To prevent this, + do a --dry-run first and fix any problems before the real import. + + 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 + (is) + + This command displays an income statement, showing revenues and ex- + penses during one or more periods. Amounts are shown with normal posi- + tive 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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + notes + List the unique notes that appear in transactions. + + This command lists the unique notes that appear in transactions, in al- + phabetic 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 + 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 + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With + --show-reverse, also show additional prices inferred by reversing known + prices. + + Price amounts are always displayed with their full precision, except + for reverse prices which are limited to 8 decimal digits. + + Prices can be filtered by a date:, cur: or amt: query. + + Generally if you run this command with --infer-market-prices --show-re- + verse, it will show the same prices used internally to calculate value + reports. But if in doubt, you can inspect those directly by running + the value report with --debug=2. + + 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). + + 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/regenerate your journal you should take care to also copy + over the directives and inter-transaction comments. + + Eg: + + $ hledger print -f examples/sample.journal date:200806 + 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 + + print explicitness + Normally, whether posting amounts are implicit or explicit is pre- + served. For example, when an amount is omitted in the journal, it will + not appear in the output. Similarly, if a conversion cost is implied + but not written, it will not appear in the output. + + You can use the -x/--explicit flag to force explicit display of all + amounts and costs. This can be useful for troubleshooting or for mak- + ing your journal more readable and robust against data entry errors. + -x is also implied by using any of -B,-V,-X,--value. + + The -x/--explicit flag will cause any postings with a multi-commodity + amount (which can arise when a multi-commodity transaction has an im- + plicit amount) to be split into multiple single-commodity postings, + keeping the output parseable. + + print amount style + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can do that with ledger-mode in + Emacs). + + Amounts will be (mostly) normalised to their commodity display style: + their symbol placement, decimal mark, and digit group marks will be + made consistent. By default, decimal digits are shown as they are + written in the journal. + + With the --round option, print will try increasingly hard to display + decimal digits according to the commodity display styles: + + o --round=none show amounts with original precisions (default) + + o --round=soft add/remove decimal zeros in amounts (except costs) + + o --round=hard round amounts (except costs), possibly hiding signifi- + cant digits + + o --round=all round all amounts and costs + + soft is good for non-lossy cleanup, formatting amounts more consis- + tently where it's safe to do so. + + hard and all can cause print to show invalid unbalanced journal en- + tries; they may be useful eg for stronger cleanup, with manual fixups + when needed. + + print parseability + 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 (though the same can be achieved with expr: queries + now): + + # 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 Value reporting affects posting amounts but not balance assertion or + balance 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. + + print, other features + With -B/--cost, amounts with costs are shown converted to cost. + + With --new, print shows 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.) + + With -m DESC/--match=DESC, print shows one recent transaction whose de- + scription is most similar to DESC. DESC should contain at least two + characters. If there is no similar-enough match, no transaction will + be shown and the program exit code will be non-zero. + + print output format + This command also supports the output destination and output format op- + tions The output formats supported are txt, beancount, csv, tsv, json + and sql. + + Experimental: The beancount format tries to produce Beancount-compati- + ble output, as follows: + + o Transaction and postings with unmarked status are converted to + cleared (*) status. + + o Transactions' payee and note are backslash-escaped and double-quote- + escaped and wrapped in double quotes. + + o Transaction tags are copied to Beancount #tag format. + + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency + names. + + o Account name parts are capitalised and unsupported characters are re- + placed with -. If an account name part does not begin with a letter, + or if the first part is not Assets, Liabilities, Equity, Income, or + Expenses, an error is raised. (Use --alias options to bring your ac- + counts into compliance.) + + o An open directive is generated for each account used, on the earliest + transaction date. + + Some limitations: + + o Balance assertions are removed. + + o Balance assignments become missing amounts. + + o Virtual and balanced virtual postings become regular postings. + + o Directives are not converted. + + 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.) + + 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 ac- + count 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 to- + gether with the related account: + + $ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per in- + terval, 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 op- + tion 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 in- + tervals. This ensures that the first and last intervals are full + length and comparable to the others in the report. + + With -m DESC/--match=DESC, register does a fuzzy search for one recent + posting whose description is most similar to DESC. DESC should contain + at least two characters. If there is no similar-enough match, no post- + ing will be shown and the program exit code will be non-zero. + + 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 de- + scription 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 op- + tions The output formats supported are txt, csv, tsv, and (experimen- + tal) json. + + 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 in- + cludes a commodity name, the new posting amount will be in the new com- + modity; otherwise, it will be in the matched posting amount's commod- + ity. + + 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 + 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 ac- + count 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, also known as money-weighted rate of return) and time-weighted + rate of return (TWR) for your investments for the time period re- + quested. IRR is always annualized due to the way it is computed, but + TWR is reported both as a rate over the chosen reporting period and as + an annual rate. + + 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 be- + comes 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 as- + sets, 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 re- + turn. + + 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, and the + time between them. Investment at a particular fixed interest rate is + going to give you more interest than the same amount invested at the + same interest rate, but made later in time. 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, + so your IRR will be smaller. And if you are adding to your investment, + you will receive bigger absolute gains, which will be a bigger percent- + age of your initial investment, so your IRR will be larger. + + 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 ac- + count for the effect of your in-flows and out-flows, but unlike IRR it + will try to compute the true rate of return of the underlying asset, + compensating for the effect that deposits and withdrawas have on the + apparent rate of growth of your investment. + + 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, and make TWR less sensitive than IRR to the effects of + cash in-flows and out-flows. + + References: + + o Explanation of rate of return + + o Explanation of IRR + + o Explanation of TWR + + o IRR vs TWR + + o Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + stats + Show journal and performance statistics. + + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report + for each report period. + + At the end, it shows (in the terminal) the overall run time and number + of transactions processed per second. Note these are approximate and + will vary based on machine, current load, data size, hledger version, + haskell lib versions, GHC version.. but they may be of interest. The + stats command's run time is similar to that of a single-column balance + report. + + Example: + + $ hledger stats -f examples/1000x1000x10.journal + Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal + Included files : + Transactions span : 2000-01-01 to 2002-09-27 (1000 days) + Last transaction : 2002-09-26 (6995 days ago) + Transactions : 1000 (1.0 per day) + Transactions last 30 days: 0 (0.0 per day) + Transactions last 7 days : 0 (0.0 per day) + Payees/descriptions : 1000 + Accounts : 1000 (depth 10) + Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) + Market prices : 1000 (A) + + Run time : 0.12 s + Throughput : 8342 txns/s + + This command supports the -o/--output-file option (but not -O/--output- + format selection). + + 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 + 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). + +PART 5: COMMON TASKS + Here are some quick examples of how to do some basic tasks with + hledger. + + Getting help + Here's how to list commands and view options and command docs: + + $ hledger # show available commands + $ hledger --help # show common options + $ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version's manual in several formats by + using the help command. Eg: + + $ hledger help # show the hledger manual with info, man or $PAGER (best available) + $ hledger help journal # show the journal topic in the hledger manual + $ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit + https://hledger.org. Chat and mail list support and discussion + archives can be found at https://hledger.org/support. + + Constructing command lines + hledger has a flexible command line interface. We strive to keep it + simple and ergonomic, but if you run into one of the sharp edges de- + scribed in OPTIONS, here are some tips that might help: + + o command-specific options must go after the command (it's fine to put + common options there too: 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 line 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 + (see below). 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 2023.journal + $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile + $ source ~/.profile + $ hledger stats + Main file : /Users/simon/finance/2023.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 LEDGER_FILE + How to set LEDGER_FILE permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for + many people; adapt as needed: + + $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile + $ source ~/.profile + + When correctly configured, in a new terminal window env | grep + LEDGER_FILE will show your file, and so will hledger files. + + On mac, this additional step might be helpful for GUI applications + (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- + ment.plist like + + { + "LEDGER_FILE" : "~/finance/2023.journal" + } + + and then run killall Dock in a terminal window (or restart the ma- + chine). + + On Windows, see https://www.java.com/en/download/help/path.html, or try + running these commands in a powershell window (let us know if it per- + sists across a reboot, and if you need to be an Administrator): + + > CD + > MKDIR finance + > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + 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 re- + cent starting date, like today or the start of the week. You can al- + ways 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: + + 2023-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/2023.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 [2023-02-07]: 2023-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): . + 2023-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 [2023-01-01]: . + + If you're using version control, this could be a good time to commit + the journal. Eg: + + $ git commit -m 'initial balances' 2023.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: + + 2023/1/10 * gift received + assets:cash $20 + income:gifts + + 2023.1.12 * farmers market + expenses:food $13 + assets:cash + + 2023-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 al- + ready-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: + + 2023-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 re- + ported by hledger reg checking -C. This will be easier if you gen- + erally record transaction dates quite similar to your bank's clear- + ing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a live-up- + dating register while you edit the journal: hledger-ui --watch --regis- + ter 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 2023-01-15 and paycheck + + If you're using version control, this can be another good time to com- + mit: + + $ git commit -m 'txns' 2023.journal + + Reporting + Here are some basic reports. + + Show all transactions: + + $ hledger print + 2023-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + + 2023-01-10 * gift received + assets:cash $20 + income:gifts + + 2023-01-12 * farmers market + expenses:food $13 + assets:cash + + 2023-01-15 * paycheck + income:salary + assets:bank:checking $1000 + + 2023-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + + $ hledger accounts --tree + assets + bank + checking + savings + cash + equity + opening/closing balances + expenses + food + misc + income + gifts + salary + liabilities + creditcard + + Show all account totals: + + $ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard + -------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to + depth 2: + + $ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard + -------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple + balance sheet: + + $ hledger bs -2 + Balance Sheet 2023-01-16 + + || 2023-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 2023-01-01-2023-01-16 + + || 2023-01-01-2023-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 + 2023-01-01 opening balances assets:cash $100 $100 + 2023-01-10 gift received assets:cash $20 $120 + 2023-01-12 farmers market assets:cash $-13 $107 + 2023-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + + $ hledger activity -W + 2019-12-30 ***** + 2023-01-06 **** + 2023-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. + +BUGS + We welcome bug reports in the hledger issue tracker (shortcut: + http://bugs.hledger.org), or on the #hledger chat or hledger mail list + (https://hledger.org/support). + + Some known issues and limitations: + + The need to precede add-on command options with -- when invoked from + hledger is awkward. (See Command options, Constructing command lines.) + + A UTF-8-aware system locale must be configured to work with non-ascii + data. (See Unicode characters, Troubleshooting.) + + On Microsoft Windows, depending whether you are running in a CMD window + or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii + characters and colours may not be supported, and the tab key may not be + supported by hledger add. (Running in a WSL window should resolve + these.) + + When processing large data files, hledger uses more memory than Ledger. + + Troubleshooting + Here are some common issues you might encounter when you run hledger, + and how to resolve them (and remember also you can usually get quick + Support): + + PATH issues: I get an error like "No command 'hledger' found" + Depending how you installed hledger, the executables may not be in your + shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- + cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one + of these directories to your shell's PATH, and/or open a new terminal + window. + + LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using + it + o LEDGER_FILE should be a real environment variable, not just a shell + variable. Eg on unix, the command env | grep LEDGER_FILE should show + it. You may need to use export (see https://stackover- + flow.com/a/7411509). + + o You may need to force your shell to see the new configuration. A + simple way is to close your terminal window and open a new one. + + LANG issues: I get errors like "Illegal byte sequence" or "Invalid or + incomplete multibyte or wide character" or "commitAndReleaseBuffer: in- + valid argument (invalid character)" + Programs compiled with GHC (hledger, haskell build tools, etc.) need + the system locale to be UTF-8-aware, or they will fail when they en- + counter non-ascii characters. To fix it, set the LANG environment + variable to a locale which supports UTF-8 and which is installed on + your system. + + On unix, locale -a lists the installed locales. Look for one which + mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8, + fr_FR.utf8. If necessary, use your system package manager to install + one. Then select it by setting the LANG environment variable. Note, + exact spelling and capitalisation of the locale name may be important: + Here's one common way to configure this permanently for your shell: + + $ echo "export LANG=en_US.utf8" >>~/.profile + # close and re-open terminal window + + If you are using Nix (not NixOS) for GHC and Hledger, you might need to + set the LOCALE_ARCHIVE variable: + + $ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile + # close and re-open terminal window + + COMPATIBILITY ISSUES: hledger gives an error with my Ledger file + Not all of Ledger's journal file syntax or feature set is supported. + See hledger and Ledger for full details. + + + +AUTHORS + Simon Michael and contributors. + See http://hledger.org/CREDITS.html + + +COPYRIGHT + Copyright 2007-2023 Simon Michael and contributors. + + +LICENSE + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + +hledger-1.32.1 December 2023 HLEDGER(1) diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2023" "hledger-1.32 " "hledger User Manuals" +.TH "HLEDGER" "1" "December 2023" "hledger-1.32.1 " "hledger User Manuals" @@ -23,7 +23,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP -This manual is for hledger\[aq]s command line interface, version 1.32. +This manual is for hledger\[aq]s command line interface, version 1.32.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well! @@ -2796,6 +2796,8 @@ commodity 1 000 000.0000 ; the no-symbol commodity .EE .PP +Commodities do not have tags (tags in the comment will be ignored). +.PP A commodity directive\[aq]s sample amount must always include a period or comma decimal mark (this rule helps disambiguate decimal marks and digit group marks). @@ -2931,10 +2933,18 @@ Eg: .IP .EX -payee Whole Foods +payee Whole Foods ; a comment .EE .PP -Any indented subdirectives are currently ignored. +Payees do not have tags (tags in the comment will be ignored). +.PP +To declare the empty payee name, use \f[CR]\[dq]\[dq]\f[R]. +.IP +.EX +payee \[dq]\[dq] +.EE +.PP +Ledger-style indented subdirectives, if any, are currently ignored. .SS \f[CR]tag\f[R] directive \f[CR]tag TAGNAME\f[R] .PP @@ -4153,7 +4163,7 @@ else. If you have trouble, see \[dq]Regular expressions\[dq] in the hledger manual (https://hledger.org/hledger.html#regular-expressions). -.PP +.SS What matchers match With record matchers, it\[aq]s important to know that the record matched is not the original CSV record, but a modified one: separators will be converted to commas, and enclosing double quotes (but not enclosing @@ -4169,16 +4179,19 @@ .EX 2023-01-01,Acme, Inc., 1,000 .EE -.PP +.SS Combining matchers When an if block has multiple matchers, they are combined as follows: .IP \[bu] 2 By default they are OR\[aq]d (any one of them can match) .IP \[bu] 2 When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be -AND\[aq]ed with the previous matcher (both of them must match). +AND\[aq]ed with the previous matcher (both of them must match) +.IP \[bu] 2 +When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the +matcher is negated (it may not match). .PP -When a matcher is preceded by an exclamation mark (!), the matcher will -be negated, ie it will exclude CSV records that match. +Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and +\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher). .SS Match groups Matchers can define match groups: parenthesised portions of the regular expression which are available for reference in field assignments. 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.32 +version: 1.32.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 @@ -136,7 +136,7 @@ other-modules: Paths_hledger ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.32" + cpp-options: -DVERSION="1.32.1" build-depends: Decimal >=0.5.1 , Diff >=0.2 @@ -153,7 +153,7 @@ , githash >=0.1.6.2 , hashable >=1.2.4 , haskeline >=0.6 - , hledger-lib ==1.32.* + , hledger-lib >=1.32.1 && <1.33 , lucid , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.6 @@ -188,7 +188,7 @@ hs-source-dirs: app ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.32" + cpp-options: -DVERSION="1.32.1" build-depends: Decimal >=0.5.1 , aeson >=1 && <2.3 @@ -204,7 +204,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib ==1.32.* + , hledger-lib >=1.32.1 && <1.33 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.6 , microlens >=0.4 @@ -239,7 +239,7 @@ hs-source-dirs: test ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.32" + cpp-options: -DVERSION="1.32.1" build-depends: Decimal >=0.5.1 , aeson >=1 && <2.3 @@ -255,7 +255,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib ==1.32.* + , hledger-lib >=1.32.1 && <1.33 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.6 , microlens >=0.4 @@ -304,7 +304,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib ==1.32.* + , hledger-lib >=1.32.1 && <1.33 , html , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.6 diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -23,11491 +23,11519 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.32. -It also describes the common options, file formats and concepts used by -all hledger programs. It might accidentally teach you some -bookkeeping/accounting as well! You don't need to know everything in -here to use hledger productively, but when you have a question about -functionality, this doc should answer it. It is detailed, so do skip -ahead or skim when needed. You can read it on hledger.org, or as an -info manual or man page on your system. You can also get it from -hledger itself with -'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'. - - The main function of the hledger CLI is to read plain text files -describing financial transactions, crunch the numbers, and print a -useful report on the terminal (or save it as HTML, CSV, JSON or SQL). -Many reports are available, as subcommands. hledger will also detect -other 'hledger-*' executables as extra subcommands. - - hledger usually reads from (and appends to) a journal file specified -by the 'LEDGER_FILE' environment variable (defaulting to -'$HOME/.hledger.journal'); or you can specify files with '-f' options. -It can also read timeclock files, timedot files, or any CSV/SSV/TSV file -with a date field. - - Here is a small journal file describing one transaction: - -2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more -_accounts_: bank accounts, your wallet, revenue/expense categories, -people, etc. You can choose any account names you wish, using ':' to -indicate subaccounts. There must be at least two spaces between account -name and amount. Positive amounts are inflow to that account (_debit_), -negatives are outflow from it (_credit_). (Some reports show revenue, -liability and equity account balances as negative numbers as a result; -this is normal.) - - hledger's add command can help you add transactions, or you can -install other data entry UIs like hledger-web or hledger-iadd. For more -extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM -+ vim-ledger, or VS Code + hledger-vscode are some good choices (see -https://hledger.org/editors.html). - - To get started, run 'hledger add' and follow the prompts, or save -some entries like the above in '$HOME/.hledger.journal', then try -commands like: -'hledger print -x' -'hledger aregister assets' -'hledger balance' -'hledger balancesheet' -'hledger incomestatement'. -Run 'hledger' to list the commands. See also the "Starting a journal -file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -* Menu: - -* PART 1 USER INTERFACE:: -* Input:: -* Commands:: -* Options:: -* Command line tips:: -* Output:: -* Environment:: -* PART 2 DATA FORMATS:: -* Journal:: -* CSV:: -* Timeclock:: -* Timedot:: -* PART 3 REPORTING CONCEPTS:: -* Amount formatting parseability:: -* Time periods:: -* Depth:: -* Queries:: -* Pivoting:: -* Generating data:: -* Forecasting:: -* Budgeting:: -* Cost reporting:: -* Value reporting:: -* PART 4 COMMANDS:: -* PART 5 COMMON TASKS:: -* BUGS:: - - -File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: Top - -1 PART 1: USER INTERFACE -************************ - - -File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top - -2 Input -******* - -hledger reads one or more data files, each time you run it. You can -specify a file with '-f', like so - -$ hledger -f FILE print - - Files are most often in hledger's journal format, with the '.journal' -file extension ('.hledger' or '.j' also work); these files describe -transactions, like an accounting general journal. - - When no file is specified, hledger looks for '.hledger.journal' in -your home directory. - - But most people prefer to keep financial files in a dedicated folder, -perhaps with version control. Also, starting a new journal file each -year is common (it's not required, but helps keep things fast and -organised). So we usually configure a different journal file, by -setting the 'LEDGER_FILE' environment variable, to something like -'~/finance/2023.journal'. For more about how to do that on your system, -see Common tasks > Setting LEDGER_FILE. - -* Menu: - -* Data formats:: -* Standard input:: -* Multiple files:: -* Strict mode:: - - -File: hledger.info, Node: Data formats, Next: Standard input, Up: Input - -2.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 '.journal' '.j' '.hledger' - some Ledger journals, for '.ledger' - transactions -'timeclock' timeclock files, for precise '.timeclock' - time logging -'timedot' timedot files, for '.timedot' - approximate time logging -'csv' CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv' - values, for data import '.csv.rules' '.ssv.rules' - '.tsv.rules' - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions -shown above. If it can't recognise the file extension, it assumes -'journal' format. So for non-journal files, it's important to use a -recognised file extension, so as to either read successfully or to show -relevant error messages. - - You can also force a specific reader/format by prefixing the file -path with the format and a colon. Eg, to read a .dat file as csv -format: - -$ hledger -f csv:/some/csv-file.dat stats - - -File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input - -2.2 Standard input -================== - -The file name '-' means standard input: - -$ cat FILE | hledger -f- print - - If reading non-journal data in this way, you'll need to add a file -format prefix, like: - -$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- - - -File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input - -2.3 Multiple files -================== - -You can specify multiple '-f' options, to read multiple files as one big -journal. When doing this, note that certain features (described below) -will be affected: - - * Balance assertions will not see the effect of transactions in - previous files. (Usually this doesn't matter as each file will set - the corresponding opening balances.) - * Some directives will not affect previous or subsequent files. - - If needed, you can work around these by using a single parent file -which includes the others, or concatenating the files into one, eg: 'cat -a.journal b.journal | hledger -f- CMD'. - - -File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input - -2.4 Strict mode -=============== - -hledger checks input files for valid data. By default, the most -important errors are detected, while still accepting easy journal files -without a lot of declarations: - - * Are the input files parseable, with valid syntax ? - * Are all transactions balanced ? - * Do all balance assertions pass ? - - With the '-s'/'--strict' flag, additional checks are performed: - - * Are all accounts posted to, declared with an 'account' directive ? - (Account error checking) - * Are all commodities declared with a 'commodity' directive ? - (Commodity error checking) - * Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks - the ones -listed above and some more. - - -File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top - -3 Commands -********** - -hledger provides various subcommands for getting things done. Most of -these commands do not change the journal file; they just read it and -output a report. A few commands assist with adding data and file -management. - - To show the commands list, run 'hledger' with no arguments. The -commands are described in detail in PART 4: COMMANDS, below. - - To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', - - * CMD is the full command name, or its standard abbreviation shown in - the commands list, or any unambiguous prefix of the name. - - * CMDOPTS are command-specific options, if any. Command-specific - options must be written after the command name. Eg: 'hledger print - -x'. - - * CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit - the data in some way. Eg: 'hledger reg assets:checking'. - - To list a command's options, arguments, and documentation in the -terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. - -* Menu: - -* Add-on commands:: - - -File: hledger.info, Node: Add-on commands, Up: Commands - -3.1 Add-on commands -=================== - -In addition to the built-in commands, you can install _add-on commands_: -programs or scripts named "hledger-SOMETHING", which will also appear in -hledger's commands list. If you used the hledger-install script, you -will have several add-ons installed already. Some more can be found in -hledger's bin/ directory, documented at -https://hledger.org/scripts.html. - - More precisely, add-on commands are programs or scripts in your -shell's PATH, whose name starts with "hledger-" and ends with no -extension or a recognised extension (".bat", ".com", ".exe", ".hs", -".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), -and (on unix and mac) which has executable permission for the current -user. - - You can run add-on commands using hledger, much like built-in -commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'. But note -the double hyphen argument, required before add-on-specific options. -Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'. If this causes -difficulty, you can always run the add-on directly, without using -'hledger': 'hledger-ui --watch' or 'hledger-web --serve'. - - -File: hledger.info, Node: Options, Next: Command line tips, Prev: Commands, Up: Top - -4 Options -********* - -Run 'hledger -h' to see general command line help, and general options -which are common to most hledger commands. These options can be written -anywhere on the command line. They can be grouped into help, input, and -reporting options: - -* Menu: - -* General help options:: -* General input options:: -* General reporting options:: - - -File: hledger.info, Node: General help options, Next: General input options, Up: Options - -4.1 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) - - -File: hledger.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: Options - -4.2 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) - - -File: hledger.info, Node: General reporting options, Prev: General input options, Up: Options - -4.3 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-equity' - - infer conversion equity postings from costs -'--infer-costs' - - infer costs from conversion equity postings -'--infer-market-prices' - - use costs as additional market prices, as if they were P directives -'--forecast' - - generate transactions from periodic rules, between the latest - recorded txn and 6 months from today, or during the specified - PERIOD (= is required). Auto posting rules will be applied to - these transactions as well. Also, in hledger-ui make future-dated - transactions visible. -'--auto' - - generate extra postings by applying auto posting rules to all txns - (not just forecast txns) -'--verbose-tags' - - add visible tags indicating transactions or postings which have - been generated/modified -'--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 line tips, Next: Output, Prev: Options, Up: Top - -5 Command line tips -******************* - -Here are some details useful to know about for hledger command lines -(and elsewhere). Feel free to skip this section until you need it. - -* Menu: - -* Option repetition:: -* Special characters:: -* Unicode characters:: -* Regular expressions:: -* Argument files:: - - -File: hledger.info, Node: Option repetition, Next: Special characters, Up: Command line tips - -5.1 Option repetition -===================== - -If options are repeated in a command line, hledger will generally use -the last (right-most) occurence. - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Option repetition, Up: Command line tips - -5.2 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 - -5.2.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 - -5.2.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 - -5.2.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 - -5.2.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: Command line tips - -5.3 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, Next: Argument files, Prev: Unicode characters, Up: Command line tips - -5.4 Regular expressions -======================= - -A regular expression (regexp) is a small piece of text where certain -characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have -special meanings, forming a tiny language for matching text precisely - -very useful in hledger and elsewhere. To learn all about them, visit -regular-expressions.info. - - hledger supports regexps whenever you are entering a pattern to match -something, eg in query arguments, account aliases, CSV if rules, -hledger-web's search form, hledger-ui's '/' search, etc. You may need -to wrap them in quotes, especially at the command line (see Special -characters above). Here are some examples: - - Account name queries (quoted for command line use): - -Regular expression: Matches: -------------------- ------------------------------------------------------------ -bank assets:bank, assets:bank:savings, expenses:art:banksy, ... -:bank assets:bank:savings, expenses:art:banksy -:bank: assets:bank:savings -'^bank' none of those ( ^ matches beginning of text ) -'bank$' assets:bank ( $ matches end of text ) -'big \$ bank' big $ bank ( \ disables following character's special meaning ) -'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) -'(sav|check)ing' saving or checking ( (|) matches either alternative ) -'saving|checking' saving or checking ( outer parentheses are not needed ) -'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) -'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) -'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) -'b.nk' bank, bonk, b nk, ... ( . matches any character ) - - Some other queries: - -desc:'amazon|amzn|audible' Amazon transactions -cur:EUR amounts with commodity symbol containing EUR -cur:'\$' amounts with commodity symbol containing $ -cur:'^\$$' only $ amounts, not eg AU$ or CA$ -cur:....? amounts with 4-or-more-character symbols -tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 - - Account name aliases: accept '.' instead of ':' as account separator: - -alias /\./=: replaces all periods in account names with colons - - Show multiple top-level accounts combined as one: - ---alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) - - Show accounts with the second-level part removed: - ---alias '/^([^:]+):[^:]+/ = \1' - match a top-level account and a second-level account - and replace those with just the top-level account - ( \1 in the replacement text means "whatever was matched - by the first parenthesised part of the regexp" - - CSV rules: match CSV records containing dining-related MCC codes: - -if \?MCC581[124] - - Match CSV records with a specific amount around the end/start of -month: - -if %amount \b3\.99 -& %date (29|30|31|01|02|03)$ - -* Menu: - -* hledger's regular expressions:: - - -File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions - -5.4.1 hledger's regular expressions ------------------------------------ - -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. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the - replacement string to reference capturing groups in the search - regexp. Otherwise, if you write '\1', it will match the digit '1'. - 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: Argument files, Prev: Regular expressions, Up: Command line tips - -5.5 Argument files -================== - -You can save a set of command line options and arguments in a file, and -then reuse them by writing '@FILENAME' as a command line argument. Eg: -'hledger bal @foo.args'. - - Inside the argument file, each line should contain just one option or -argument. Don't use spaces except inside quotes (or you'll see a -confusing error); write '=' (or nothing) between a flag and its -argument. For the special characters mentioned above, use one less -level of quoting than you would at the command prompt. - - -File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips, Up: Top - -6 Output -******** - -* Menu: - -* Output destination:: -* Output format:: -* Commodity styles:: -* Colour:: -* Box-drawing:: -* Paging:: -* Debug output:: - - -File: hledger.info, Node: Output destination, Next: Output format, Up: Output - -6.1 Output destination -====================== - -hledger commands send their output to the terminal by default. You can -of course redirect this, eg into a file, using standard shell syntax: - -$ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also -provide the '-o/--output-file' option, which does the same thing without -needing the shell. Eg: - -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) - - -File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output - -6.2 Output format -================= - -Some commands offer other kinds of output, not just text on the -terminal. Here are those commands and the formats currently supported: - -- txt csv/tsv html json sql -------------------------------------------------------------------------------- -aregister Y Y Y Y -balance Y _1_ Y _1_ Y _1,2_ Y -balancesheet Y _1_ Y _1_ Y _1_ Y -balancesheetequityY _1_ Y _1_ Y _1_ Y -cashflow Y _1_ Y _1_ Y _1_ Y -incomestatement Y _1_ Y _1_ Y _1_ Y -print Y Y Y Y -register Y Y Y - - * _1 Also affected by the balance commands' '--layout' option._ - * _2 'balance' does not support html output without a report interval - or with '--budget'._ - - The output format is selected by the '-O/--output-format=FMT' option: - -$ hledger print -O csv # print CSV on stdout - - or by the filename extension of an output file specified with the -'-o/--output-file=FILE.FMT' option: - -$ hledger balancesheet -o foo.csv # write CSV to foo.csv - - The '-O' option can be combined with '-o' to override the file -extension, if needed: - -$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - - Some notes about the various output formats: - -* Menu: - -* CSV output:: -* HTML output:: -* JSON output:: -* SQL output:: - - -File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format - -6.2.1 CSV output ----------------- - - * In CSV output, digit group marks (such as thousands separators) are - disabled automatically. - - -File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format - -6.2.2 HTML output ------------------ - - * HTML output can be styled by an optional 'hledger.css' file in the - same directory. - - -File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format - -6.2.3 JSON output ------------------ - - * This is not yet much used; real-world feedback is welcome. - - * Our JSON is rather large and verbose, since it is a faithful - representation of hledger's internal data types. To understand the - JSON, read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. - - * hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can - arise in practice (from automatically-calculated transaction - prices), and would break most JSON consumers. So in JSON, we show - quantities as simple Numbers with at most 10 decimal places. We - don't limit the number of integer digits, but that part is under - your control. We hope this approach will not cause problems in - practice; if you find otherwise, please let us know. (Cf #1195) - - -File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format - -6.2.4 SQL output ----------------- - - * This is not yet much used; real-world feedback is welcome. - - * SQL output is expected to work at least with SQLite, MySQL and - Postgres. - - * For SQLite, it will be more useful if you modify the generated 'id' - field to be a PRIMARY KEY. Eg: - - $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - - * SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables - created via SQL output of hledger, you would probably want to - either clear tables of existing data (via 'delete' or 'truncate' - SQL statements) or drop tables completely as otherwise your - postings will be duped. - - -File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output - -6.3 Commodity styles -==================== - -When displaying amounts, hledger infers a standard display style for -each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a '-c/--commodity-style' option -(except for cost amounts and amounts displayed by the 'print' command, -which are always displayed with all decimal digits). For example, the -following will force dollar amounts to be displayed as shown: - -$ hledger print -c '$1.000,0' - - This option can repeated to set the display style for multiple -commodities/currencies. Its argument is as described in the commodity -directive. - - -File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output - -6.4 Colour -========== - -In terminal output, some commands can produce colour when the terminal -supports it: - - * if the '--color/--colour' option is given a value of 'yes' or - 'always' (or 'no' or 'never'), colour will (or will not) be used; - * otherwise, if the 'NO_COLOR' environment variable is set, colour - will not be used; - * otherwise, colour will be used if the output (terminal or file) - supports it. - - -File: hledger.info, Node: Box-drawing, Next: Paging, Prev: Colour, Up: Output - -6.5 Box-drawing -=============== - -In terminal output, you can enable unicode box-drawing characters to -render prettier tables: - - * if the '--pretty' option is given a value of 'yes' or 'always' (or - 'no' or 'never'), unicode characters will (or will not) be used; - * otherwise, unicode characters will not be used. - - -File: hledger.info, Node: Paging, Next: Debug output, Prev: Box-drawing, Up: Output - -6.6 Paging -========== - -When showing long output in the terminal, hledger will try to use the -pager specified by the 'PAGER' environment variable, or 'less', or -'more'. (A pager is a helper program that shows one page at a time -rather than scrolling everything off screen). Currently it does this -only for help output, not for reports; specifically, - - * when listing commands, with 'hledger' - * when showing help with 'hledger [CMD] --help', - * when viewing manuals with 'hledger help' or 'hledger --man'. - - Note the pager is expected to handle ANSI codes, which hledger uses -eg for bold emphasis. For the common pager 'less' (and its 'more' -compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment -variables to make this work. If you use a different pager, you might -need to configure it similarly, to avoid seeing junk on screen (let us -know). Otherwise, you can set the 'NO_COLOR' environment variable to 1 -to disable all ANSI output (see Colour). - - -File: hledger.info, Node: Debug output, Prev: Paging, Up: Output - -6.7 Debug output -================ - -We intend hledger to be relatively easy to troubleshoot, introspect and -develop. You can add '--debug[=N]' to any hledger command line to see -additional debug output. N ranges from 1 (least output, the default) to -9 (maximum output). Typically you would start with 1 and increase until -you are seeing enough. Debug output goes to stderr, and is not affected -by '-o/--output-file' (unless you redirect stderr to stdout, eg: -'2>&1'). It will be interleaved with normal output, which can help -reveal when parts of the code are evaluated. To capture debug output in -a log file instead, you can usually redirect stderr, eg: - -hledger bal --debug=3 2>hledger.log - - -File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top - -7 Environment -************* - -These environment variables affect hledger: - - *COLUMNS* This is normally set by your terminal; some hledger -commands ('register') will format their output to this width. If not -set, they will try to use the available terminal width. - - *LEDGER_FILE* The main journal file to use when not specified with -'-f/--file'. Default: '$HOME/.hledger.journal'. - - *NO_COLOR* If this environment variable is set (with any value), -hledger will not use ANSI color codes in terminal output, unless -overridden by an explicit '--color/--colour' option. - - -File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top - -8 PART 2: DATA FORMATS -********************** - - -File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top - -9 Journal -********* - -hledger's default file format, representing a General Journal. Here's a -cheatsheet/mini-tutorial, or you can skip ahead to About journal format. - -* Menu: - -* Journal cheatsheet:: -* About journal format:: -* Comments:: -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Transaction comments:: -* Postings:: -* Account names:: -* Amounts:: -* Costs:: -* Balance assertions:: -* Posting comments:: -* Tags:: -* Directives:: -* account directive:: -* alias directive:: -* commodity directive:: -* decimal-mark directive:: -* include directive:: -* P directive:: -* payee directive:: -* tag directive:: -* Periodic transactions:: -* Auto postings:: -* Other syntax:: - - -File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal - -9.1 Journal cheatsheet -====================== - -# Here is the main syntax of hledger's journal format -# (omitting extra Ledger compatibility syntax). -# hledger journals contain comments, directives, and transactions, in any order: - -############################################################################### -# 1. Comment lines are for notes or temporarily disabling things. -# They begin with #, ;, or a line containing the word "comment". - -# hash comment line -; semicolon comment line -comment -These lines -are commented. -end comment - -# Some but not all hledger entries can have same-line comments attached to them, -# from ; (semicolon) to end of line. - -############################################################################### -# 2. Directives modify parsing or reports in some way. -# They begin with a word or letter (or symbol). - -account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. -account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) -alias chkg = assets:checking -commodity $0.00 -decimal-mark . -include /dev/null -payee Whole Foods -P 2022-01-01 AAAA $1.40 -~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - -############################################################################### -# 3. Transactions are what it's all about; they are dated events, -# usually describing movements of money. -# They begin with a date. - -# DATE DESCRIPTION ; This is a transaction comment. -# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. -# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. -# ; ^^ At least 2 spaces between account and amount. -# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - -2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - -2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - -2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - -2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - -2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - -1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - -2022.01.01 These date -2022/1/1 formats are -12/31 also allowed (but consistent YYYY-MM-DD is recommended). - - -File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal - -9.2 About journal format -======================== - -hledger's usual data source is a plain text file containing journal -entries in hledger journal format. This file represents a standard -accounting general journal. I use file names ending in '.journal', but -that's not required. The journal file contains a number of transaction -entries, each describing a transfer of money (or any commodity) between -two or more named accounts, in a simple format readable by both hledger -and humans. - - hledger's journal format is compatible with most of Ledger's journal -format, but not all of it. The differences and interoperation tips are -described at hledger and Ledger. With some care, and by avoiding -incompatible features, you can keep your hledger journal readable by -Ledger and vice versa. This can useful eg for comparing the behaviour -of one app against the other. - - You can use hledger without learning any more about this file; just -use the add or web or import commands to create and update it. - - Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor addons -such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and -hledger-vscode for Visual Studio Code, make this easier, adding colour, -formatting, tab completion, and useful commands. See Editor -configuration at hledger.org for the full list. - - Here's a description of each part of the file format (and hledger's -data model). - - A hledger journal file can contain three kinds of thing: file -comments, transactions, and/or directives (counting periodic transaction -rules and auto posting rules as directives). - - -File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal - -9.3 Comments -============ - -Lines in the journal will be ignored if they begin with a hash ('#') or -a semicolon (';'). (See also Other syntax.) hledger will also ignore -regions beginning with a 'comment' line and ending with an 'end comment' -line (or file end). Here's a suggestion for choosing between them: - - * '#' for top-level notes - * ';' for commenting out things temporarily - * 'comment' for quickly commenting large regions (remember it's - there, or you might get confused) - - Eg: - -# a comment line -; another commentline -comment -A multi-line comment block, -continuing until "end comment" directive -or the end of the current file. -end comment - - Some hledger entries can have same-line comments attached to them, -from ; (semicolon) to end of line. See Transaction comments, Posting -comments, and Account comments below. - - -File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal - -9.4 Transactions -================ - -Transactions are the main unit of information in a journal file. They -represent events, typically a movement of some quantity of commodities -between two or more named accounts. - - Each transaction is recorded as a journal entry, beginning with a -simple date in column 0. This can be followed by any of the following -optional fields, separated by spaces: - - * a status character (empty, '!', or '*') - * a code (any short number or text, enclosed in parentheses) - * a description (any remaining text until end of line or a semicolon) - * a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - * 0 or more indented _posting_ lines, describing what was transferred - and the accounts involved (indented comment lines are also allowed, - but not blank lines or non-indented lines). - - Here's a simple journal file containing one transaction: - -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - -File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal - -9.5 Dates -========= - -* Menu: - -* Simple dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates - -9.5.1 Simple dates ------------------- - -Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or -'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may -be omitted, in which case it will be inferred from the context: the -current transaction, the default year set with a 'Y' directive, or the -current date when the command is run. Some examples: '2010-01-31', -'2010/01/31', '2010.1.31', '1/31'. - - (The UI also accepts simple dates, as well as the more flexible smart -dates documented in the hledger manual.) - - -File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates - -9.5.2 Posting dates -------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like 'date:DATE'. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction's date. -The 'date:' tag must have a valid simple date value if it is present, eg -a 'date:' tag with no value is not allowed. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal - -9.6 Status -========== - -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: - -mark status - ------------------ - unmarked -'!' pending -'*' cleared - - When reporting, you can filter by status with the '-U/--unmarked', -'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', -and 'status:*' queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" -state is called "uncleared". As of hledger 1.3 we have renamed it to -unmarked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching -pending, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. Some editor modes provide highlighting and -shortcuts for working with status. Eg in Emacs ledger-mode, you can -toggle transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to -you. Here's one suggestion: - -status meaning --------------------------------------------------------------------------- -uncleared recorded but not yet reconciled; needs review -pending tentatively reconciled (if needed, eg during a big - reconciliation) -cleared complete, reconciled as far as possible, and considered - correct - - With this scheme, you would use '-PC' to see the current balance at -your bank, '-U' to see things which will probably hit your bank soon -(like uncashed checks), and no flags to see the most up-to-date state of -your finances. - - -File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal - -9.7 Code -======== - -After the status mark, but before the description, you can optionally -write a transaction "code", enclosed in parentheses. This is a good -place to record a check number, or some other important transaction id -or reference number. - - -File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal - -9.8 Description -=============== - -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -9.8.1 Payee and note --------------------- - -You can optionally include a '|' (pipe) character in descriptions to -subdivide the description into separate fields for payee/payer name on -the left (up to the first '|') and an additional note field on the right -(after the first '|'). This may be worthwhile if you need to do more -precise querying and pivoting by payee or by note. - - -File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal - -9.9 Transaction comments -======================== - -Text following ';', after a transaction description, and/or on indented -lines immediately below it, form comments for that transaction. They -are reproduced by 'print' but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal - -9.10 Postings -============= - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - * (optional) a status character (empty, '!', or '*'), followed by a - space - * (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - * (optional) *two or more spaces* or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are -being removed. - - The amounts within a transaction must always sum up to zero. As a -convenience, one amount may be left blank; it will be inferred so as to -balance the transaction. - - Be sure to note the unusual two-space delimiter between account name -and amount. This makes it easy to write account names containing -spaces. But if you accidentally leave only one space (or tab) before -the amount, the amount will be considered part of the account name. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal - -9.11 Account names -================== - -Accounts are the main way of categorising things in hledger. As in -Double Entry Bookkeeping, they can represent real world accounts (such -as a bank account), or more abstract categories such as "money borrowed -from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are 'assets', -'liabilities', 'equity', 'revenues', 'expenses'. (You might see these -referred to as A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. For example, from the account names 'assets:bank:checking' -and 'expenses:food', hledger will infer this hierarchy of five accounts: - -assets -assets:bank -assets:bank:checking -expenses -expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - -assets - bank - checking -expenses - food - - hledger reports can summarise the account tree to any depth, so you -can go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. Note, when an account name and an -amount are written on the same line, they must be separated by *two or -more spaces* (or tabs). - - Parentheses or brackets enclosing the full account name indicate -virtual postings, described below. Parentheses or brackets internal to -the account name have no special meaning. - - Account names can be altered temporarily or permanently by account -aliases. - - -File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal - -9.12 Amounts -============ - -After the account name, there is usually an amount. (Important: between -account name and amount, there must be *two or more spaces*.) - - hledger's amount format is flexible, supporting several international -formats. Here are some examples. Amounts have a number (the -"quantity"): - -1 - - ..and usually a currency symbol or commodity name (more on this -below), to the left or right of the quantity, with or without a -separating space: - -$1 -4000 AAPL -3 "green apples" - - Amounts can be preceded by a minus sign (or a plus sign, though plus -is the default), The sign can be written before or after a left-side -commodity symbol: - --$1 -$-1 - - One or more spaces between the sign and the number are acceptable -when parsing (but they won't be displayed in output): - -+ $1 -$- 1 - - Scientific E notation is allowed: - -1E-6 -EUR 1E3 - -* Menu: - -* Decimal marks digit group marks:: -* Commodity:: -* Directives influencing number parsing and display:: -* Commodity display style:: -* Rounding:: - - -File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts - -9.12.1 Decimal marks, digit group marks ---------------------------------------- - -A _decimal mark_ can be written as a period or a comma: - -1.23 -1,23 - - 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 - - hledger is not biased towards period or comma decimal marks, so a -number containing just one period or comma, like '1,000' or '1.000', is -ambiguous. In such cases hledger assumes it is a decimal mark, parsing -both of these as 1. - - To disambiguate these and ensure accurate number parsing, especially -if you use digit group marks, we recommend declaring the decimal mark. -You can declare it for each file with 'decimal-mark' directives, or for -each commodity with 'commodity' directives (described below). - - -File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts - -9.12.2 Commodity ----------------- - -Amounts in hledger have both a "quantity", which is a signed decimal -number, and a "commodity", which is a currency symbol, stock ticker, or -any word or phrase describing something you are tracking. - - If the commodity name contains non-letters (spaces, numbers, or -punctuation), you must always write it inside double quotes ('"green -apples"', '"ABC123"'). - - If you write just a bare number, that too will have a commodity, with -name '""'; we call that the "no-symbol commodity". - - Actually, hledger combines these single-commodity amounts into more -powerful multi-commodity amounts, which are what it works with most of -the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 -TSLA'. In practice, you will only see multi-commodity amounts in -hledger's output; you can't write them directly in the journal file. - - (If you are writing scripts or working with hledger's internals, -these are the 'Amount' and 'MixedAmount' types.) - - -File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts - -9.12.3 Directives influencing number parsing and display --------------------------------------------------------- - -You can add 'decimal-mark' and 'commodity' directives to the journal, to -declare and control these things more explicitly and precisely. These -are described below, but here's a quick example: - -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 - - -File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts - -9.12.4 Commodity display style ------------------------------- - -For the amounts in each commodity, hledger chooses a consistent display -style (symbol placement, decimal mark and digit group marks, number of -decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a 'D' directive declaring a default commodity, that -commodity symbol and amount format is applied to all no-symbol amounts -in the journal. - - Then each commodity's display style is determined from its -'commodity' directive. We recommend always declaring commodities with -'commodity' directives, since they help ensure consistent display styles -and precisions, and bring other benefits such as error checking for -commodity symbols. - - But if a 'commodity' directive is not present, hledger infers a -commodity's display styles from its amounts as they are written in the -journal (excluding cost amounts and amounts in periodic transaction -rules or auto posting rules). It uses - - * the symbol placement and decimal mark of the first amount seen - * the digit group marks of the first amount with digit group marks - * and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a -default style, like '$1000.00' (symbol on the left with no space, period -as decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -'-c/--commodity-style' command line option. - - -File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts - -9.12.5 Rounding ---------------- - -Amounts are stored internally as decimal numbers with up to 255 decimal -places. They are displayed with their original journal precisions by -print and print-like reports, and rounded to their display precision -(the number of decimal digits specified by the commodity display style) -by other reports. When rounding, hledger uses banker's rounding (it -rounds to the nearest even digit). So eg 0.5 displayed with zero -decimal digits appears as "0". - - -File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal - -9.13 Costs -========== - -After a posting amount, you can note its cost (when buying) or selling -price (when selling) in another commodity, by writing either '@ -UNITPRICE' or '@@ TOTALPRICE' after it. This indicates a conversion -transaction, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, -discussions, or code; that term was directionally neutral and reminded -that it is a price specific to a transaction, but we now just call it -"cost", with the understanding that the transaction could be a purchase -or a sale.) - - Costs are usually written explicitly with '@' or '@@', but can also -be inferred automatically for simple multi-commodity transactions. -Note, if costs are inferred, the order of postings is significant; the -first posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign -currency in hledger, using the cost notation either explicitly or -implicitly: - - 1. Write the price per unit, as '@ UNITPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as '@@ TOTALPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction. - Note the effect of posting order: the price is added to first - posting, making it '€100 @@ $135', as in example 2: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the '-B/--cost' -flag; this is discussed more in the Cost reporting section. - - Note that the cost normally should be a positive amount, though it's -not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. - -* Menu: - -* Other cost/lot notations:: - - -File: hledger.info, Node: Other cost/lot notations, Up: Costs - -9.13.1 Other cost/lot notations -------------------------------- - -A slight digression for Ledger and Beancount users. Ledger has a number -of cost/lot-related notations: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a conversion rate, as in hledger - * when buying, also creates a lot than can be selected at - selling time - - * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) - * like the above, but also means "this cost was exceptional, - don't use it when inferring market prices". - - Currently, hledger treats the above like '@' and '@@'; the -parentheses are ignored. - - * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) - * when buying, means "this cost is also the fixed price, don't - let it fluctuate in value reports" - - * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) - * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', - also creates a lot - * when selling, combined with '@ ...', specifies an investment - lot by its cost basis; does not check if that lot is present - - * and related: '[YYYY/MM/DD]' (lot date) - * when buying, attaches this acquisition date to the lot - * when selling, selects a lot by its acquisition date - - * '(SOME TEXT)' (lot note) - * when buying, attaches this note to the lot - * when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. (This can break transaction -balancing.) - - For Beancount users, the notation and behaviour is different: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a cost without creating a lot, as in hledger - * when buying (augmenting) or selling (reducing) a lot, combined - with '{...}': documents the cost/selling price (not used for - transaction balancing) - - * '{UNITCOST}' and '{{TOTALCOST}}' - * when buying (augmenting), expresses the cost for transaction - balancing, and also creates a lot with this cost basis - attached - * when selling (reducing), - * selects a lot by its cost basis - * raises an error if that lot is not present or can not be - selected unambiguously (depending on booking method - configured) - * expresses the selling price for transaction balancing - - Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation -but ignores it. - - * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, - "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. - - Currently, hledger rejects these. - - -File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal - -9.14 Balance assertions -======================= - -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, '= EXPECTEDBALANCE' following a posting's -amount. Eg here we assert the expected dollar balance in accounts a and -b after each posting: - -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the '-I/--ignore-assertions' flag, which can be useful for -troubleshooting or for reading Ledger files. (Note: this flag currently -does not disable balance assignments, described below). - -* Menu: - -* Assertions and ordering:: -* Assertions and multiple included files:: -* Assertions and multiple -f files:: -* Assertions and commodities:: -* Assertions and prices:: -* Assertions and subaccounts:: -* Assertions and virtual postings:: -* Assertions and auto postings:: -* Assertions and precision:: - - -File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions - -9.14.1 Assertions and ordering ------------------------------- - -hledger sorts an account's postings and assertions first by date and -then (for postings on the same day) by parse order. Note this is -different from Ledger, which sorts assertions only by parse order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder -differently-dated transactions within the journal. But if you reorder -same-dated transactions or postings, assertions might break and require -updating. This order dependence does bring an advantage: precise -control over the order of postings and assertions within a day, so you -can assert intra-day balances. - - -File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions - -9.14.2 Assertions and multiple included files ---------------------------------------------- - -Multiple files included with the 'include' directive are processed as if -concatenated into one file, preserving their order and the posting order -within each file. It means that balance assertions in later files will -see balance from earlier files. - - And if you have multiple postings to an account on the same day, -split across multiple files, and you want to assert the account's -balance on that day, you'll need to put the assertion in the right file -- the last one in the sequence, probably. - - -File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions - -9.14.3 Assertions and multiple -f files ---------------------------------------- - -Unlike 'include', when multiple files are specified on the command line -with multiple '-f/--file' options, balance assertions will not see -balance from earlier files. This can be useful when you do not want -problems in earlier files to disrupt valid assertions in later files. - - If you do want assertions to see balance from earlier files, use -'include', or concatenate the files temporarily. - - -File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions - -9.14.4 Assertions and commodities ---------------------------------- - -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity's balance within the -(possibly multi-commodity) account balance. This is how assertions work -in Ledger also. We could call this a "partial" balance assertion. - - To assert the balance of more than one commodity in an account, you -can write multiple postings, each asserting one commodity's balance. - - You can make a stronger "total" balance assertion by writing a double -equals sign ('== EXPECTEDBALANCE'). This asserts that there are no -other commodities in the account besides the asserted one (or at least, -that their balance is 0). - -2013/1/1 - a $1 - a 1€ - b $-1 - c -1€ - -2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1€ - b 0 == $-1 - c 0 == -1€ - -2013/1/3 ; This assertion fails as 'a' also contains 1€ - a 0 == $1 - - It's not yet possible to make a complete assertion about a balance -that has multiple commodities. One workaround is to isolate each -commodity into its own subaccount: - -2013/1/1 - a:usd $1 - a:euro 1€ - b - -2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1€ - - -File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions - -9.14.5 Assertions and prices ----------------------------- - -Balance assertions ignore costs, and should normally be written without -one: - -2019/1/1 - (a) $1 @ €1 = $1 - - We do allow prices to be written there, however, and print shows -them, even though they don't affect whether the assertion passes or -fails. This is for backward compatibility (hledger's close command used -to generate balance assertions with prices), and because balance -_assignments_ do use them (see below). - - -File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions - -9.14.6 Assertions and subaccounts ---------------------------------- - -The balance assertions above ('=' and '==') do not count the balance -from subaccounts; they check the account's exclusive balance only. You -can assert the balance including subaccounts by writing '=*' or '==*', -eg: - -2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 - - -File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions - -9.14.7 Assertions and virtual postings --------------------------------------- - -Balance assertions always consider both real and virtual postings; they -are not affected by the '--real/-R' flag or 'real:' query. - - -File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions - -9.14.8 Assertions and auto postings ------------------------------------ - -Balance assertions _are_ affected by the '--auto' flag, which generates -auto postings, which can alter account balances. Because auto postings -are optional in hledger, accounts affected by them effectively have two -balances. But balance assertions can only test one or the other of -these. So to avoid making fragile assertions, either: - - * assert the balance calculated with '--auto', and always use - '--auto' with that file - * or assert the balance calculated without '--auto', and never use - '--auto' with that file - * or avoid balance assertions on accounts affected by auto postings - (or avoid auto postings entirely). - - -File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions - -9.14.9 Assertions and precision -------------------------------- - -Balance assertions compare the exactly calculated amounts, which are not -always what is shown by reports. Eg a commodity directive may limit the -display precision, but this will not affect balance assertions. Balance -assertion failure messages show exact amounts. - - -File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal - -9.15 Posting comments -===================== - -Text following ';', at the end of a posting line, and/or on indented -lines immediately below it, form comments for that posting. They are -reproduced by 'print' but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - -File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal - -9.16 Tags -========= - -Tags are a way to add extra labels or labelled data to transactions, -postings, or accounts, which you can then search or pivot on. - - They are written as a word (optionally hyphenated) immediately -followed by a full colon, in a transaction or posting or account -directive's comment. (This is an exception to the usual rule that -things in comments are ignored.) Eg, here four different tags are -recorded: one on the checking account, two on the transaction, and one -on the expenses posting: - -account assets:checking ; accounttag: - -2017/1/16 bought groceries ; transactiontag-1: - ; transactiontag-2: - assets:checking $-1 - expenses:food $1 ; postingtag: - - Postings also inherit tags from their transaction and their account. -And transactions also acquire tags from their postings (and postings' -accounts). So in the example above, the expenses posting effectively -has all four tags (by inheriting from account and transaction), and the -transaction also has all four tags (by acquiring from the expenses -posting). - - You can list tag names with 'hledger tags [NAMEREGEX]', or match by -tag name with a 'tag:NAMEREGEX' query. - -* Menu: - -* Tag values:: - - -File: hledger.info, Node: Tag values, Up: Tags - -9.16.1 Tag values ------------------ - -Tags can have a value, which is any text after the colon up until a -comma or end of line (with surrounding whitespace removed). Note this -means that hledger tag values can not contain commas. Eg in the -following posting, the three tags' values are "value 1", "value 2", and -"" (empty) respectively: - - expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - - Note that tags can be repeated, and are additive rather than -overriding: when the same tag name is seen again with a new value, the -new name:value pair is added to the tags. (It is not possible to -override a tag's value or remove a tag.) - - You can list a tag's values with 'hledger tags TAGNAME --values', or -match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query. - - -File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal - -9.17 Directives -=============== - -Besides transactions, there is something else you can put in a 'journal' -file: directives. These are declarations, beginning with a keyword, -that modify hledger's behaviour. Some directives can have more specific -subdirectives, indented below them. hledger's directives are similar to -Ledger's in many cases, but there are also many differences. Directives -are not required, but can be useful. Here are the main directives: - -purpose directive --------------------------------------------------------------------------- -*READING DATA:* -Rewrite account names 'alias' -Comment out sections of the file 'comment' -Declare file's decimal mark, to help 'decimal-mark' -parse amounts accurately -Include other data files 'include' -*GENERATING DATA:* -Generate recurring transactions or '~' -budget goals -Generate extra postings on existing '=' -transactions -*CHECKING FOR ERRORS:* -Define valid entities to provide more 'account', 'commodity', -error checking 'payee', 'tag' -*REPORTING:* -Declare accounts' type and display 'account' -order -Declare commodity display styles 'commodity' -Declare market prices 'P' - -* Menu: - -* Directives and multiple files:: -* Directive effects:: - - -File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives - -9.17.1 Directives and multiple files ------------------------------------- - -Directives vary in their scope, ie which journal entries and which input -files they affect. Most often, a directive will affect the following -entries and included files if any, until the end of the current file - -and no further. You might find this inconvenient! For example, 'alias' -directives do not affect parent or sibling files. But there are usually -workarounds; for example, put 'alias' directives in your top-most file, -before including other files. - - The restriction, though it may be annoying at first, is in a good -cause; it allows reports to be stable and deterministic, independent of -the order of input. Without it, reports could show different numbers -depending on the order of -f options, or the positions of include -directives in your files. - - -File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives - -9.17.2 Directive effects ------------------------- - -Here are all hledger's directives, with their effects and scope -summarised - nine main directives, plus four others which we consider -non-essential: - -directivewhat it does ends - at - file - end? ---------------------------------------------------------------------------- -*'account'*Declares an account, for checking all entries in all files; andN - its display order and type. Subdirectives: any text, ignored. -*'alias'*Rewrites account names, in following entries until end of Y - current file or 'end aliases'. Command line equivalent: - '--alias' -*'comment'*Ignores part of the journal file, until end of current file orY - 'end comment'. -*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N - all amounts in all files 2. the decimal mark for parsing - amounts of this commodity, in the following entries until end of - current file (if there is no 'decimal-mark' directive) 3. and - the display style for amounts of this commodity 4. which is - also the precision to use for balanced-transaction checking in - this commodity. Takes precedence over 'D'. Subdirectives: - 'format' (Ledger-compatible syntax). Command line equivalent: - '-c/--commodity-style' -*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y - commodities in following entries until next 'decimal-mark' or - end of current file. Included files can override. Takes - precedence over 'commodity' and 'D'. -*'include'*Includes entries and directives from another file, as if theyN - were written inline. Command line alternative: multiple - '-f/--file' -*'payee'*Declares a payee name, for checking all entries in all files. N -*'P'*Declares the market price of a commodity on some date, for value N - reports. -*'~'*Declares a periodic transaction rule that generates future N -(tilde)transactions with '--forecast' and budget goals with 'balance - --budget'. -Other -syntax: -*'applyPrepends a common parent account to all account names, in Y -account'*following entries until end of current file or 'end apply - account'. -*'D'*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no 'commodity' directive for this commodity: its - decimal mark, balancing precision, and display style, as above. -*'Y'*Sets a default year to use for any yearless dates, in following Y - entries until end of current file. -*'='*Declares an auto posting rule that generates extra postings on partly -(equals)matched transactions with '--auto', in current, parent, and - child files (but not sibling files, see #1212). -*OtherOther directives from Ledger's file format are accepted but -Ledgerignored. -directives* - - -File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal - -9.18 'account' directive -======================== - -'account' directives can be used to declare accounts (ie, the places -that amounts are transferred from and to). Though not required, these -declarations can provide several benefits: - - * They can document your intended chart of accounts, providing a - reference. - * In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - * They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - * They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - * They can store additional account information as comments, or as - tags which can be used to filter or pivot reports. - * They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - - They are written as the word 'account' followed by a hledger-style -account name, eg: - -account assets:bank:checking - - Note, however, that accounts declared in account directives are not -allowed to have surrounding brackets and parentheses, unlike accounts -used in postings. So the following journal will not parse: - -account (assets:bank:checking) - -* Menu: - -* Account comments:: -* Account subdirectives:: -* Account error checking:: -* Account display order:: -* Account types:: - - -File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive - -9.18.1 Account comments ------------------------ - -Text following *two or more spaces* and ';' at the end of an account -directive line, and/or following ';' on indented lines immediately below -it, form comments for that account. They are ignored except they may -contain tags, which are not ignored. - - The two-space requirement for same-line account comments is because -';' is allowed in account names. - -account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - -File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive - -9.18.2 Account subdirectives ----------------------------- - -Ledger-style indented subdirectives are also accepted, but currently -ignored: - -account assets:bank:checking - format subdirective is ignored - - -File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive - -9.18.3 Account error checking ------------------------------ - -By default, accounts need not be declared; they come into existence when -a posting references them. This is convenient, but it means hledger -can't warn you when you mis-spell an account name in the journal. -Usually you'll find that error later, as an extra account in balance -reports, or an incorrect balance when reconciling. - - In strict mode, enabled with the '-s'/'--strict' flag, hledger will -report an error if any transaction uses an account name that has not -been declared by an account directive. Some notes: - - * The declaration is case-sensitive; transactions must use the - correct account name capitalisation. - * The account directive's scope is "whole file and below" (see - directives). This means it affects all of the current file, and - any files it includes, but not parent or sibling files. The - position of account directives within the file does not matter, - though it's usual to put them at the top. - * Accounts can only be declared in 'journal' files, but will affect - included files of all types. - * It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - -File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive - -9.18.4 Account display order ----------------------------- - -The order in which account directives are written influences the order -in which accounts appear in reports, hledger-ui, hledger-web etc. By -default accounts appear in alphabetical order, but if you add these -account directives to the journal file: - -account assets -account liabilities -account equity -account revenues -account expenses - - those accounts will be displayed in declaration order: - -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses - - Any undeclared accounts are displayed last, in alphabetical order. - - Sorting is done at each level of the account tree, within each group -of sibling accounts under the same parent. And currently, this -directive: - -account other:zoo - - would influence the position of 'zoo' among 'other''s subaccounts, -but not the position of 'other' among the top-level accounts. This -means: - - * you will sometimes declare parent accounts (eg 'account other' - above) that you don't intend to post to, just to customize their - display order - * sibling accounts stay together (you couldn't display 'x:y' in - between 'a:b' and 'a:c'). - - -File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive - -9.18.5 Account types --------------------- - -hledger knows that accounts come in several types: assets, liabilities, -expenses and so on. This enables easy reports like balancesheet and -incomestatement, and filtering by account type with the 'type:' query. - - As a convenience, hledger will detect these account types -automatically if you are using common english-language top-level account -names (described below). But generally we recommend you declare types -explicitly, by adding a 'type:' tag to your top-level account -directives. Subaccounts will inherit the type of their parent. The -tag's value should be one of the five main account types: - - * 'A' or 'Asset' (things you own) - * 'L' or 'Liability' (things you owe) - * 'E' or 'Equity' (investment/ownership; balanced counterpart of - assets & liabilities) - * 'R' or 'Revenue' (what you received money from, AKA income; - technically part of Equity) - * 'X' or 'Expense' (what you spend money on; technically part of - Equity) - - or, it can be (these are used less often): - - * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the - cashflow report) - * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost - reporting).) - - Here is a typical set of account type declarations: - -account assets ; type: A -account liabilities ; type: L -account equity ; type: E -account revenues ; type: R -account expenses ; type: X - -account assets:bank ; type: C -account assets:cash ; type: C - -account equity:conversion ; type: V - - Here are some tips for working with account types. - - * The rules for inferring types from account names are as follows. - These are just a convenience that sometimes help new users get - going; if they don't work for you, just ignore them and declare - your account types. See also Regular expressions. - - If account's name contains this (CI) regular expression: | its type is: - --------------------------------------------------------------------|------------- - ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash - ^assets?(:|$) | Asset - ^(debts?|liabilit(y|ies))(:|$) | Liability - ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion - ^equity(:|$) | Equity - ^(income|revenue)s?(:|$) | Revenue - ^expenses?(:|$) | Expense - - * If you declare any account types, it's a good idea to declare an - account for all of the account types, because a mixture of declared - and name-inferred types can disrupt certain reports. - - * Certain uses of account aliases can disrupt account types. See - Rewriting accounts > Aliases and account types. - - * As mentioned above, subaccounts will inherit a type from their - parent account. More precisely, an account's type is decided by - the first of these that exists: - - 1. A 'type:' declaration for this account. - 2. A 'type:' declaration in the parent accounts above it, - preferring the nearest. - 3. An account type inferred from this account's name. - 4. An account type inferred from a parent account's name, - preferring the nearest parent. - 5. Otherwise, it will have no type. - - * For troubleshooting, you can list accounts and their types with: - - $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] - - -File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal - -9.19 'alias' directive -====================== - -You can define account alias rules which rewrite your account names, or -parts of them, before generating reports. This can be useful for: - - * expanding shorthand account names to their full form, allowing - easier data entry and a less verbose journal - * adapting old journals to your current chart of accounts - * experimenting with new account organisations, like a new hierarchy - * combining two accounts into one, eg to see their sum or difference - on one line - * customising reports - - Account aliases also rewrite account names in account directives. -They do not affect account names being entered via hledger add or -hledger-web. - - Account aliases are very powerful. They are generally easy to use -correctly, but you can also generate invalid account names with them; -more on this below. - - See also Rewrite account names. - -* Menu: - -* Basic aliases:: -* Regex aliases:: -* Combining aliases:: -* Aliases and multiple files:: -* end aliases directive:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive - -9.19.1 Basic aliases --------------------- - -To set an account alias, use the 'alias' directive in your journal file. -This affects all subsequent journal entries in the current file or its -included files (but note: not sibling or parent files). The spaces -around the = are optional: - -alias OLD = NEW - - Or, you can use the '--alias 'OLD=NEW'' option on the command line. -This affects all entries. It's useful for trying out aliases -interactively. - - OLD and NEW are case sensitive full account names. hledger will -replace any occurrence of the old account name with the new one. -Subaccounts are also affected. Eg: - -alias checking = assets:bank:wells fargo:checking -; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - -File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive - -9.19.2 Regex aliases --------------------- - -There is also a more powerful variant that uses a regular expression, -indicated by wrapping the pattern in forward slashes. (This is the only -place where hledger requires forward slashes around a regular -expression.) - - Eg: - -alias /REGEX/ = REPLACEMENT - - or: - -$ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by -REPLACEMENT. REGEX is case-insensitive as usual. - - If you need to match a forward slash, escape it with a backslash, eg -'/\/=:'. - - If REGEX contains parenthesised match groups, these can be referenced -by the usual backslash and number in REPLACEMENT: - -alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 -; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - REPLACEMENT continues to the end of line (or on command line, to end -of option argument), so it can contain trailing whitespace. - - -File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive - -9.19.3 Combining aliases ------------------------- - -You can define as many aliases as you like, using journal directives -and/or command line options. - - Recursive aliases - where an account name is rewritten by one alias, -then by another alias, and so on - are allowed. Each alias sees the -effect of previously applied aliases. - - In such cases it can be important to understand which aliases will be -applied and in which order. For (each account name in) each journal -entry, we apply: - - 1. 'alias' directives preceding the journal entry, most recently - parsed first (ie, reading upward from the journal entry, bottom to - top) - 2. '--alias' options, in the order they appeared on the command line - (left to right). - - In other words, for (an account name in) a given journal entry: - - * the nearest alias declaration before/above the entry is applied - first - * the next alias before/above that will be be applied next, and so on - * aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps -provide semantic stability - aliases will keep working the same way -independent of which files are being read and in which order. - - In case of trouble, adding '--debug=6' to the command line will show -which aliases are being applied when. - - -File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive - -9.19.4 Aliases and multiple files ---------------------------------- - -As explained at Directives and multiple files, 'alias' directives do not -affect parent or sibling files. Eg in this command, - -hledger -f a.aliases -f b.journal - - account aliases defined in a.aliases will not affect b.journal. -Including the aliases doesn't work either: - -include a.aliases - -2023-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 - -2023-01-01 ; affected by aliases above - foo 1 - bar - -include c.journal ; also affected - - -File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive - -9.19.5 'end aliases' directive ------------------------------- - -You can clear (forget) all currently defined aliases (seen in the -journal so far, or defined on the command line) with this directive: - -end aliases - - -File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive - -9.19.6 Aliases can generate bad account names ---------------------------------------------- - -Be aware that account aliases can produce malformed account names, which -could cause confusing reports or invalid 'print' output. For example, -you could erase all account names: - -2021-01-01 - a:aa 1 - b - -$ hledger print --alias '/.*/=' -2021-01-01 - 1 - - The above 'print' output is not a valid journal. Or you could insert -an illegal double space, causing 'print' output that would give a -different journal when reparsed: - -2021-01-01 - old 1 - other - -$ hledger print --alias old="new USD" | hledger -f- print -2021-01-01 - new USD 1 - other - - -File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive - -9.19.7 Aliases and account types --------------------------------- - -If an account with a type declaration (see Declaring accounts > Account -types) is renamed by an alias, normally the account type remains in -effect. - - However, renaming in a way that reshapes the account tree (eg -renaming parent accounts but not their children, or vice versa) could -prevent child accounts from inheriting the account type of their -parents. - - Secondly, if an account's type is being inferred from its name, -renaming it by an alias could prevent or alter that. - - If you are using account aliases and the 'type:' query is not -matching accounts as you expect, try troubleshooting with the accounts -command, eg something like: - -$ hledger accounts --alias assets=bassetts type:a - - -File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal - -9.20 'commodity' directive -========================== - -The 'commodity' directive performs several functions: - - 1. It declares which commodity symbols may be used in the journal, - enabling useful error checking with strict mode or the check - command. (See Commodity error checking below.) - - 2. It declares the precision with which this commodity's amounts - should be compared when checking for balanced transactions. - - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See Commodity display style above.) - - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no 'decimal-mark' - directive in effect. See Decimal marks, digit group marks above. - For related dev discussion, see #793.) - - Declaring commodities solves several common parsing/display problems, -so we recommend it. Generally you should put 'commodity' directives at -the top of your journal file (because function 4 is position-sensitive). - -* Menu: - -* Commodity directive syntax:: -* Commodity error checking:: - - -File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive - -9.20.1 Commodity directive syntax ---------------------------------- - -A commodity directive is normally the word 'commodity' followed by a -sample amount (and optionally a comment). Only the amount's symbol and -format is significant. Eg: - -commodity $1000.00 -commodity 1.000,00 EUR -commodity 1 000 000.0000 ; the no-symbol commodity - - A commodity directive's sample amount must always include a period or -comma decimal mark (this rule helps disambiguate decimal marks and digit -group marks). If you don't want to show any decimal digits, write the -decimal mark at the end: - -commodity 1000. AAAA ; show AAAA with no decimals - - Commodity symbols containing spaces, numbers, or punctuation must be -enclosed in double quotes, as usual: - -commodity 1.0000 "AAAA 2023" - - Commodity directives normally include a sample amount, but can -declare only a symbol (ie, just function 1 above): - -commodity $ -commodity INR -commodity "AAAA 2023" -commodity "" ; the no-symbol commodity - - Commodity directives may also be written with an indented 'format' -subdirective, as in Ledger. The symbol is repeated and must be the same -in both places. Other subdirectives are currently ignored: - -; 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 - an unsupported subdirective ; ignored by hledger - - -File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive - -9.20.2 Commodity error checking -------------------------------- - -In strict mode ('-s'/'--strict') (or when you run 'hledger check -commodities'), hledger will report an error if an undeclared commodity -symbol is used. (With one exception: zero amounts are always allowed to -have no commodity symbol.) It works like account error checking -(described above). - - -File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal - -9.21 'decimal-mark' directive -============================= - -You can use a 'decimal-mark' directive - usually one per file, at the -top of the file - to declare which character represents a decimal mark -when parsing amounts in this file. It can look like - -decimal-mark . - - or - -decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we -recommend it, especially if the file contains digit group marks (eg -thousands separators). - - -File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal - -9.22 'include' directive -======================== - -You can pull in the content of additional files by writing an include -directive, like this: - -include FILEPATH - - Only journal files can include, and only journal, timeclock or -timedot files can be included (not CSV files, currently). - - If the file path does not begin with a slash, it is relative to the -current file's folder. - - A tilde means home directory, eg: 'include ~/main.journal'. - - The path may contain glob patterns to match multiple files, eg: -'include *.journal'. - - There is limited support for recursive wildcards: '**/' (the slash is -required) matches 0 or more subdirectories. It's not super convenient -since you have to avoid include cycles and including directories, but -this can be done, eg: 'include */**/*.journal'. - - The path may also be prefixed to force a specific file format, -overriding the file extension (as described in Data formats): 'include -timedot:~/notes/2023*.md'. - - -File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal - -9.23 'P' directive -================== - -The 'P' directive declares a market price, which is a conversion rate -between two commodities on a certain date. This allows value reports to -convert amounts of one commodity to their value in another, on or after -that date. These prices are often obtained from a stock exchange, -cryptocurrency exchange, the or foreign exchange market. - - The format is: - -P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the -commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and -quantity) of commodity 2 that one unit of commodity 1 is worth on this -date. Examples: - -# one euro was worth $1.35 from 2009-01-01 onward: -P 2009-01-01 € $1.35 - -# and $1.40 from 2010-01-01 onward: -P 2010-01-01 € $1.40 - - The '-V', '-X' and '--value' flags use these market prices to show -amount values in another commodity. See Value reporting. - - -File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal - -9.24 'payee' directive -====================== - -'payee PAYEE NAME' - - This directive can be used to declare a limited set of payees which -may appear in transaction descriptions. The "payees" check will report -an error if any transaction refers to a payee that has not been -declared. Eg: - -payee Whole Foods - - Any indented subdirectives are currently ignored. - - -File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal - -9.25 'tag' directive -==================== - -'tag TAGNAME' - - This directive can be used to declare a limited set of tag names -allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - -tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is -used. It is quite easy to accidentally create a tag through normal use -of colons in comments(#comments]; if you want to prevent this, you can -declare and check your tags . - - -File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal - -9.26 Periodic transactions -========================== - -The '~' directive declares recurring transactions. Such directives -allow hledger to generate temporary future transactions (visible in -reports, not in the journal file) to help with forecasting or budgeting. - - Periodic transactions can be a little tricky, so before you use them, -read this whole section, or at least these tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - 2. For troubleshooting, show the generated transactions with 'hledger - print --forecast tag:generated' or 'hledger register --forecast - tag:generated'. - 3. Forecasted transactions will begin only after the last - non-forecasted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. - See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs - improvement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in 'weekly from DATE', DATE - must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give - an error. - 7. Other period expressions with an interval are automatically - expanded to cover a whole number of that interval. (This is done - to improve reports, but it also affects periodic transactions. - Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th - day of month from 2023/01', which is equivalent to '~ every 10th - day of month from 2023/01/01', will be adjusted to start on - 2019/12/10. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -9.26.1 Periodic rule syntax ---------------------------- - -A periodic transaction rule looks like a normal journal entry, with the -date replaced by a tilde ('~') followed by a period expression -(mnemonic: '~' looks like a recurring sine wave.): - -# every first of month -~ monthly - expenses:rent $2000 - assets:bank:checking - -# every 15th of month in 2023's first quarter: -~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying -multi-period reports, just interpreted differently; there, it specifies -report periods; here it specifies recurrence dates (the periods' start -dates). - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -9.26.2 Periodic rules and relative dates ----------------------------------------- - -Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', -'next quarter') are usually not recommended in periodic rules, since the -results will change as time passes. If used, they will be interpreted -relative to, in order of preference: - - 1. the first day of the default year specified by a recent 'Y' - directive - 2. or the date specified with '--today' - 3. or the date on which you are running the report. - - They will not be affected at all by report period or forecast period -dates. - - -File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions - -9.26.3 Two spaces between period expression and description! ------------------------------------------------------------- - -If the period expression is followed by a transaction description, these -must be separated by *two or more spaces*. This helps hledger know -where the period expression ends, so that descriptions can not -accidentally alter their meaning, as in this example: - -; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" -; || -; vv -~ every 2 months in 2023, 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: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal - -9.27 Auto postings -================== - -The '=' directive declares a rule for generating temporary extra -postings on transactions. Wherever the rule matches an existing -posting, it can add one or more companion postings below that one, -optionally influenced by the matched posting's amount. This can be -useful for generating tax postings with a standard percentage, for -example. - - Note that depending on generated data is not ideal for financial -records (it's less portable, less future-proof, less auditable by -others, and less robust, since other features like balance assertions -will depend on using or not using '--auto'). - - 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:: - - -File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings - -9.27.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). - -* Menu: - -* Auto postings and dates:: -* Auto postings and transaction balancing / inferred amounts / balance assertions:: -* Auto posting tags:: -* Auto postings on forecast transactions only:: - - -File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files - -9.27.1.1 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 and multiple files - -9.27.1.2 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, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files - -9.27.1.3 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: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files - -9.27.1.4 Auto postings on forecast transactions only -.................................................... - -Tip: you can can make auto postings that will apply to forecast -transactions but not recorded transactions, by adding -'tag:_generated-transaction' to their QUERY. This can be useful when -generating new journal entries to be saved in the journal. - - -File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal - -9.28 Other syntax -================= - -hledger journal format supports quite a few other features, mainly to -make interoperating with or converting from Ledger easier. Note some of -the features below are powerful and can be useful in special cases, but -in general, features in this section are considered less important or -even not recommended for most users. Downsides are mentioned to help -you decide if you want to use them. - -* Menu: - -* Balance assignments:: -* Bracketed posting dates:: -* D directive:: -* apply account directive:: -* Y directive:: -* Secondary dates:: -* Star comments:: -* Valuation expressions:: -* Virtual postings:: -* Other Ledger directives:: - - -File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax - -9.28.1 Balance assignments --------------------------- - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). - - Downsides: using balance assignments makes your journal less -explicit; to know the exact amount posted, you have to run hledger or do -the calculations yourself, instead of just reading it. Also balance -assignments' forcing of balances can hide errors. These things make -your financial data less portable, less future-proof, and less -trustworthy in an audit. - -* Menu: - -* Balance assignments and prices:: -* Balance assignments and multiple files:: - - -File: hledger.info, Node: Balance assignments and prices, Next: Balance assignments and multiple files, Up: Balance assignments - -9.28.1.1 Balance assignments and prices -....................................... - -A cost in a balance assignment will cause the calculated amount to have -that price attached: - -2019/1/1 - (a) = $1 @ €2 - -$ hledger print --explicit -2019-01-01 - (a) $1 @ €2 = $1 @ €2 - - -File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and prices, Up: Balance assignments - -9.28.1.2 Balance assignments and multiple files -............................................... - -Balance assignments handle multiple files like balance assertions. They -see balance from other files previously included from the current file, -but not from previous sibling or parent files. - - -File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax - -9.28.2 Bracketed posting dates ------------------------------- - -For setting posting dates and secondary posting dates, Ledger's -bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or -'[=DATE2]' in posting comments. hledger will attempt to parse any -square-bracketed sequence of the '0123456789/-.=' characters in this -way. With this syntax, DATE infers its year from the transaction and -DATE2 infers its year from DATE. - - Downsides: another syntax to learn, redundant with hledger's -'date:'/'date2:' tags, and confusingly similar to Ledger's lot date -syntax. - - -File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax - -9.28.3 'D' directive --------------------- - -'D AMOUNT' - - This directive sets a default commodity, to be used for any -subsequent commodityless amounts (ie, plain numbers) seen while parsing -the journal. This effect lasts until the next 'D' directive, or the end -of the journal. - - For compatibility/historical reasons, 'D' also acts like a -'commodity' directive (setting the commodity's decimal mark for parsing -and display style for output). So its argument is not just a commodity -symbol, but a full amount demonstrating the style. The amount must -include a decimal mark (either period or comma). Eg: - -; commodity-less amounts should be treated as dollars -; (and displayed with the dollar sign on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity's display style, a 'commodity' directive has -highest priority, then a 'D' directive. - - For detecting a commodity's decimal mark during parsing, -'decimal-mark' has highest priority, then 'commodity', then 'D'. - - For checking commodity symbols with the check command, a 'commodity' -directive is required ('hledger check commodities' ignores 'D' -directives). - - Downsides: omitting commodity symbols makes your financial data less -explicit, less portable, and less trustworthy in an audit. It is -usually an unsustainable shortcut; sooner or later you will want to -track multiple commodities. D is overloaded with functions redundant -with 'commodity' and 'decimal-mark'. And it works differently from -Ledger's 'D'. - - -File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax - -9.28.4 'apply account' directive --------------------------------- - -This directive sets a default parent account, which will be prepended to -all accounts in following entries, until an 'end apply account' -directive or end of current file. Eg: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - 'account' directives are also affected, and so is any 'include'd -content. - - Account names entered via hledger add or hledger-web are not -affected. - - Account aliases, if any, are applied after the parent account is -prepended. - - Downsides: this can make your financial data less explicit, less -portable, and less trustworthy in an audit. - - -File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax - -9.28.5 'Y' directive --------------------- - -'Y YEAR' - - or (deprecated backward-compatible forms): - - 'year YEAR' 'apply year YEAR' - - The space is optional. This sets a default year to be used for -subsequent dates which don't specify a year. Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -year 2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at -least) makes your financial data less explicit, less portable, and less -trustworthy in an audit. Such dates can get separated from their -corresponding Y directive, eg when evaluating a region of the journal in -your editor. A missing Y directive makes reports dependent on today's -date. - - -File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax - -9.28.6 Secondary dates ----------------------- - -A secondary date is written after the primary date, following an equals -sign. If the year is omitted, the primary date's year is assumed. When -running reports, the primary (left) date is used by default, but with -the '--date2' flag (or '--aux-date' or '--effective'), the secondary -(right) date will be used instead. - - The meaning of secondary dates is up to you, but it's best to follow -a consistent rule. Eg "primary = the bank's clearing date, secondary = -date the transaction was initiated, if different". - - Downsides: makes your financial data more complicated, less portable, -and less trustworthy in an audit. Keeping the meaning of the two dates -consistent requires discipline, and you have to remember which reporting -mode is appropriate for a given report. Posting dates are simpler and -better. - - -File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax - -9.28.7 Star comments --------------------- - -Lines beginning with '*' (star/asterisk) are also comment lines. This -feature allows Emacs users to insert org headings in their journal, -allowing them to fold/unfold/navigate it like an outline when viewed -with org mode. - - Downsides: another, unconventional comment syntax to learn. -Decreases your journal's portability. And switching to Emacs org mode -just for folding/unfolding meant losing the benefits of ledger mode; -nowadays you can add outshine mode to ledger mode to get folding without -losing ledger mode's features. - - -File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax - -9.28.8 Valuation expressions ----------------------------- - -Ledger allows a valuation function or value to be written in double -parentheses after an amount. hledger ignores these. - - -File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax - -9.28.9 Virtual postings ------------------------ - -A posting with parentheses around the account name ('(some:account)') is -called a _unbalanced virtual posting_. Such postings do not participate -in transaction balancing. (And if you write them without an amount, a -zero amount is always inferred.) These can occasionally be convenient -for special circumstances, but they violate double entry bookkeeping and -make your data less portable across applications, so many people avoid -using them at all. - - A posting with brackets around the account name ('[some:account]') is -called a _balanced virtual posting_. The balanced virtual postings in a -transaction must add up to zero, just like ordinary postings, but -separately from them. These are not part of double entry bookkeeping -either, but they are at least balanced. An example: - -2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Ordinary postings, whose account names are neither parenthesised nor -bracketed, are called _real postings_. You can exclude virtual postings -from reports with the '-R/--real' flag or a 'real:1' query. - - -File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax - -9.28.10 Other Ledger directives -------------------------------- - -These other Ledger directives are currently accepted but ignored. This -allows hledger to read more Ledger files, but be aware that hledger's -reports may differ from Ledger's if you use these. - -apply fixed COMM AMT -apply tag TAG -assert EXPR -bucket / A ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR -end apply fixed -end apply tag -end apply year -end tag -eval / expr EXPR -python - PYTHONCODE -tag NAME -value EXPR ---command-line-flags - - See also https://hledger.org/ledger.html for a detailed -hledger/Ledger syntax comparison. - - -File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top - -10 CSV -****** - -hledger can read CSV files (Character Separated Value - usually comma, -semicolon, or tab) containing dated records, automatically converting -each record into a transaction. - - (To learn about _writing_ CSV, see CSV output.) - - For best error messages when reading CSV/TSV/SSV files, make sure -they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use -a hledger file prefix (see File Extension below). - - Each CSV file must be described by a corresponding _rules file_. -This contains rules describing the CSV data (header line, fields layout, -date format etc.), how to construct hledger transactions from it, and -how to categorise transactions based on description or other attributes. - - By default hledger looks for a rules file named like the CSV file -with an extra '.rules' extension, in the same directory. Eg when asked -to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'. You can -specify a different rules file with the '--rules-file' option. If no -rules file is found, hledger will create a sample rules file, which -you'll need to adjust. - - At minimum, the rules file must identify the date and amount fields, -and often it also specifies the date format and how many header lines -there are. Here's a simple CSV file and a rules file for it: - -Date, Description, Id, Amount -12/11/2019, Foo, 123, 10.23 - -# basic.csv.rules -skip 1 -fields date, description, , amount -date-format %d/%m/%Y - -$ hledger print -f basic.csv -2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There's an introductory Importing CSV data tutorial on hledger.org, -and more CSV rules examples below, and a larger collection at -https://github.com/simonmichael/hledger/tree/master/examples/csv. - -* Menu: - -* CSV rules cheatsheet:: -* source:: -* separator:: -* skip:: -* date-format:: -* timezone:: -* newest-first:: -* intra-day-reversed:: -* decimal-mark:: -* fields list:: -* Field assignment:: -* Field names:: -* if block:: -* Matchers:: -* if table:: -* balance-type:: -* include:: -* Working with CSV:: -* CSV rules examples:: - - -File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV - -10.1 CSV rules cheatsheet -========================= - -The following kinds of rule can appear in the rules file, in any order. -(Blank lines and lines beginning with '#' or ';' or '*' are ignored.) - -*'source'* optionally declare which file to read data - from -*'separator'* declare the field separator, instead of - relying on file extension -*'skip'* skip one or more header lines at start of file -*'date-format'* declare how to parse CSV dates/date-times -*'timezone'* declare the time zone of ambiguous CSV - date-times -*'newest-first'* improve txn order when: there are multiple - records, newest first, all with the same date -*'intra-day-reversed'* improve txn order when: same-day txns are in - opposite order to the overall file -*'decimal-mark'* declare the decimal mark used in CSV amounts, - when ambiguous -*'fields' list* name CSV fields for easy reference, and - optionally assign their values to hledger - fields -*Field assignment* assign a CSV value or interpolated text value - to a hledger field -*'if' block* conditionally assign values to hledger fields, - or 'skip' a record or 'end' (skip rest of - file) -*'if' table* conditionally assign values to hledger fields, - using compact syntax -*'balance-type'* select which type of balance - assertions/assignments to generate -*'include'* inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are -evaluated. - - -File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV - -10.2 'source' -============= - -If you tell hledger to read a csv file with '-f foo.csv', it will look -for rules in 'foo.csv.rules'. Or, you can tell it to read the rules -file, with '-f foo.csv.rules', and it will look for data in 'foo.csv' -(since 1.30). - - These are mostly equivalent, but the second method provides some -extra features. For one, the data file can be missing, without causing -an error; it is just considered empty. And, you can specify a different -data file by adding a "source" rule: - -source ./Checking1.csv - - If you specify just a file name with no path, hledger will look for -it in your system's downloads directory ('~/Downloads', currently): - -source Checking1.csv - - And if you specify a glob pattern, hledger will read the most recent -of the matched files (useful with repeated downloads): - -source Checking1*.csv - - See also "Working with CSV > Reading files specified by rule". - - -File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV - -10.3 'separator' -================ - -You can use the 'separator' rule to read other kinds of -character-separated data. The argument is any single separator -character, or the words 'tab' or 'space' (case insensitive). Eg, for -comma-separated values (CSV): - -separator , - - or for semicolon-separated values (SSV): - -separator ; - - or for tab-separated values (TSV): - -separator TAB - - If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a -'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be -inferred automatically, and you won't need this rule. - - -File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV - -10.4 'skip' -=========== - -skip N - - The word 'skip' followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines at the start of the input -data. You'll need this whenever your CSV data contains header lines. -Note, empty and blank lines are skipped automatically, so you don't need -to count those. - - 'skip' has a second meaning: it can be used inside if blocks -(described below), to skip one or more records whenever the condition is -true. Records skipped in this way are ignored, except they are still -required to be valid CSV. - - -File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV - -10.5 'date-format' -================== - -date-format DATEFMT - - This is a helper for the 'date' (and 'date2') fields. If your CSV -dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD', -you'll need to add a date-format rule describing them with a -strptime-style date parsing pattern - see -https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. -The pattern must parse the CSV date value completely. Some examples: - -# MM/DD/YY -date-format %m/%d/%y - -# D/M/YYYY -# The - makes leading zeros optional. -date-format %-d/%-m/%Y - -# YYYY-Mmm-DD -date-format %Y-%h-%d - -# M/D/YYYY HH:MM AM some other junk -# Note the time and junk must be fully parsed, though only the date is used. -date-format %-m/%-d/%Y %l:%M %p some other junk - - -File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV - -10.6 'timezone' -=============== - -timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone -other than yours, but containing no explicit time zone information, you -can use this rule to declare the CSV's native time zone, which helps -prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don't -need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ', -'%Ez'; see the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware -conversion, localising the CSV date-times to your current system time -zone. If you prefer to localise to some other time zone, eg for -reproducibility, you can (on unix at least) set the output timezone with -the TZ environment variable, eg: - -$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - 'timezone' currently does not understand timezone names, except -"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". -For others, use numeric format: +HHMM or -HHMM. - - -File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV - -10.7 'newest-first' -=================== - -hledger tries to ensure that the generated transactions will be ordered -chronologically, including same-day transactions. Usually it can -auto-detect how the CSV records are ordered. But if it encounters CSV -where all records are on the same date, it assumes that the records are -oldest first. If in fact the CSV's records are normally newest first, -like: - -2022-10-01, txn 3... -2022-10-01, txn 2... -2022-10-01, txn 1... - - you can add the 'newest-first' rule to help hledger generate the -transactions in correct order. - -# same-day CSV records are newest first -newest-first - - -File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV - -10.8 'intra-day-reversed' -========================= - -If CSV records within a single day are ordered opposite to the overall -record order, you can add the 'intra-day-reversed' rule to improve the -order of journal entries. Eg, here the overall record order is newest -first, but same-day records are oldest first: - -2022-10-02, txn 3... -2022-10-02, txn 4... -2022-10-01, txn 1... -2022-10-01, txn 2... - -# transactions within each day are reversed with respect to the overall date order -intra-day-reversed - - -File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV - -10.9 'decimal-mark' -=================== - -decimal-mark . - - or: - -decimal-mark , - - hledger automatically accepts either period or comma as a decimal -mark when parsing numbers (cf Amounts). However if any numbers in the -CSV contain digit group marks, such as thousand-separating commas, you -should declare the decimal mark explicitly with this rule, to avoid -misparsed numbers. - - -File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV - -10.10 'fields' list -=================== - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word 'fields' followed by comma-separated field -names) is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say - '%SomeField' instead of remembering '%13'. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and - build a transaction. - - Here's an example that says "use the 1st, 2nd and 4th fields as the -transaction's date, description and amount; name the last two fields for -later reference; and ignore the others": - -fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to -the CSV file's separator. Also: - - * There must be least two items in the list (at least one comma). - * Field names may not contain spaces. Spaces before/after field - names are optional. - * Field names may contain '_' (underscore) or '-' (hyphen). - * Fields you don't care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it's convenient to use these for -your field names, suitably modified (eg lower-cased with spaces replaced -by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning -to a hledger field with the same name. Eg you could call the CSV's -"balance" field 'balance_' to avoid directly setting hledger's 'balance' -field (and generating a balance assertion). - - -File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV - -10.11 Field assignment -====================== - -HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to -hledger fields. They can be used instead of or in addition to a fields -list (see above). - - To assign a value to a hledger field, write the field name (any of -the standard hledger field/pseudo-field names, defined below), a space, -followed by a text value on the same line. This text value may -interpolate CSV fields, referenced either by their 1-based position in -the CSV record ('%N') or by the name they were given in the fields list -('%CSVFIELD'), and regular expression match groups ('\N'). - - Some examples: - -# set the amount to the 4th CSV field, with " USD" appended -amount %4 USD - -# combine three fields to make a comment, containing note: and date: tags -comment note: %somefield - %anotherfield, date: %1 - - Tips: - - * Interpolation strips outer whitespace (so a CSV value like '" 1 "' - becomes '1' when interpolated) (#1051). - * Interpolations always refer to a CSV field - you can't interpolate - a hledger field. (See Referencing other fields below). - - -File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV - -10.12 Field names -================= - -Note the two kinds of field names mentioned here, and used only in -hledger CSV rules files: - - 1. *CSV field names* ('CSVFIELD' in these docs): you can optionally - name the CSV columns for easy reference (since hledger doesn't yet - automatically recognise column headings in a CSV file), by writing - arbitrary names in a 'fields' list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you - must set at least some of these to generate the hledger transaction - from a CSV record, by writing them as the left hand side of a field - assignment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a 'fields' list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what -happens when you assign values to them: - -* Menu: - -* date field:: -* date2 field:: -* status field:: -* code field:: -* description field:: -* comment field:: -* account field:: -* amount field:: -* currency field:: -* balance field:: - - -File: hledger.info, Node: date field, Next: date2 field, Up: Field names - -10.12.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 - -10.12.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 - -10.12.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 - -10.12.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 - -10.12.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 - -10.12.6 comment field ---------------------- - -'comment' sets the transaction's comment, if any. - - 'commentN', where N is a number, sets the Nth posting's comment. - - You can assign multi-line comments by writing literal '\n' in the -code. A comment starting with '\n' will begin on a new line. - - Comments can contain tags, as usual. - - -File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names - -10.12.7 account field ---------------------- - -Assigning to 'accountN', where N is 1 to 99, sets the account name of -the Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you'll want to set 'account1' -and 'account2'. Typically 'account1' is associated with the CSV file, -and is set once with a top-level assignment, while 'account2' is set -based on each transaction's description, in conditional rules. - - If a posting's account name is left unset but its amount is set (see -below), a default account name will be chosen (like "expenses:unknown" -or "income:unknown"). - - -File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names - -10.12.8 amount field --------------------- - -There are several ways to set posting amounts from CSV, useful in -different situations. - - 1. *'amount'* is the oldest and simplest. Assigning to this sets the - amount of the first and second postings. In the second posting, - the amount will be negated; also, if it has a cost attached, it - will be converted to cost. - - 2. *'amount-in'* and *'amount-out'* work exactly like the above, but - should be used when the CSV has two amount fields (such as "Debit" - and "Credit", or "Inflow" and "Outflow"). Whichever field has a - non-zero value will be used as the amount of the first and second - postings. Here are some tips to avoid confusion: - - * It's not "amount-in for posting 1 and amount-out for posting - 2", it is "extract a single amount from the amount-in or - amount-out field, and use that for posting 1 and (negated) for - posting 2". - * Don't use both 'amount' and 'amount-in'/'amount-out' in the - same rules file; choose based on whether the amount is in a - single CSV field or spread across two fields. - * In each record, at most one of the two CSV fields should - contain a non-zero amount; the other field must contain a zero - or nothing. - * hledger assumes both CSV fields contain unsigned numbers, and - it automatically negates the amount-out values. - * If the data doesn't fit these requirements, you'll probably - need an if rule (see below). - - 3. *'amountN'* (where N is a number from 1 to 99) sets the amount of - only a single posting: the Nth posting in the transaction. You'll - usually need at least two such assignments to make a balanced - transaction. You can also generate more than two postings, to - represent more complex transactions. The posting numbers don't - have to be consecutive; with if rules, higher posting numbers can - be useful to ensure a certain order of postings. - - 4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but - should be used when the CSV has two amount fields. This is - analogous to 'amount-in' and 'amount-out', and those tips also - apply here. - - 5. Remember that a 'fields' list can also do assignments. So in a - fields list if you name a CSV field "amount", that counts as - assigning to 'amount'. (If you don't want that, call it something - else in the fields list, like "amount_".) - - 6. The above don't handle every situation; if you need more - flexibility, use an 'if' rule to set amounts conditionally. See - "Working with CSV > Setting amounts" below for more on this and on - amount-setting generally. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -10.12.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 - -10.12.10 balance field ----------------------- - -'balanceN' sets a balance assertion amount (or if the posting amount is -left empty, a balance assignment) on posting N. - - 'balance' is a compatibility spelling for hledger <1.17; it is -equivalent to 'balance1'. - - You can adjust the type of assertion/assignment with the -'balance-type' rule (see below). - - See Tips below for more about setting amounts and currency. - - -File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV - -10.13 'if' block -================ - -Rules can be applied conditionally, depending on patterns in the CSV -data. This allows flexibility; in particular, it is how you can -categorise transactions, selecting an appropriate account name based on -their description (for example). There are two ways to write -conditional rules: "if blocks", described here, and "if tables", -described below. - - An if block is the word 'if' and one or more "matcher" expressions -(can be a word or phrase), one per line, starting either on the same or -next line; followed by one or more indented rules. Eg, - -if MATCHER - RULE - - or - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be -applied. They are usually field assignments, but the following special -rules may also be used within an if block: - - * 'skip' - skips the matched CSV record (generating no transaction - from it) - * 'end' - skips the rest of the current CSV file. - - Some examples: - -# if the record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the record contains any of these phrases, set account2 and a transaction comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - -# if an empty record is seen (assuming five fields), ignore the rest of the CSV file -if ,,,, - end - - -File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV - -10.14 Matchers -============== - -There are two kinds: - - 1. A record matcher is a word or single-line text fragment or regular - expression ('REGEX'), which hledger will try to match - case-insensitively anywhere within the CSV record. - Eg: 'whole foods' - - 2. A field matcher is preceded with a percent sign and CSV field name - ('%CSVFIELD REGEX'). hledger will try to match these just within - the named CSV field. - Eg: '%date 2023' - - The regular expression is (as usual in hledger) a POSIX extended -regular expression, that also supports GNU word boundaries ('\b', '\B', -'\<', '\>'), and nothing else. If you have trouble, see "Regular -expressions" in the hledger manual -(https://hledger.org/hledger.html#regular-expressions). - - With record matchers, it's important to know that the record matched -is not the original CSV record, but a modified one: separators will be -converted to commas, and enclosing double quotes (but not enclosing -whitespace) are removed. So for example, when reading an SSV file, if -the original record was: - -2023-01-01; "Acme, Inc."; 1,000 - - the regex would see, and try to match, this modified record text: - -2023-01-01,Acme, Inc., 1,000 - - When an if block has multiple matchers, they are combined as follows: - - * By default they are OR'd (any one of them can match) - * When a matcher is preceded by ampersand ('&') it will be AND'ed - with the previous matcher (both of them must match). - - When a matcher is preceded by an exclamation mark (!), the matcher -will be negated, ie it will exclude CSV records that match. - -* Menu: - -* Match groups:: - - -File: hledger.info, Node: Match groups, Up: Matchers - -10.14.1 Match groups --------------------- - -Matchers can define match groups: parenthesised portions of the regular -expression which are available for reference in field assignments. -Groups are enclosed in regular parentheses ('(' and ')') and can be -nested. Each group is available in field assignments using the token -'\N', where N is an index into the match groups for this conditional -block (e.g. '\1', '\2', etc.). - - Example: Warp credit card payment postings to the beginning of the -billing period (Month start), to match how they are presented in -statements, using posting dates: - -if %date (....-..)-.. - comment2 date:\1-01 - - Another example: Read the expense account from the CSV field, but -throw away a prefix: - -if %account1 liabilities:family:(expenses:.*) - account1 \1 - - -File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV - -10.15 'if' table -================ - -"if tables" are an alternative to if blocks; they can express many -matchers and field assignments in a more compact tabular format, like -this: - -if,HLEDGERFIELD1,HLEDGERFIELD2,... -MATCHERA,VALUE1,VALUE2,... -MATCHERB,VALUE1,VALUE2,... -MATCHERC,VALUE1,VALUE2,... - - - The first character after 'if' is taken to be this if table's field -separator. It is unrelated to the separator used in the CSV file. It -should be a non-alphanumeric character like ',' or '|' that does not -appear anywhere else in the table (it should not be used in field names -or matchers or values, and it cannot be escaped with a backslash). - - Each line must contain the same number of separators; empty values -are allowed. Whitespace can be used in the matcher lines for -readability (but not in the if line, currently). The table must be -terminated by an empty line (or end of file). - - An if table like the above is interpreted as follows: try all of the -matchers; whenever a matcher succeeds, assign all of the values on that -line to the corresponding hledger fields; later lines can overrider -earlier ones. It is equivalent to this sequence of if blocks: - -if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERB - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - -if,account2,comment -atm transaction fee,expenses:business:banking,deductible? check it -%description groceries,expenses:groceries, -2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - -File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV - -10.16 'balance-type' -==================== - -Balance assertions generated by assigning to balanceN are of the simple -'=' type by default, which is a single-commodity, subaccount-excluding -assertion. You may find the subaccount-including variants more useful, -eg if you have created some virtual subaccounts of checking to help with -budgeting. You can select a different type of assertion with the -'balance-type' rule: - -# balance assertions will consider all commodities and all subaccounts -balance-type ==* - - Here are the balance assertion types for quick reference: - -= single commodity, exclude subaccounts -=* single commodity, include subaccounts -== multi commodity, exclude subaccounts -==* multi commodity, include subaccounts - - -File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV - -10.17 'include' -=============== - -include RULESFILE - - This includes the contents of another CSV rules file at this point. -'RULESFILE' is an absolute file path or a path relative to the current -file's directory. This can be useful for sharing common rules between -several rules files, eg: - -# someaccount.csv.rules - -## someaccount-specific rules -fields date,description,amount -account1 assets:someaccount -account2 expenses:misc - -## common rules -include categorisation.rules - - -File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV - -10.18 Working with CSV -====================== - -Some tips: - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading CSV from standard input:: -* Reading multiple CSV files:: -* Reading files specified by rule:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Amount signs:: -* Setting currency/commodity:: -* Amount decimal places:: -* Referencing other fields:: -* How CSV rules are evaluated:: -* Well factored rules:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV - -10.18.1 Rapid feedback ----------------------- - -It's a good idea to get rapid feedback while creating/troubleshooting -CSV rules. Here's a good way, using entr from eradman.com/entrproject: - -$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - - A desc: query (eg) is used to select just one, or a few, transactions -of interest. "bash -c" is used to run multiple commands, so we can echo -a separator each time the command re-runs, making it easier to read the -output. - - -File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV - -10.18.2 Valid CSV ------------------ - -Note that hledger will only accept valid CSV conforming to RFC 4180, and -equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab -as separators). This means, eg: - - * Values may be enclosed in double quotes, or not. Enclosing in - single quotes is not allowed. (Eg ''A','B'' is rejected.) - * When values are enclosed in double quotes, spaces outside the - quotes are not allowed. (Eg '"A", "B"' is rejected.) - * When values are not enclosed in quotes, they may not contain double - quotes. (Eg 'A"A, B' is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you'll need to -transform it before reading with hledger. Try using sed, or a more -permissive CSV parser like python's csv lib. - - -File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV - -10.18.3 File Extension ----------------------- - -To help hledger choose the CSV file reader and show the right error -messages (and choose the right field separator character by default), -it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv' -filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV -reader (and the default field separator) by prefixing the file path with -'csv:', 'ssv:' or 'tsv:': Eg: - -$ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator -rule if needed. - - -File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV - -10.18.4 Reading CSV from standard input ---------------------------------------- - -You'll need the file format prefix when reading CSV from stdin also, -since hledger assumes journal format by default. Eg: - -$ cat foo.dat | hledger -f ssv:- print - - -File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV - -10.18.5 Reading multiple CSV files ----------------------------------- - -If you use multiple '-f' options to read multiple CSV files at once, -hledger will look for a correspondingly-named rules file for each CSV -file. But if you use the '--rules-file' option, that rules file will be -used for all the CSV files. - - -File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV - -10.18.6 Reading files specified by rule ---------------------------------------- - -Instead of specifying a CSV file in the command line, you can specify a -rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will -read data from foo.csv in the same directory, but you can add a source -rule to specify a different data file, perhaps located in your web -browser's download directory. - - This feature was added in hledger 1.30, so you won't see it in most -CSV rules examples. But it helps remove some of the busywork of -managing CSV downloads. Most of your financial institutions's default -CSV filenames are different and can be recognised by a glob pattern. So -you can put a rule like 'source Checking1*.csv' in -foo-checking.csv.rules, and then periodically follow a workflow like: - - 1. Download CSV from Foo's website, using your browser's defaults - 2. Run 'hledger import foo-checking.csv.rules' to import any new - transactions - - After import, you can: discard the CSV, or leave it where it is for a -while, or move it into your archives, as you prefer. If you do nothing, -next time your browser will save something like Checking1-2.csv, and -hledger will use that because of the '*' wild card and because it is the -most recent. - - -File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV - -10.18.7 Valid transactions --------------------------- - -After reading a CSV file, hledger post-processes and validates the -generated journal entries as it would for a journal file - balancing -them, applying balance assignments, and canonicalising amount styles. -Any errors at this stage will be reported in the usual way, displaying -the problem entry. - - There is one exception: balance assertions, if you have generated -them, will not be checked, since normally these will work only when the -CSV data is part of the main journal. If you do need to check balance -assertions generated from CSV right away, pipe into another hledger: - -$ hledger -f file.csv print | hledger -f- print - - -File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV - -10.18.8 Deduplicating, importing --------------------------------- - -When you download a CSV file periodically, eg to get your latest bank -transactions, the new file may overlap with the old one, containing some -of the same records. - - The import command will (a) detect the new transactions, and (b) -append just those transactions to your main journal. It is idempotent, -so you don't have to remember how many times you ran it or with which -version of the CSV. (It keeps state in a hidden '.latest.FILE.csv' -file.) This is the easiest way to import CSV data. Eg: - -# download the latest CSV files, then run this command. -# Note, no -f flags needed here. -$ hledger import *.csv [--dry] - - This method works for most CSV files. (Where records have a stable -chronological order, and new records appear only at the new end.) - - A number of other tools and workflows, hledger-specific and -otherwise, exist for converting, deduplicating, classifying and managing -CSV data. See: - - * https://hledger.org/cookbook.html#setups-and-workflows - * https://plaintextaccounting.org -> data import/conversion - - -File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV - -10.18.9 Setting amounts ------------------------ - -Continuing from amount field above, here are more tips for -amount-setting: - - 1. *If the amount is in a single CSV field:* - - a. *If its sign indicates direction of flow:* - Assign it to 'amountN', to set the Nth posting's amount. N is - usually 1 or 2 but can go up to 99. - - b. *If another field indicates direction of flow:* - Use one or more conditional rules to set the appropriate - amount sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. *If the amount is in two CSV fields (such as Debit and Credit, or - In and Out):* - - a. *If both fields are unsigned:* - Assign one field to 'amountN-in' and the other to - 'amountN-out'. hledger will automatically negate the "out" - field, and will use whichever field value is non-zero as - posting N's amount. - - b. *If either field is signed:* - You will probably need to override hledger's sign for one or - the other field, as in the following example: - - # Negate the -out value, but only if it is not empty: - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields can contain a non-zero value (or both can be - empty):* - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such - as '1' and 'none'. For such cases, use conditional rules to - help select the amount. Eg, to handle the above you could - select the value containing non-zero digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. *If you want posting 2's amount converted to cost:* - Use the unnumbered 'amount' (or 'amount-in' and 'amount-out') - syntax. - - 4. *If the CSV has only balance amounts, not transaction amounts:* - Assign to 'balanceN', to set a balance assignment on the Nth - posting, causing the posting's amount to be calculated - automatically. 'balance' with no number is equivalent to - 'balance1'. In this situation hledger is more likely to guess the - wrong default account name, so you may need to set that explicitly. - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV - -10.18.10 Amount signs ---------------------- - -There is some special handling making it easier to parse and to reverse -amount signs. (This only works for whole amounts, not for cost amounts -such as COST in 'amount1 AMT @ COST'): - - * *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 '""'. - - It's not possible (without preprocessing the CSV) to set an amount to -its absolute value, ie discard its sign. - - -File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV - -10.18.11 Setting currency/commodity ------------------------------------ - -If the currency/commodity symbol is included in the CSV's amount -field(s): - -2023-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 - -2023-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - -2023-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 - -2023-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 - -2023-01-01 foo - expenses:unknown 123.00 USD - income:unknown -123.00 USD - - Note we used a temporary field name ('cur') that is not 'currency' - -that would trigger the prepending effect, which we don't want here. - - -File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV - -10.18.12 Amount decimal places ------------------------------- - -Like amounts in a journal file, the amounts generated by CSV rules like -'amount1' influence commodity display styles, such as the number of -decimal places displayed in reports. - - The original amounts as written in the CSV file do not affect display -style (because we don't yet reliably know their commodity). - - -File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV - -10.18.13 Referencing other fields ---------------------------------- - -In field assignments, you can interpolate only CSV fields, not hledger -fields. In the example below, there's both a CSV field and a hledger -field named amount1, but %amount1 always means the CSV field, not the -hledger field: - -# Name the third CSV field "amount1" -fields date,description,amount1 - -# Set hledger's amount1 to the CSV amount1 field followed by USD -amount1 %amount1 USD - -# Set comment to the CSV amount1 (not the amount1 assigned above) -comment %amount1 - - Here, since there's no CSV amount1 field, %amount1 will produce a -literal "amount1": - -fields date,description,csvamount -amount1 %csvamount USD -# Can't interpolate amount1 here -comment %amount1 - - When there are multiple field assignments to the same hledger field, -only the last one takes effect. Here, comment's value will be be B, or -C if "something" is matched, but never A: - -comment A -comment B -if something - comment C - - -File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV - -10.18.14 How CSV rules are evaluated ------------------------------------- - -Here's how to think of CSV rules being evaluated (if you really need -to). First, - - * 'include' - all includes are inlined, from top to bottom, depth - first. (At each include point the file is inlined and scanned for - further includes, recursively, before proceeding.) - - Then "global" rules are evaluated, top to bottom. If a rule is -repeated, the last one wins: - - * 'skip' (at top level) - * 'date-format' - * 'newest-first' - * 'fields' - names the CSV fields, optionally sets up initial - assignments to hledger fields - - Then for each CSV record in turn: - - * test all 'if' blocks. If any of them contain a 'end' rule, skip - all remaining CSV records. Otherwise if any of them contain a - 'skip' rule, skip that many CSV records. If there are multiple - matched 'skip' rules, the first one wins. - * collect all field assignments at top level and in matched 'if' - blocks. When there are multiple assignments for a field, keep only - the last one. - * compute a value for each hledger field - either the one that was - assigned to it (and interpolate the %CSVFIELD references), or a - default - * generate a hledger transaction (journal entry) from these values. - - This is all part of the CSV reader, one of several readers hledger -can use to parse input files. When all files have been read -successfully, the transactions are passed as input to whichever hledger -command the user specified. - - -File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV - -10.18.15 Well factored rules ----------------------------- - -Some things than can help reduce duplication and complexity in rules -files: - - * Extracting common rules usable with multiple CSV files into a - 'common.rules', and adding 'include common.rules' to each CSV's - rules file. - - * Splitting if blocks into smaller if blocks, extracting the - frequently used parts. - - -File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV - -10.19 CSV rules examples -======================== - -* Menu: - -* Bank of Ireland:: -* Coinbase:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples - -10.19.1 Bank of Ireland ------------------------ - -Here's a CSV with two amount fields (Debit and Credit), and a balance -field, which we can use to add balance assertions, which is not -necessary but provides extra error checking: - -Date,Details,Debit,Credit,Balance -07/12/2012,LODGMENT 529898,,10.0,131.21 -07/12/2012,PAYMENT,5,,126 - -# bankofireland-checking.csv.rules - -# skip the header line -skip - -# name the csv fields, and assign some of them as journal entry fields -fields date, description, amount-out, amount-in, balance - -# We generate balance assertions by assigning to "balance" -# above, but you may sometimes need to remove these because: -# -# - the CSV balance differs from the true balance, -# by up to 0.0000000000005 in my experience -# -# - it is sometimes calculated based on non-chronological ordering, -# eg when multiple transactions clear on the same day - -# date is in UK/Ireland format -date-format %d/%m/%Y - -# set the currency -currency EUR - -# set the base account for all txns -account1 assets:bank:boi:checking - -$ hledger -f bankofireland-checking.csv print -2012-12-07 LODGMENT 529898 - assets:bank:boi:checking EUR10.0 = EUR131.2 - income:unknown EUR-10.0 - -2012-12-07 PAYMENT - assets:bank:boi:checking EUR-5.0 = EUR126.0 - expenses:unknown EUR5.0 - - The balance assertions don't raise an error above, because we're -reading directly from CSV, but they will be checked if these entries are -imported into a journal file. - - -File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples - -10.19.2 Coinbase ----------------- - -A simple example with some CSV from Coinbase. The spot price is -recorded using cost notation. The legacy 'amount' field name -conveniently sets amount 2 (posting 2's amount) to the total cost. - -# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes -# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - -# coinbase.csv.rules -skip 1 -fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes -date %Timestamp -date-format %Y-%m-%dT%T%Z -description %Notes -account1 assets:coinbase:cc -amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - -$ hledger print -f coinbase.csv -2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - -File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples - -10.19.3 Amazon --------------- - -Here we convert amazon.com order history, and use an if block to -generate a third posting if there's a fee. (In practice you'd probably -get this data from your bank instead, but it's an example.) - -"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" -"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" -"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" - -# amazon-orders.csv.rules - -# skip one header line -skip 1 - -# name the csv fields, and assign the transaction's date, amount and code. -# Avoided the "status" and "amount" hledger field names to prevent confusion. -fields date, _, toorfrom, name, amzstatus, amzamount, fees, code - -# how to parse the date -date-format %b %-d, %Y - -# combine two fields to make the description -description %toorfrom %name - -# save the status as a tag -comment status:%amzstatus - -# set the base account for all transactions -account1 assets:amazon -# leave amount1 blank so it can balance the other(s). -# I'm assuming amzamount excludes the fees, don't remember - -# set a generic account2 -account2 expenses:misc -amount2 %amzamount -# and maybe refine it further: -#include categorisation.rules - -# add a third posting for fees, but only if they are non-zero. -if %fees [1-9] - account3 expenses:fees - amount3 %fees - -$ hledger -f amazon-orders.csv print -2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed - assets:amazon - expenses:misc $20.00 - -2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed - assets:amazon - expenses:misc $25.00 - expenses:fees $1.00 - - -File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples - -10.19.4 Paypal --------------- - -Here's a real-world rules file for (customised) Paypal CSV, with some -Paypal-specific rules, and a second rules file included: - -"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" -"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" -"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" -"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" -"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" -"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" -"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" -"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" - -# paypal-custom.csv.rules - -# Tips: -# Export from Activity -> Statements -> Custom -> Activity download -# Suggested transaction type: "Balance affecting" -# Paypal's default fields in 2018 were: -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" -# This rules file assumes the following more detailed fields, configured in "Customize report fields": -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" - -fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note - -skip 1 - -date-format %-m/%-d/%Y - -# ignore some paypal events -if -In Progress -Temporary Hold -Update to - skip - -# add more fields to the description -description %description_ %itemtitle - -# save some other fields as tags -comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ - -# convert to short currency symbols -if %currency USD - currency $ -if %currency EUR - currency E -if %currency GBP - currency P - -# generate postings - -# the first posting will be the money leaving/entering my paypal account -# (negative means leaving my account, in all amount fields) -account1 assets:online:paypal -amount1 %netamount - -# the second posting will be money sent to/received from other party -# (account2 is set below) -amount2 -%grossamount - -# if there's a fee, add a third posting for the money taken by paypal. -if %feeamount [1-9] - account3 expenses:banking:paypal - amount3 -%feeamount - comment3 business: - -# choose an account for the second posting - -# override the default account names: -# if the amount is positive, it's income (a debit) -if %grossamount ^[^-] - account2 income:unknown -# if negative, it's an expense (a credit) -if %grossamount ^- - account2 expenses:unknown - -# apply common rules for setting account2 & other tweaks -include common.rules - -# apply some overrides specific to this csv - -# Transfers from/to bank. These are usually marked Pending, -# which can be disregarded in this case. -if -Bank Account -Bank Deposit to PP Account - description %type for %referencetxnid %itemtitle - account2 assets:bank:wf:pchecking - account1 assets:online:paypal - -# Currency conversions -if Currency Conversion - account2 equity:currency conversion - -# common.rules - -if -darcs -noble benefactor - account2 revenues:foss donations:darcshub - comment2 business: - -if -Calm Radio - account2 expenses:online:apps - -if -electronic frontier foundation -Patreon -wikimedia -Advent of Code - account2 expenses:dues - -if Google - account2 expenses:online:apps - description google | music - -$ hledger -f paypal-custom.csv print -2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed - assets:online:paypal $-6.99 = $-6.99 - expenses:online:apps $6.99 - -2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $6.99 = $0.00 - assets:bank:wf:pchecking $-6.99 - -2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed - assets:online:paypal $-7.00 = $-7.00 - expenses:dues $7.00 - -2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $7.00 = $0.00 - assets:bank:wf:pchecking $-7.00 - -2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed - assets:online:paypal $-2.00 = $-2.00 - expenses:dues $2.00 - expenses:banking:paypal ; business: - -2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $2.00 = $0.00 - assets:bank:wf:pchecking $-2.00 - -2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed - assets:online:paypal $9.41 = $9.41 - revenues:foss donations:darcshub $-10.00 ; business: - expenses:banking:paypal $0.59 ; business: - - -File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top - -11 Timeclock -************ - -The time logging format of timeclock.el, as read by hledger. - - hledger can read time logs in timeclock format. As with Ledger, -these are (a subset of) timeclock.el's format, containing clock-in and -clock-out entries as in the example below. The date is a simple date. -The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are -optional. The timezone, if present, must be four digits and is ignored -(currently the time is always interpreted as a local time). Lines -beginning with '#' or ';' or '*', and blank lines, are ignored. - -i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: -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 2 spaces ; optional comment, tags: - (some account) 0.33h - -2015-03-31 * 22:21-23:59 - (another:account) 1.64h - -2015-04-01 * 00:00-02:00 - (another:account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - -$ hledger -f sample.timeclock balance # current time balances -$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 -$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - * use emacs and the built-in timeclock.el, or the extended - timeclock-x.el and perhaps the extras in ledgerutils.el - - * at the command line, use these bash aliases: 'shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' - - * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. - These rely on a "timeclock" executable which I think is just the - ledger 2 executable renamed. - - -File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top - -12 Timedot -********** - -'timedot' format is hledger's human-friendly time logging format. -Compared to 'timeclock' format, it is more convenient for quick, -approximate, and retroactive time logging, and more human-readable (you -can see at a glance where time was spent). A quick example: - -2023-05-01 -hom:errands .... .... ; two hours; the space is ignored -fos:hledger:timedot .. ; half an hour -per:admin:finance ; no time spent yet - - hledger reads this as a transaction on this day with three -(unbalanced) postings, where each dot represents "0.25". No commodity -symbol is assumed, but we typically interpret it as hours. - -$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required -2023-05-01 * - (hom:errands) 2.00 ; two hours - (fos:hledger:timedot) 0.50 ; half an hour - (per:admin:finance) 0 - - A timedot file contains a series of transactions (usually one per -day). Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D), -optionally be followed on the same line by a transaction description, -and/or a transaction comment following a semicolon. - - After the date line are zero or more time postings, consisting of: - - * *An account name* - any hledger-style account name, optionally - indented. - - * *Two or more spaces* - required if there is an amount (as in - journal format). - - * *A timedot amount*, which can be - - * empty (representing zero) - - * a number, optionally followed by a unit 's', 'm', 'h', 'd', - 'w', 'mo', or 'y', representing a precise number of seconds, - minutes, hours, days weeks, months or years (hours is assumed - by default), which will be converted to hours according to 60s - = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. - - * one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can - be used for grouping/alignment. - - * one or more letters. These are like dots but they also - generate a tag 't:' (short for "type") with the letter as its - value, and a separate posting for each of the values. This - provides a second dimension of categorisation, viewable in - reports with '--pivot t'. - - * *An optional comment* following a semicolon (a hledger-style - posting comment). - - There is some flexibility to help with keeping time log data and -notes in the same file: - - * Blank lines and lines beginning with '#' or ';' are ignored. - - * After the first date line, lines which do not contain a double - space are parsed as postings with zero amount. (hledger's register - reports will show these if you add -E). - - * Before the first date line, lines beginning with '*' (eg org - headings) are ignored. And from the first date line onward, Emacs - org mode heading prefixes at the start of lines (one or more '*''s - followed by a space) will be ignored. This means the time log can - also be a org outline. - -* Menu: - -* Timedot examples:: - - -File: hledger.info, Node: Timedot examples, Up: Timedot - -12.1 Timedot examples -===================== - -Numbers: - -2016/2/3 -inc:client1 4 -fos:hledger 3h -biz:research 60m - - Dots: - -# 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 . - -$ 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 - - Letters: - -# Activity types: -# c cleanup/catchup/repair -# e enhancement -# s support -# l learning/research - -2023-11-01 -work:adm ccecces - -$ hledger -f a.timedot print -2023-11-01 - (work:adm) 1 ; t:c - (work:adm) 0.5 ; t:e - (work:adm) 0.25 ; t:s - -$ hledger -f a.timedot bal - 1.75 work:adm --------------------- - 1.75 - -$ hledger -f a.timedot bal --pivot t - 1.00 c - 0.50 e - 0.25 s --------------------- - 1.75 - - Org: - -* 2023 Work Diary -** Q1 -*** 2023-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 - - Using '.' as account name separator: - -2016/2/4 -fos.hledger.timedot 4h -fos.ledger .. - -$ hledger -f a.timedot --alias '/\./=:' bal -t - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger --------------------- - 4.50 - - -File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Amount formatting parseability, Prev: Timedot, Up: Top - -13 PART 3: REPORTING CONCEPTS -***************************** - - -File: hledger.info, Node: Amount formatting parseability, Next: Time periods, Prev: PART 3 REPORTING CONCEPTS, Up: Top - -14 Amount formatting, parseability -********************************** - -If you're wondering why your 'print' report sometimes shows trailing -decimal marks, with no decimal digits; it does this when showing amounts -that have digit group marks but no decimal digits, to disambiguate them -and allow them to be re-parsed reliably (see also Decimal marks, digit -group marks. Eg: - -commodity $1,000.00 - -2023-01-02 - (a) $1000 - -$ hledger print -2023-01-02 - (a) $1,000. - - If this is a problem (eg when exporting to Ledger), you can avoid it -by disabling digit group marks, eg with -c/-commodity (for each affected -commodity): - -$ hledger print -c '$1000.00' -2023-01-02 - (a) $1000 - - or by forcing print to always show decimal digits, with -round: - -$ hledger print -c '$1,000.00' --round=soft -2023-01-02 - (a) $1,000.00 - - More generally: hledger output falls into three rough categories, -which format amounts a little bit differently to suit different -consumers: - - *1. "hledger-readable output" - should be readable by hledger (and -by humans)* - - * This is produced by reports that show full journal entries: - 'print', 'import', 'close', 'rewrite' etc. - * It shows amounts with their original journal precisions, which may - not be consistent. - * It adds a trailing decimal mark when needed to avoid showing - ambiguous amounts. - * It can be parsed reliably (by hledger and ledger2beancount at - least, but perhaps not by Ledger..) - - *2. "human-readable output" - usually for humans* - - * This is produced by all other reports. - * It shows amounts with standard display precisions, which will be - consistent within each commodity. - * It shows ambiguous amounts unmodified. - * It can be parsed reliably in the context of a known report (when - you know decimals are consistently not being shown, you can assume - a single mark is a digit group mark). - - *3. "machine-readable output" - usually for other software* - - * This is produced by all reports when an output format like 'csv', - 'tsv', 'json', or 'sql' is selected. - * It shows amounts as 1 or 2 do, but without digit group marks. - * It can be parsed reliably (if needed, the decimal mark can be - changed with -c/-commodity-style). - - -File: hledger.info, Node: Time periods, Next: Depth, Prev: Amount formatting parseability, Up: Top - -15 Time periods -*************** - -* Menu: - -* Report start & end date:: -* Smart dates:: -* Report intervals:: -* Date adjustment:: -* Period expressions:: - - -File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods - -15.1 Report start & end date -============================ - -By default, most hledger reports will show the full span of time -represented by the journal. The report start date will be the earliest -transaction or posting date, and the report end date will be the latest -transaction, posting, or market price date. - - Often you will want to see a shorter time span, such as the current -month. You can specify a start and/or end date using '-b/--begin', -'-e/--end', '-p/--period' or a 'date:' query (described below). All of -these accept the smart date syntax (below). - - Some notes: - - * End dates are exclusive, as in Ledger, so you should write the date - _after_ the last day you want to see in the report. - * As noted in reporting options: among start/end dates specified with - _options_, the last (i.e. right-most) option takes precedence. - * The effective report start and end dates are the intersection of - the start/end dates from options and that from 'date:' queries. - That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January - 2019, the smallest common time span. - * In some cases a report interval will adjust start/end dates to fall - on interval boundaries (see below). - - Examples: - -'-b begin on St. Patrick's day 2016 -2016/3/17' -'-e 12/1' end at the start of december 1st of the current year - (11/30 will be the last date included) -'-b all transactions on or after the 1st of the current month -thismonth' -'-p all transactions in the current month -thismonth' -'date:2016/3/17..'the above written as queries instead ('..' can also be - replaced with '-') -'date:..12/1' -'date:thismonth..' -'date:thismonth' - - -File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods - -15.2 Smart dates -================ - -hledger's user interfaces accept a "smart date" syntax for added -convenience. Smart dates optionally can be relative to today's date, be -written with english words, and have less-significant parts omitted -(missing parts are inferred as 1). Some examples: - -'2004/10/1', exact date, several separators allowed. Year -'2004-01-01', is 4+ digits, month is 1-12, day is 1-31 -'2004.9.1' -'2004' start of year -'2004/10' start of month -'10/1' month and day in current year -'21' day in current month -'october, oct' start of month in current year -'yesterday, today, -1, 0, 1 days from today -tomorrow' -'last/this/next -1, 0, 1 periods from the current period -day/week/month/quarter/year' -'in n n periods from the current period -days/weeks/months/quarters/years' -'n n periods from the current period -days/weeks/months/quarters/years -ahead' -'n -n periods from the current period -days/weeks/months/quarters/years -ago' -'20181201' 8 digit YYYYMMDD with valid year month and - day -'201812' 6 digit YYYYMM with valid year and month - - Some counterexamples - malformed digit sequences might give -surprising results: - -'201813' 6 digits with an invalid month is parsed as start of - 6-digit year -'20181301' 8 digits with an invalid month is parsed as start of - 8-digit year -'20181232' 8 digits with an invalid day gives an error -'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error - - "Today's date" can be overridden with the '--today' option, in case -it's needed for testing or for recreating old reports. (Except for -periodic transaction rules, which are not affected by '--today'.) - - -File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods - -15.3 Report intervals -===================== - -A report interval can be specified so that reports like register, -balance or activity become multi-period, showing each subperiod as a -separate row or column. - - The following standard intervals can be enabled with command-line -flags: - - * '-D/--daily' - * '-W/--weekly' - * '-M/--monthly' - * '-Q/--quarterly' - * '-Y/--yearly' - - More complex intervals can be specified using '-p/--period', -described below. - - -File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods - -15.4 Date adjustment -==================== - -When there is a report interval (other than daily), report start/end -dates which have been inferred, eg from the journal, are automatically -adjusted to natural period boundaries. This is convenient for producing -simple periodic reports. More precisely: - - * an inferred start date will be adjusted earlier if needed to fall - on a natural period boundary - - * an inferred end date will be adjusted later if needed to make the - last period the same length as the others. - - By contrast, start/end dates which have been specified explicitly, -with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger -1.29). This makes it possible to specify non-standard report periods, -but it also means that if you are specifying a start date, you should -pick one that's on a period boundary if you want to see simple report -period headings. - - -File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods - -15.5 Period expressions -======================= - -The '-p/--period' option specifies a period expression, which is a -compact way of expressing a start date, end date, and/or report -interval. - - Here's a period expression with a start and end date (specifying the -first quarter of 2009): - -'-p "from 2009/1/1 to 2009/4/1"' - - Several keywords like "from" and "to" are supported for readability; -these are optional. "to" can also be written as ".." or "-". The -spaces are also optional, as long as you don't run two dates together. -So the following are equivalent to the above: - -'-p "2009/1/1 2009/4/1"' -'-p2009/1/1to2009/4/1' -'-p2009/1/1..2009/4/1' - - Dates are smart dates, so if the current year is 2009, these are also -equivalent to the above: - -'-p "1/1 4/1"' -'-p "jan-apr"' -'-p "this year to 4/1"' - - If you specify only one date, the missing start or end date will be -the earliest or latest transaction date in the journal: - -'-p "from 2009/1/1"' everything after january 1, 2009 -'-p "since 2009/1"' the same, since is a synonym -'-p "from 2009"' the same -'-p "to 2009"' everything before january 1, 2009 - - You can also specify a period by writing a single partial or full -date: - -'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” -'-p "2009/1"' the month of january 2009; equivalent to “2009/1/1 to - 2009/2/1” -'-p the first day of 2009; equivalent to “2009/1/1 to -"2009/1/1"' 2009/1/2” - - or by using the "Q" quarter-year syntax (case insensitive): - -'-p "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to - 2009/4/1” -'-p "q4"' fourth quarter of the current year - -* Menu: - -* Period expressions with a report interval:: -* More complex report intervals:: -* Multiple weekday intervals:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -15.5.1 Period expressions with a report interval ------------------------------------------------- - -A period expression can also begin with a report interval, separated -from the start/end dates (if any) by a space or the word 'in': - -'-p "weekly from 2009/1/1 to 2009/4/1"' -'-p "monthly in 2008"' -'-p "quarterly"' - - -File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions - -15.5.2 More complex report intervals ------------------------------------- - -Some more complex intervals can be specified within period expressions, -such as: - - * 'biweekly' (every two weeks) - * 'fortnightly' - * 'bimonthly' (every two months) - * 'every day|week|month|quarter|year' - * 'every N days|weeks|months|quarters|years' - - Weekly on a custom day: - - * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted - after the number) - * 'every WEEKDAYNAME' (full or three-letter english weekday name, - case insensitive) - - Monthly on a custom day: - - * 'every Nth day [of month]' - * 'every Nth WEEKDAYNAME [of month]' - - Yearly on a custom day: - - * 'every MM/DD [of year]' (month number and day of month number) - * 'every MONTHNAME DDth [of year]' (full or three-letter english - month name, case insensitive, and day of month number) - * 'every DDth MONTHNAME [of year]' (equivalent to the above) - - Examples: - -'-p "bimonthly from -2008"' -'-p "every 2 weeks"' -'-p "every 5 months from -2009/03"' -'-p "every 2nd day of periods will go from Tue to Tue -week"' -'-p "every Tue"' same -'-p "every 15th day"' period boundaries will be on 15th of each - month -'-p "every 2nd Monday"' period boundaries will be on second Monday - of each month -'-p "every 11/05"' yearly periods with boundaries on 5th of - November -'-p "every 5th November"' same -'-p "every Nov 5th"' same - - Show historical balances at end of the 15th day of each month (N is -an end date, exclusive as always): - -$ hledger balance -H -p "every 16th day" - - Group postings from the start of wednesday to end of the following -tuesday (N is both (inclusive) start date and (exclusive) end date): - -$ hledger register checking -p "every 3rd day of week" - - -File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions - -15.5.3 Multiple weekday intervals ---------------------------------- - -This special form is also supported: - - * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english - weekday names, case insensitive) - - Also, 'weekday' and 'weekendday' are shorthand for -'mon,tue,wed,thu,fri' and 'sat,sun'. - - This is mainly intended for use with '--forecast', to generate -periodic transactions on arbitrary days of the week. It may be less -useful with '-p', since it divides each week into subperiods of unequal -length, which is unusual. (Related: #1632) - - Examples: - -'-p "every dates will be Mon, Wed, Fri; periods will be -mon,wed,fri"' Mon-Tue, Wed-Thu, Fri-Sun -'-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will -weekday"' be Mon, Tue, Wed, Thu, Fri-Sun -'-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri -weekendday"' - - -File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top - -16 Depth -******** - -With the '--depth NUM' option (short form: '-NUM'), reports will show -accounts only to the specified depth, hiding deeper subaccounts. Use -this when you want a summary with less detail. This flag has the same -effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are -equivalent. - - -File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top - -17 Queries -********** - -One of hledger's strengths is being able to quickly report on a precise -subset of your data. Most hledger commands accept optional query -arguments to restrict their scope. The syntax is as follows: - - * Zero or more space-separated query terms. These are most often - account name substrings: - - 'utilities food:groceries' - - * Terms with spaces or other special characters should be enclosed in - quotes: - - '"personal care"' - - * Regular expressions are also supported: - - '"^expenses\b"' - '"accounts (payable|receivable)"' - - * Add a query type prefix to match other parts of the data: - - 'date:202312-' - 'status:' - 'desc:amazon' - 'cur:USD' - '"amt:>0"' - - * Add a 'not:' prefix to negate: - - 'not:cur:USD' - - * Multiple unlike terms are AND-ed, multiple like terms are OR-ed - - 'date:2022 desc:amazon desc:amzn' - (all transactions with "amazon" or "amzn" in description during - 2022) - -* Menu: - -* Query types:: -* Combining query terms:: -* Queries and command options:: -* Queries and valuation:: -* Querying with account aliases:: -* Querying with cost or value:: - - -File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries - -17.1 Query types -================ - -Here are the types of query term available. Remember these can also be -prefixed with *'not:'* to convert them into a negative match. - - *'acct:REGEX', 'REGEX'* -Match account names containing this (case insensitive) regular -expression. This is the default query type when there is no prefix, and -regular expression syntax is typically not needed, so usually we just -write an account name substring, like 'expenses' or 'food'. - - *'amt:N, amt:N, amt:>=N'* -Match postings with a single-commodity amount equal to, less than, or -greater than N. (Postings with multi-commodity amounts are not tested -and will always match.) The comparison has two modes: if N is preceded -by a + or - sign (or is 0), the two signed numbers are compared. -Otherwise, the absolute magnitudes are compared, ignoring sign. - - *'code:REGEX'* -Match by transaction code (eg check number). - - *'cur:REGEX'* -Match postings or transactions including any amounts whose -currency/commodity symbol is fully matched by REGEX. (For a partial -match, use '.*REGEX.*'). Note, to match special characters which are -regex-significant, you need to escape them with '\'. And for characters -which are significant to your shell you may need one more level of -escaping. So eg to match the dollar sign: -'hledger print cur:\\$'. - - *'desc:REGEX'* -Match transaction descriptions. - - *'date:PERIODEXPR'* -Match dates (or with the '--date2' flag, secondary dates) within the -specified period. PERIODEXPR is a period expression with no report -interval. Examples: -'date:2016', 'date:thismonth', 'date:2/1-2/15', -'date:2021-07-27..nextquarter'. - - *'date2:PERIODEXPR'* -Match secondary dates within the specified period (independent of the -'--date2' flag). - - *'depth:N'* -Match (or display, depending on command) accounts at or above this -depth. - - *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg) -Match with a boolean combination of queries (which must be enclosed in -quotes). See Combining query terms below. - - *'note:REGEX'* -Match transaction notes (the part of the description right of '|', or -the whole description if there's no '|'). - - *'payee:REGEX'* -Match transaction payee/payer names (the part of the description left of -'|', or the whole description if there's no '|'). - - *'real:, real:0'* -Match real or virtual postings respectively. - - *'status:, status:!, status:*'* -Match unmarked, pending, or cleared transactions respectively. - - *'type:TYPECODES'* -Match by account type (see Declaring accounts > Account types). -'TYPECODES' is one or more of the single-letter account type codes -'ALERXCV', case insensitive. Note 'type:A' and 'type:E' will also match -their respective subtypes 'C' (Cash) and 'V' (Conversion). Certain -kinds of account alias can disrupt account types, see Rewriting accounts -> Aliases and account types. - - *'tag:REGEX[=REGEX]'* -Match by tag name, and optionally also by tag value. (To match only by -value, use 'tag:.=REGEX'.) - - When querying by tag, note that: - - * Accounts also inherit the tags of their parent accounts - * Postings also inherit the tags of their account and their - transaction - * Transactions also acquire the tags of their postings. - - (*'inacct:ACCTNAME'* -A special query term used automatically in hledger-web only: tells -hledger-web to show the transaction register for an account.) - - -File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries - -17.2 Combining query terms -========================== - -When given multiple space-separated query terms, most commands select -things which match: - - * any of the description terms AND - * any of the account terms AND - * any of the status terms AND - * all the other terms. - - The print command is a little different, showing transactions which: - - * match any of the description terms AND - * have any postings matching any of the positive account terms AND - * have no postings matching any of the negative account terms AND - * match all the other terms. - - We also support more complex boolean queries with the 'expr:' prefix. -This allows one to combine queries using one of three operators: AND, -OR, and NOT, where NOT is different syntax for 'not:'. - - Examples of such queries are: - - * Match transactions with 'cool' in the description AND with the 'A' - tag - - 'expr:"desc:cool AND tag:A"' - - * Match transactions NOT to the 'expenses:food' account OR with the - 'A' tag - - 'expr:"NOT expenses:food OR tag:A"' - - * Match transactions NOT involving the 'expenses:food' account OR - with the 'A' tag AND involving the 'expenses:drink' account. (the - AND is implicitly added by space-separation, following the rules - above) - - 'expr:"expenses:food OR (tag:A expenses:drink)"' - - -File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries - -17.3 Queries and command options -================================ - -Some queries can also be expressed as command-line options: 'depth:2' is -equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. -When you mix command options and query arguments, generally the -resulting query is their intersection. - - -File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries - -17.4 Queries and valuation -========================== - -When amounts are converted to other commodities in cost or value -reports, 'cur:' and 'amt:' match the old commodity symbol and the old -amount quantity, not the new ones (except in hledger 1.22.0 where it's -reversed, see #1625). - - -File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries - -17.5 Querying with account aliases -================================== - -When account names are rewritten with '--alias' or 'alias', note that -'acct:' will match either the old or the new account name. - - -File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries - -17.6 Querying with cost or value -================================ - -When amounts are converted to other commodities in cost or value -reports, note that 'cur:' matches the new commodity symbol, and not the -old one, and 'amt:' matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, see -the discussion at #1625. - - -File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top - -18 Pivoting -*********** - -Normally, hledger groups and sums amounts within each account. The -'--pivot FIELD' option substitutes some other transaction field for -account names, causing amounts to be grouped and summed by that field's -value instead. FIELD can be any of the transaction fields 'acct', -'status', 'code', 'desc', 'payee', 'note', or a tag name. When pivoting -on a tag and a posting has multiple values of that tag, only the first -value is displayed. Values containing 'colon:separated:parts' will be -displayed hierarchically, like account names. Multiple, colon-delimited -fields can be pivoted simultaneously, generating a hierarchical account -name. - - Some examples: - -2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe, kind: Lifetime - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues --------------------- - 0 - - Pivoted balance report, using member: tag values instead: - -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 - - One way to show only amounts with a member: value (using a query): - -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account -name"): - -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR - - Hierarchical reports can be generated with multiple pivots: - -$ hledger balance Income:Dues --pivot kind:member - -2 EUR Lifetime:John Doe --------------------- - -2 EUR - - -File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top - -19 Generating data -****************** - -hledger has several features for generating data, such as: - - * Periodic transaction rules can generate single or repeating - transactions following a template. These are usually dated in the - future, eg to help with forecasting. They are activated by the - '--forecast' option. - - * The balance command's '--budget' option uses these same periodic - rules to generate goals for the budget report. - - * Auto posting rules can generate extra postings on certain matched - transactions. They are always applied to forecast transactions; - with the '--auto' flag they are applied to transactions recorded in - the journal as well. - - * The '--infer-equity' flag infers missing conversion equity postings - from @/@@ costs. And the inverse '--infer-costs' flag infers - missing @/@@ costs from conversion equity postings. - - Generated data of this kind is temporary, existing only at report -time. But you can see it in the output of 'hledger print', and you can -save that to your journal, in effect converting it from temporary -generated data to permanent recorded data. This could be useful as a -data entry aid. - - If you are wondering what data is being generated and why, add the -'--verbose-tags' flag. In 'hledger print' output you will see extra -tags like 'generated-transaction', 'generated-posting', and 'modified' -on generated/modified data. Also, even without '--verbose-tags', -generated data always has equivalen hidden tags (with an underscore -prefix), so eg you could match generated transactions with -'tag:_generated-transaction'. - - -File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top - -20 Forecasting -************** - -Forecasting, or speculative future reporting, can be useful for -estimating future balances, or for exploring different future scenarios. - - The simplest and most flexible way to do it with hledger is to -manually record a bunch of future-dated transactions. You could keep -these in a separate 'future.journal' and include that with '-f' only -when you want to see them. - -* Menu: - -* --forecast:: -* Inspecting forecast transactions:: -* Forecast reports:: -* Forecast tags:: -* Forecast period in detail:: -* Forecast troubleshooting:: - - -File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting - -20.1 -forecast -============== - -There is another way: with the '--forecast' option, hledger can generate -temporary "forecast transactions" for reporting purposes, according to -periodic transaction rules defined in the journal. Each rule can -generate multiple recurring transactions, so by changing one rule you -can change many forecasted transactions. (These same rules can also -generate budget goals, described in Budgeting.) - - Forecast transactions usually start after ordinary transactions end. -By default, they begin after your latest-dated ordinary transaction, or -today, whichever is later, and they end six months from today. (The -exact rules are a little more complicated, and are given below.) - - This is the "forecast period", which need not be the same as the -report period. You can override it - eg to forecast farther into the -future, or to force forecast transactions to overlap your ordinary -transactions - by giving the -forecast option a period expression -argument, like '--forecast=..2099' or '--forecast=2023-02-15..'. Note -that the '=' is required. - - -File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting - -20.2 Inspecting forecast transactions -===================================== - -'print' is the best command for inspecting and troubleshooting forecast -transactions. Eg: - -~ monthly from 2022-12-20 rent - assets:bank:checking - expenses:rent $1000 - -$ hledger print --forecast --today=2023/4/21 -2023-05-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-06-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-07-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-08-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-09-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - Here there are no ordinary transactions, so the forecasted -transactions begin on the first occurence after today's date. (You -won't normally use '--today'; it's just to make these examples -reproducible.) - - -File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting - -20.3 Forecast reports -===================== - -Forecast transactions affect all reports, as you would expect. Eg: - -$ hledger areg rent --forecast --today=2023/4/21 -Transactions in expenses:rent and subaccounts: -2023-05-20 rent as:ba:checking $1000 $1000 -2023-06-20 rent as:ba:checking $1000 $2000 -2023-07-20 rent as:ba:checking $1000 $3000 -2023-08-20 rent as:ba:checking $1000 $4000 -2023-09-20 rent as:ba:checking $1000 $5000 - -$ hledger bal -M expenses --forecast --today=2023/4/21 -Balance changes in 2023-05-01..2023-09-30: - - || May Jun Jul Aug Sep -===============++=================================== - expenses:rent || $1000 $1000 $1000 $1000 $1000 ----------------++----------------------------------- - || $1000 $1000 $1000 $1000 $1000 - - -File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting - -20.4 Forecast tags -================== - -Forecast transactions generated by -forecast have a hidden tag, -'_generated-transaction'. So if you ever need to match forecast -transactions, you could use 'tag:_generated-transaction' (or just -'tag:generated') in a query. - - For troubleshooting, you can add the '--verbose-tags' flag. Then, -visible 'generated-transaction' tags will be added also, so you can view -them with the 'print' command. Their value indicates which periodic -rule was responsible. - - -File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting - -20.5 Forecast period, in detail -=============================== - -Forecast start/end dates are chosen so as to do something useful by -default in almost all situations, while also being flexible. Here are -(with luck) the exact rules, to help with troubleshooting: - - The forecast period starts on: - - * the later of - * the start date in the periodic transaction rule - * the start date in '--forecast''s argument - - * otherwise (if those are not available): the later of - * the report start date specified with '-b'/'-p'/'date:' - * the day after the latest ordinary transaction in the journal - - * otherwise (if none of these are available): today. - - The forecast period ends on: - - * the earlier of - * the end date in the periodic transaction rule - * the end date in '--forecast''s argument - - * otherwise: the report end date specified with '-e'/'-p'/'date:' - * otherwise: 180 days (~6 months) from today. - - -File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting - -20.6 Forecast troubleshooting -============================= - -When -forecast is not doing what you expect, one of these tips should -help: - - * Remember to use the '--forecast' option. - * Remember to have at least one periodic transaction rule in your - journal. - * Test with 'print --forecast'. - * Check for typos or too-restrictive start/end dates in your periodic - transaction rule. - * Leave at least 2 spaces between the rule's period expression and - description fields. - * Check for future-dated ordinary transactions suppressing forecasted - transactions. - * Try setting explicit report start and/or end dates with '-b', '-e', - '-p' or 'date:' - * Try adding the '-E' flag to encourage display of empty periods/zero - transactions. - * Try setting explicit forecast start and/or end dates with - '--forecast=START..END' - * Consult Forecast period, in detail, above. - * Check inside the engine: add '--debug=2' (eg). - - -File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top - -21 Budgeting -************ - -With the balance command's '--budget' report, each periodic transaction -rule generates recurring budget goals in specified accounts, and goals -and actual performance can be compared. See the balance command's doc -below. - - You can generate budget goals and forecast transactions at the same -time, from the same or different periodic transaction rules: 'hledger -bal -M --budget --forecast ...' - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Budgeting, Up: Top - -22 Cost reporting -***************** - -In some transactions - for example a currency conversion, or a purchase -or sale of stock - one commodity is exchanged for another. In these -transactions there is a conversion rate, also called the cost (when -buying) or selling price (when selling). In hledger docs we just say -"cost", for convenience; feel free to mentally translate to "conversion -rate" or "selling price" if helpful. - -* Menu: - -* Recording costs:: -* Reporting at cost:: -* Equity conversion postings:: -* Inferring equity conversion postings:: -* Combining costs and equity conversion postings:: -* Requirements for detecting equity conversion postings:: -* Infer cost and equity by default ?:: - - -File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting - -22.1 Recording costs -==================== - -We'll explore several ways of recording transactions involving costs. -These are also summarised at hledger Cookbook > Cost notation. - - Costs can be recorded explicitly in the journal, using the '@ -UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs: - - *Variant 1* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 ; $1.35 per euro (unit cost) - - *Variant 2* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 @@ $135 ; $135 total cost - - Typically, writing the unit cost (variant 1) is preferable; it can be -more effort, requiring more attention to decimal digits; but it reveals -the per-unit cost basis, and makes stock sales easier. - - Costs can also be left implicit, and hledger will infer the cost that -is consistent with a balanced transaction: - - *Variant 3* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 - - Here, hledger will attach a '@@ €100' cost to the first amount (you -can see it with 'hledger print -x'). This form looks convenient, but -there are downsides: - - * It sacrifices some error checking. For example, if you - accidentally wrote €10 instead of €100, hledger would not be able - to detect the mistake. - - * It is sensitive to the order of postings - if they were reversed, a - different entry would be inferred and reports would be different. - - * The per-unit cost basis is not easy to read. - - So generally this kind of entry is not recommended. You can make -sure you have none of these by using '-s' (strict mode), or by running -'hledger check balanced'. - - -File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting - -22.2 Reporting at cost -====================== - -Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's --B/-basis/-cost flag), any amounts which have been annotated with costs -will be converted to their cost's commodity (in the report output). Ie -they will be displayed "at cost" or "at sale price". - - Some things to note: - - * Costs are attached to specific posting amounts in specific - transactions, and once recorded they do not change. This contrasts - with market prices, which are ambient and fluctuating. - - * Conversion to cost is performed before conversion to market value - (described below). - - -File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting - -22.3 Equity conversion postings -=============================== - -There is a problem with the entries above - they are not conventional -Double Entry Bookkeeping (DEB) notation, and because of the "magical" -transformation of one commodity into another, they cause an imbalance in -the Accounting Equation. This shows up as a non-zero grand total in -balance reports like 'hledger bse'. - - For most hledger users, this doesn't matter in practice and can -safely be ignored ! But if you'd like to learn more, keep reading. - - Conventional DEB uses an extra pair of equity postings to balance the -transaction. Of course you can do this in hledger as well: - - *Variant 4* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 - equity:conversion $135 - equity:conversion €-100 - - Now the transaction is perfectly balanced according to standard DEB, -and 'hledger bse''s total will not be disrupted. - - And, hledger can still infer the cost for cost reporting, but it's -not done by default - you must add the '--infer-costs' flag like so: - -$ hledger print --infer-costs -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 @@ €100 - assets:euros €100 - equity:conversion $135 - equity:conversion €-100 - -$ hledger bal --infer-costs -B - €-100 assets:dollars - €100 assets:euros --------------------- - 0 - - Here are some downsides of this kind of entry: - - * The per-unit cost basis is not easy to read. - - * Instead of '-B' you must remember to type '-B --infer-costs'. - - * '--infer-costs' works only where hledger can identify the two - equity:conversion postings and match them up with the two - non-equity postings. So writing the journal entry in a particular - format becomes more important. More on this below. - - -File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting - -22.4 Inferring equity conversion postings -========================================= - -Can we go in the other direction ? Yes, if you have transactions -written with the @/@@ cost notation, hledger can infer the missing -equity postings, if you add the '--infer-equity' flag. Eg: - -2022-01-01 - assets:dollars -$135 - assets:euros €100 @ $1.35 - -$ hledger print --infer-equity -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 - equity:conversion:$-€:€ €-100 - equity:conversion:$-€:$ $135.00 - - The equity account names will be "equity:conversion:A-B:A" and -"equity:conversion:A-B:B" where A is the alphabetically first commodity -symbol. You can customise the "equity:conversion" part by declaring an -account with the 'V'/'Conversion' account type. - - -File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting - -22.5 Combining costs and equity conversion postings -=================================================== - -Finally, you can use both the @/@@ cost notation and equity postings at -the same time. This in theory gives the best of all worlds - preserving -the accounting equation, revealing the per-unit cost basis, and -providing more flexibility in how you write the entry: - - *Variant 5* - -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 @ $1.35 - - All the other variants above can (usually) be rewritten to this final -form with: - -$ hledger print -x --infer-costs --infer-equity - - Downsides: - - * This was added in hledger-1.29 and is still somewhat experimental. - - * The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it - will give a transaction balancing error. - - * The add command does not yet accept this kind of entry (#2056). - - * This is the most verbose form. - - -File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting - -22.6 Requirements for detecting equity conversion postings -========================================================== - -'--infer-costs' has certain requirements (unlike '--infer-equity', which -always works). It will infer costs only in transactions with: - - * Two non-equity postings, in different commodities. Their order is - significant: the cost will be added to the first of them. - - * Two postings to equity conversion accounts, next to one another, - which balance the two non-equity postings. This balancing is - checked to the same precision (number of decimal places) used in - the conversion posting's amount. Equity conversion accounts are: - - * any accounts declared with account type 'V'/'Conversion', or - their subaccounts - * otherwise, accounts named 'equity:conversion', 'equity:trade', - or 'equity:trading', or their subaccounts. - - And multiple such four-posting groups can coexist within a single -transaction. When '--infer-costs' fails, it does not infer a cost in -that transaction, and does not raise an error (ie, it infers costs where -it can). - - Reading variant 5 journal entries, combining cost notation and equity -postings, has all the same requirements. When reading such an entry -fails, hledger raises an "unbalanced transaction" error. - - -File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting - -22.7 Infer cost and equity by default ? -======================================= - -Should '--infer-costs' and '--infer-equity' be enabled by default ? Try -using them always, eg with a shell alias: - -alias h="hledger --infer-equity --infer-costs" - - and let us know what problems you find. - - -File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top - -23 Value reporting -****************** - -Instead of reporting amounts in their original commodity, hledger can -convert them to cost/sale amount (using the conversion rate recorded in -the transaction), and/or to market value (using some market price on a -certain date). This is controlled by the '--value=TYPE[,COMMODITY]' -option, which will be described below. We also provide the simpler '-V' -and '-X COMMODITY' options, and often one of these is all you need: - -* Menu: - -* -V Value:: -* -X Value in specified commodity:: -* Valuation date:: -* Finding market price:: -* --infer-market-prices market prices from transactions:: -* Valuation commodity:: -* Simple valuation examples:: -* --value Flexible valuation:: -* More valuation examples:: -* Interaction of valuation and queries:: -* Effect of valuation on reports:: - - -File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Value reporting - -23.1 -V: Value -============== - -The '-V/--market' flag converts amounts to market value in their default -_valuation commodity_, using the market prices in effect on the -_valuation date(s)_, if any. More on these in a minute. - - -File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Value reporting - -23.2 -X: Value in specified commodity -===================================== - -The '-X/--exchange=COMM' option is like '-V', except you tell it which -currency you want to convert to, and it tries to convert everything to -that. - - -File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Value reporting - -23.3 Valuation date -=================== - -Market prices can change from day to day. hledger will use the prices -on a particular valuation date (or on more than one date). By default -hledger uses "end" dates for valuation. More specifically: - - * For single period reports (including normal print and register - reports): - * If an explicit report end date is specified, that is used - * Otherwise the latest transaction date or P directive date is - used (even if it's in the future) - - * For multiperiod reports, each period is valued on its last day. - - This can be customised with the -value option described below, which -can select either "then", "end", "now", or "custom" dates. (Note, this -has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key -always resets it to "end".) - - -File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting - -23.4 Finding market price -========================= - -To convert a commodity A to its market value in another commodity B, -hledger looks for a suitable market price (exchange rate) as follows, in -this order of preference: - - 1. A _declared market price_ or _inferred market price_: A's latest - market price in B on or before the valuation date as declared by a - P directive, or (with the '--infer-market-prices' flag) inferred - from costs. - - 2. A _reverse market price_: the inverse of a declared or inferred - market price from B to A. - - 3. A _forward chain of market prices_: a synthetic price formed by - combining the shortest chain of "forward" (only 1 above) market - prices, leading from A to B. - - 4. _Any chain of market prices_: a chain of any market prices, - including both forward and reverse prices (1 and 2 above), leading - from A to B. - - There is a limit to the length of these price chains; if hledger -reaches that length without finding a complete chain or exhausting all -possibilities, it will give up (with a "gave up" message visible in -'--debug=2' output). That limit is currently 1000. - - Amounts for which no suitable market price can be found, are not -converted. - - -File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting - -23.5 -infer-market-prices: market prices from transactions -========================================================== - -Normally, market value in hledger is fully controlled by, and requires, -P directives in your journal. Since adding and updating those can be a -chore, and since transactions usually take place at close to market -value, why not use the recorded costs as additional market prices (as -Ledger does) ? Adding the '--infer-market-prices' flag to '-V', '-X' or -'--value' enables this. - - So for example, 'hledger bs -V --infer-market-prices' will get market -prices both from P directives and from transactions. If both occur on -the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in -confusing/undesired ways by your journal entries. If this happens to -you, read all of this Value reporting section carefully, and try adding -'--debug' or '--debug=2' to troubleshoot. - - '--infer-market-prices' can infer market prices from: - - * multicommodity transactions with explicit prices ('@'/'@@') - - * multicommodity transactions with implicit prices (no '@', two - commodities, unbalanced). (With these, the order of postings - matters. 'hledger print -x' can be useful for troubleshooting.) - - * multicommodity transactions with equity postings, if cost is - inferred with '--infer-costs'. - - There is a limitation (bug) currently: when a valuation commodity is -not specified, prices inferred with '--infer-market-prices' do not help -select a default valuation commodity, as 'P' prices would. So -conversion might not happen because no valuation commodity was detected -('--debug=2' will show this). To be safe, specify the valuation -commmodity, eg: - - * '-X EUR --infer-market-prices', not '-V --infer-market-prices' - * '--value=then,EUR --infer-market-prices', not '--value=then - --infer-market-prices' - - Signed costs and market prices can be confusing. For reference, here -is the current behaviour, since hledger 1.25. (If you think it should -work differently, see #1870.) - -2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - -2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - -2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - -2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - -2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - -2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each -day, the two transactions are considered equivalent). Here are the -market prices inferred for B: - -$ hledger -f- --infer-market-prices prices -P 2022-01-01 B A 1 -P 2022-01-01 B A 1.0 -P 2022-01-02 B A -1 -P 2022-01-02 B A -1.0 -P 2022-01-03 B A -1 -P 2022-01-03 B A -1.0 - - -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Value reporting - -23.6 Valuation commodity -======================== - -*When you specify a valuation commodity ('-X COMM' or '--value -TYPE,COMM'):* -hledger will convert all amounts to COMM, wherever it can find a -suitable market price (including by reversing or chaining prices). - - *When you leave the valuation commodity unspecified ('-V' or '--value -TYPE'):* -For each commodity A, hledger picks a default valuation commodity as -follows, in this order of preference: - - 1. The price commodity from the latest P-declared market price for A - on or before valuation date. - - 2. The price commodity from the latest P-declared market price for A - on any date. (Allows conversion to proceed when there are inferred - prices before the valuation date.) - - 3. If there are no P directives at all (any commodity or date) and the - '--infer-market-prices' flag is used: the price commodity from the - latest transaction-inferred price for A on or before valuation - date. - - This means: - - * If you have P directives, they determine which commodities '-V' - will convert, and to what. - - * If you have no P directives, and use the '--infer-market-prices' - flag, costs determine it. - - Amounts for which no valuation commodity can be found are not -converted. - - -File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Value reporting - -23.7 Simple valuation examples -============================== - -Here are some quick examples of '-V': - -; one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -; purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -; the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 - - How many euros do I have ? - -$ hledger -f t.j bal -N euros - €100 assets:euros - - What are they worth at end of nov 3 ? - -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date -specified, defaults to today) - -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - -File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Value reporting - -23.8 -value: Flexible valuation -=============================== - -'-V' and '-X' are special cases of the more general '--value' option: - - --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. - COMM is an optional commodity symbol. - Shows amounts converted to: - - default valuation commodity (or COMM) using market prices at posting dates - - default valuation commodity (or COMM) using market prices at period end(s) - - default valuation commodity (or COMM) using current market prices - - default valuation commodity (or COMM) using market prices at some date - - The TYPE part selects cost or value and valuation date: - -'--value=then' - - Convert amounts to their value in the default valuation commodity, - using market prices on each posting's date. -'--value=end' - - Convert amounts to their value in the default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal's end date); or in multiperiod reports, - market prices on the last day of each subperiod. -'--value=now' - - Convert amounts to their value in the default valuation commodity - using current market prices (as of when report is generated). -'--value=YYYY-MM-DD' - - Convert amounts to their value in the default valuation commodity - using market prices on this date. - - To select a different valuation commodity, add the optional ',COMM' -part: a comma, then the target commodity's symbol. Eg: -*'--value=now,EUR'*. hledger will do its best to convert amounts to -this commodity, deducing market prices as described above. - - -File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting - -23.9 More valuation examples -============================ - -Here are some examples showing the effect of '--value', as seen with -'print': - -P 2000-01-01 A 1 B -P 2000-02-01 A 2 B -P 2000-03-01 A 3 B -P 2000-04-01 A 4 B - -2000-01-01 - (a) 1 A @ 5 B - -2000-02-01 - (a) 1 A @ 6 B - -2000-03-01 - (a) 1 A @ 7 B - - Show the cost of each posting: - -$ hledger -f- print --cost -2000-01-01 - (a) 5 B - -2000-02-01 - (a) 6 B - -2000-03-01 - (a) 7 B - - Show the value as of the last day of the report period (2000-02-29): - -$ hledger -f- print --value=end date:2000/01-2000/03 -2000-01-01 - (a) 2 B - -2000-02-01 - (a) 2 B - - With no report period specified, that shows the value as of the last -day of the journal (2000-03-01): - -$ hledger -f- print --value=end -2000-01-01 - (a) 3 B - -2000-02-01 - (a) 3 B - -2000-03-01 - (a) 3 B - - Show the current value (the 2000-04-01 price is still in effect -today): - -$ hledger -f- print --value=now -2000-01-01 - (a) 4 B - -2000-02-01 - (a) 4 B - -2000-03-01 - (a) 4 B - - Show the value on 2000/01/15: - -$ hledger -f- print --value=2000-01-15 -2000-01-01 - (a) 1 B - -2000-02-01 - (a) 1 B - -2000-03-01 - (a) 1 B - - -File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Value reporting - -23.10 Interaction of valuation and queries -========================================== - -When matching postings based on queries in the presence of valuation, -the following happens. - - 1. The query is separated into two parts: - 1. the currency ('cur:') or amount ('amt:'). - 2. all other parts. - - 2. The postings are matched to the currency and amount queries based - on pre-valued amounts. - 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on - post-valued amounts. - - See: 1625 - - -File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting - -23.11 Effect of valuation on reports -==================================== - -Here is a reference for how valuation is supposed to affect each part of -hledger's reports (and a glossary). (It's wide, you'll have to scroll -sideways.) It may be useful when troubleshooting. If you find -problems, please report them, ideally with a reproducible example. -Related: #329, #1083. - -Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', -type '--cost' '--value=now' ------------------------------------------------------------------------------- -*print* -posting cost value at value at posting value at value -amounts report end date report or at - or today journal DATE/today - end -balance unchanged unchanged unchanged unchanged unchanged -assertions/assignments -*register* -starting cost value at valued at day value at value -balance report or each historical report or at -(-H) journal posting was made journal DATE/today - end end -starting cost value at valued at day value at value -balance day before each historical day before at -(-H) report or posting was made report or DATE/today -with journal journal -report start start -interval -posting cost value at value at posting value at value -amounts report or date report or at - journal journal DATE/today - end end -summary summarised value at sum of postings value at value -posting cost period in interval, period at -amounts ends valued at ends DATE/today -with interval start -report -interval -running sum/average sum/average sum/average of sum/average sum/average -total/averageof of displayed values of of - displayed displayed displayed displayed - values values values values -*balance -(bs, -bse, cf, -is)* -balance sums of value at value at posting value at value -changes costs report end date report or at - or today journal DATE/today - of sums of end of of - postings sums of sums - postings of - postings -budget like like like balance like like -amounts balance balance changes balances balance -(-budget) changes changes changes -grand sum of sum of sum of displayed sum of sum of -total displayed displayed valued displayed displayed - values values values values -*balance -(bs, -bse, cf, -is) with -report -interval* -starting sums of value at sums of values value at sums -balances costs of report of postings report of -(-H) postings start of before report start of postings - before sums of start at sums of before - report all respective all report - start postings posting dates postings start - before before - report report - start start -balance sums of same as sums of values balance value -changes costs of -value=end of postings in change in at -(bal, postings period at each DATE/today -is, bs in period respective period, of --change, posting dates valued at sums -cf period of --change) ends postings -end sums of same as sums of values period end value -balances costs of -value=end of postings from balances, at -(bal -H, postings before period valued at DATE/today -is -H, from start to period period of -bs, cf) before end at ends sums - report respective of - start to posting dates postings - period end -budget like like like balance like like -amounts balance balance changes/end balances balance -(-budget) changes/end changes/end balances changes/end - balances balances balances -row sums, sums, sums, averages sums, sums, -totals, averages averages of displayed averages averages -row of of values of of -averages displayed displayed displayed displayed -(-T, -A) values values values values -column sums of sums of sums of sums of sums -totals displayed displayed displayed values displayed of - values values values displayed - values -grand sum, sum, sum, average of sum, sum, -total, average of average of column totals average of average -grand column column column of -average totals totals totals column - totals - - '--cumulative' is omitted to save space, it works like '-H' but with -a zero starting balance. - - *Glossary:* - -_cost_ - - calculated using price(s) recorded in the transaction(s). -_value_ - - market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. -_report start_ - - the first day of the report period specified with -b or -p or - date:, otherwise today. -_report or journal start_ - - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. -_report end_ - - the last day of the report period specified with -e or -p or date:, - otherwise today. -_report or journal end_ - - the last day of the report period specified with -e or -p or date:, - otherwise the latest transaction date in the journal, otherwise - today. -_report interval_ - - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report's multi-period mode (whether showing one or many - subperiods). - - -File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Value reporting, Up: Top - -24 PART 4: COMMANDS -******************* - -* Menu: - -* Commands overview:: -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* demo:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* register:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: - - -File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS - -24.1 Commands overview -====================== - -Here are the built-in commands: - -* Menu: - -* DATA ENTRY:: -* DATA CREATION:: -* DATA MANAGEMENT:: -* REPORTS FINANCIAL:: -* REPORTS VERSATILE:: -* REPORTS BASIC:: -* HELP:: -* ADD-ONS:: - - -File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview - -24.1.1 DATA ENTRY ------------------ - -These data entry commands are the only ones which can modify your -journal file. - - * add - add transactions using terminal prompts - * import - add new transactions from other files, eg CSV files - - -File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview - -24.1.2 DATA CREATION --------------------- - - * close - generate balance-zeroing/restoring transactions - * rewrite - generate auto postings, like print -auto - - -File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview - -24.1.3 DATA MANAGEMENT ----------------------- - - * check - check for various kinds of error in the data - * diff - compare account transactions in two journal files - - -File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview - -24.1.4 REPORTS, FINANCIAL -------------------------- - - * aregister (areg) - show transactions in a particular account - * balancesheet (bs) - show assets, liabilities and net worth - * balancesheetequity (bse) - show assets, liabilities and equity - * cashflow (cf) - show changes in liquid assets - * incomestatement (is) - show revenues and expenses - - -File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview - -24.1.5 REPORTS, VERSATILE -------------------------- - - * balance (bal) - show balance changes, end balances, budgets, - gains.. - * print - show transactions or export journal data - * register (reg) - show postings in one or more accounts & running - total - * roi - show return on investments - - -File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview - -24.1.6 REPORTS, BASIC ---------------------- - - * accounts - show account names - * activity - show bar charts of posting counts per period - * codes - show transaction codes - * commodities - show commodity/currency symbols - * descriptions - show transaction descriptions - * files - show input file paths - * notes - show note parts of transaction descriptions - * payees - show payee parts of transaction descriptions - * prices - show market prices - * stats - show journal statistics - * tags - show tag names - * test - run self tests - - -File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview - -24.1.7 HELP ------------ - - * help - show the hledger manual with info/man/pager - * demo - show small hledger demos in the terminal - - -File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview - -24.1.8 ADD-ONS --------------- - -And here are some typical add-on commands. Some of these are installed -by the hledger-install script. If installed, they will appear in -hledger's commands list: - - * ui - run hledger's terminal UI - * web - run hledger's web UI - * iadd - add transactions using a TUI (currently hard to build) - * interest - generate interest transactions - * stockquotes - download market prices from AlphaVantage - * Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, - pijul, plot, and more.. - - Next, each command is described in detail, in alphabetical order. - - -File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS - -24.2 accounts -============= - -Show account names. - - This command lists account names. By default it shows all known -accounts, either used in transactions or declared with account -directives. - - With query arguments, only matched account names and account names -referenced by matched postings are shown. - - Or it can show just the used accounts ('--used'/'-u'), the declared -accounts ('--declared'/'-d'), the accounts declared but not used -('--unused'), the accounts used but not declared ('--undeclared'), or -the first account matched by an account name pattern, if any ('--find'). - - It shows a flat list by default. With '--tree', it uses indentation -to show the account hierarchy. In flat mode you can add '--drop N' to -omit the first few account name components. Account names can be -depth-clipped with 'depth:N' or '--depth N' or '-N'. - - With '--types', it also shows each account's type, if it's known. -(See Declaring accounts > Account types.) - - With '--positions', it also shows the file and line number of each -account's declaration, if any, and the account's overall declaration -order; these may be useful when troubleshooting account display order. - - With '--directives', it adds the 'account' keyword, showing valid -account directives which can be pasted into a journal file. This is -useful together with '--undeclared' when updating your account -declarations to satisfy 'hledger check accounts'. - - The '--find' flag can be used to look up a single account name, in -the same way that the 'aregister' command does. It returns the -alphanumerically-first matched account name, or if none can be found, it -fails with a non-zero exit code. - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - -$ hledger accounts --undeclared --directives >> $LEDGER_FILE -$ hledger check accounts - - -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS - -24.3 activity -============= - -Show an ascii barchart of posting counts per interval. - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - - Examples: - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS - -24.4 add -======== - -Prompt for transactions and add them to the journal. Any arguments will -be used as default inputs for the first N prompts. - - Many hledger users edit their journals directly with a text editor, -or generate them from CSV. For more interactive data entry, there is the -'add' command, which prompts interactively on the console for new -transactions, and appends them to the main journal file (which should be -in journal format). Existing transactions are not changed. This is one -of the few hledger commands that writes to the journal file (see also -'import'). - - To use it, just run 'hledger add' and follow the prompts. You can -add as many transactions as you like; when you are finished, enter '.' -or press control-d or control-c to exit. - - Features: - - * add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as - a template. - * You can also set the initial defaults with command line arguments. - * Readline-style edit keys can be used during data entry. - * The tab key will auto-complete whenever possible - accounts, - payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If - the input area is empty, it will insert the default value. - * If the journal defines a default commodity, it will be added to any - bare numbers entered. - * A parenthesised transaction code may be entered following a date. - * Comments and tags may be entered following a description or amount. - * If you make a mistake, enter '<' at any prompt to go one step - backward. - * Input prompts are displayed in a different colour when the terminal - supports it. - - Example (see https://hledger.org/add.html for a detailed tutorial): - -$ hledger add -Adding transactions to journal file /src/hledger/examples/sample.journal -Any command line arguments will be used as defaults. -Use tab key to complete, readline keys to edit, enter to accept defaults. -An optional (CODE) may follow transaction dates. -An optional ; COMMENT may follow descriptions or amounts. -If you make a mistake, enter < at any prompt to go one step backward. -To end a transaction, enter . when prompted. -To quit, enter . at a date prompt or press control-d or control-c. -Date [2015/05/22]: -Description: supermarket -Account 1: expenses:food -Amount 1: $10 -Account 2: assets:checking -Amount 2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): . -2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - -Save this transaction to the journal ? [y]: -Saved. -Starting the next transaction (. or ctrl-D/ctrl-C to quit) -Date [2015/05/22]: $ - - On Microsoft Windows, the add command makes sure that no part of the -file path ends with a period, as that would cause problems (#1056). - - -File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS - -24.5 aregister -============== - -(areg) - - Show the transactions and running historical balance of a single -account, with each transaction displayed as one line. - - 'aregister' shows the overall transactions affecting a particular -account (and any subaccounts). Each report line represents one -transaction in this account. Transactions before the report start date -are always included in the running balance ('--historical' mode is -always on). - - This is a more "real world", bank-like view than the 'register' -command (which shows individual postings, possibly from multiple -accounts, not necessarily in historical mode). As a quick rule of -thumb: - use 'aregister' for reviewing and reconciling real-world -asset/liability accounts - use 'register' for reviewing detailed -revenues/expenses. - - 'aregister' requires one argument: the account to report on. You can -write either the full account name, or a case-insensitive regular -expression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can -be surprising; eg if you have 'assets:per:checking 1' and -'assets:biz:checking 2' accounts, 'hledger areg checking' would select -'assets:biz:checking 2'. It's just a convenience to save typing, so if -in doubt, write the full account name, or a distinctive substring that -matches uniquely. - - Transactions involving subaccounts of this account will also be -shown. 'aregister' ignores depth limits, so its final total will always -match a balance report with similar arguments. - - Any additional arguments form a query which will filter the -transactions shown. Note some queries will disturb the running balance, -causing it to be different from the account's real-world running -balance. - - An example: this shows the transactions and historical running -balance during july, in the first account whose name contains -"checking": - -$ hledger areg checking date:jul - - Each 'aregister' line item shows: - - * the transaction's date (or the relevant posting's date if - different, see below) - * the names of all the other account(s) involved in this transaction - (probably abbreviated) - * the total change to this account's balance from this transaction - * the account's historical running balance after this transaction. - - Transactions making a net change of zero are not shown by default; -add the '-E/--empty' flag to show them. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -'--align-all' flag. - - This command also supports the output destination and output format -options. The output formats supported are 'txt', 'csv', 'tsv', and -'json'. - -* Menu: - -* aregister and posting dates:: - - -File: hledger.info, Node: aregister and posting dates, Up: aregister - -24.5.1 aregister and posting dates ----------------------------------- - -aregister always shows one line (and date and amount) per transaction. -But sometimes transactions have postings with different dates. Also, -not all of a transaction's postings may be within the report period. To -resolve this, aregister shows the earliest of the transaction's date and -posting dates that is in-period, and the sum of the in-period postings. -In other words it will show a combined line item with just the earliest -date, and the running balance will (temporarily, until the transaction's -last posting) be inaccurate. Use 'register -H' if you need to see the -individual postings. - - There is also a '--txn-dates' flag, which filters strictly by -transaction date, ignoring posting dates. This too can cause an -inaccurate running balance. - - -File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS - -24.6 balance -============ - -(bal) - - Show accounts and their balances. - - 'balance' is one of hledger's oldest and most versatile commands, for -listing account balances, balance changes, values, value changes and -more, during one time period or many. Generally it shows a table, with -rows representing accounts, and columns representing periods. - - Note there are some higher-level variants of the 'balance' command -with convenient defaults, which can be simpler to use: 'balancesheet', -'balancesheetequity', 'cashflow' and 'incomestatement'. When you need -more control, then use 'balance'. - -* Menu: - -* balance features:: -* Simple balance report:: -* Balance report line format:: -* Filtered balance report:: -* List or tree mode:: -* Depth limiting:: -* Dropping top-level accounts:: -* Showing declared accounts:: -* Sorting by amount:: -* Percentages:: -* Multi-period balance report:: -* Balance change end balance:: -* Balance report types:: -* Budget report:: -* Balance report layout:: -* Useful balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -24.6.1 balance features ------------------------ - -Here's a quick overview of the 'balance' command's features, followed by -more detailed descriptions and examples. Many of these work with the -higher-level commands as well. - - 'balance' can show.. - - * accounts as a list ('-l') or a tree ('-t') - * optionally depth-limited ('-[1-9]') - * sorted by declaration order and name, or by amount - - ..and their.. - - * balance changes (the default) - * or actual and planned balance changes ('--budget') - * or value of balance changes ('-V') - * or change of balance values ('--valuechange') - * or unrealised capital gain/loss ('--gain') - * or postings count ('--count') - - ..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', 'tsv', 'json', and -(multi-period reports only:) 'html'. In 'txt' output in a -colour-supporting terminal, negative amounts are shown in red. - - The '--related'/'-r' flag shows the balance of the _other_ postings -in the transactions of the postings which would normally be shown. - - -File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance - -24.6.2 Simple balance report ----------------------------- - -With no arguments, 'balance' shows a list of all accounts and their -change of balance - ie, the sum of posting amounts, both inflows and -outflows - during the entire period of the journal. ("Simple" here -means just one column of numbers, covering a single period. You can -also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end -balance at the end of the journal period; more on this below. - - Accounts are sorted by declaration order if any, and then -alphabetically by account name. For instance (using -examples/sample.journal): - -$ hledger -f examples/sample.journal bal - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - Accounts with a zero balance (and no non-zero subaccounts, in tree -mode - see below) are hidden by default. Use '-E/--empty' to show them -(revealing 'assets:bank:checking' here): - -$ hledger -f examples/sample.journal bal -E - 0 assets:bank:checking - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - The total of the amounts displayed is shown as the last line, unless -'-N'/'--no-total' is used. - - -File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance - -24.6.3 Balance report line format ---------------------------------- - -For single-period balance reports displayed in the terminal (only), you -can use '--format FMT' to customise the format and content of each line. -Eg: - -$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 - - The FMT format string specifies the formatting applied to each -account/balance pair. It may contain any suitable text, with data -fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - - * MAX truncates at this width (optional) - - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance - -24.6.4 Filtered balance report ------------------------------- - -You can show fewer accounts, a different time period, totals from -cleared transactions only, etc. by using query arguments or options to -limit the postings being matched. Eg: - -$ hledger -f examples/sample.journal bal --cleared assets date:200806 - $-2 assets:cash --------------------- - $-2 - - -File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance - -24.6.5 List or tree mode ------------------------- - -By default, or with '-l/--flat', accounts are shown as a flat list with -their full names visible, as in the examples above. - - With '-t/--tree', the account hierarchy is shown, with subaccounts' -"leaf" names indented below their parent: - -$ hledger -f examples/sample.journal balance - $-1 assets - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts --------------------- - 0 - - Notes: - - * "Boring" accounts are combined with their subaccount for more - compact output, unless '--no-elide' is used. Boring accounts have - no balance of their own and just one subaccount (eg 'assets:bank' - and 'liabilities' above). - - * All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, - which requires explanation when sharing reports with - non-plaintextaccounting-users. A tree mode report's final total is - the sum of the top-level balances shown, not of all the balances - shown. - - * Each group of sibling accounts (ie, under a common parent) is - sorted separately. - - -File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance - -24.6.6 Depth limiting ---------------------- - -With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: -'-3') balance reports will show accounts only to the specified depth, -hiding the deeper subaccounts. This can be useful for getting an -overview without too much detail. - - Account balances at the depth limit always include the balances from -any deeper subaccounts (even in list mode). Eg, limiting to depth 1: - -$ hledger -f examples/sample.journal balance -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities --------------------- - 0 - - -File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance - -24.6.7 Dropping top-level accounts ----------------------------------- - -You can also hide one or more top-level account name parts, using -'--drop NUM'. This can be useful for hiding repetitive top-level -account names: - -$ hledger -f examples/sample.journal bal expenses --drop 1 - $1 food - $1 supplies --------------------- - $2 - - -File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance - -24.6.8 Showing declared accounts --------------------------------- - -With '--declared', accounts which have been declared with an account -directive will be included in the balance report, even if they have no -transactions. (Since they will have a zero balance, you will also need -'-E/--empty' to see them.) - - More precisely, _leaf_ declared accounts (with no subaccounts) will -be included, since those are usually the more useful in reports. - - The idea of this is to be able to see a useful "complete" balance -report, even when you don't have transactions in all of your declared -accounts yet. - - -File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance - -24.6.9 Sorting by amount ------------------------- - -With '-S/--sort-amount', accounts with the largest (most positive) -balances are shown first. Eg: 'hledger bal expenses -MAS' shows your -biggest averaged monthly expenses first. When more than one commodity -is present, they will be sorted by the alphabetically earliest commodity -first, and then by subsequent commodities (if an amount is missing a -commodity, it is treated as 0). - - Revenues and liability balances are typically negative, however, so -'-S' shows these in reverse order. To work around this, you can add -'--invert' to flip the signs. (Or, use one of the higher-level reports, -which flip the sign automatically. Eg: 'hledger incomestatement -MAS'). - - -File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance - -24.6.10 Percentages -------------------- - -With '-%/--percent', balance reports show each account's value expressed -as a percentage of the (column) total. - - Note it is not useful to calculate percentages if the amounts in a -column have mixed signs. In this case, make a separate report for each -sign, eg: - -$ hledger bal -% amt:`>0` -$ hledger bal -% amt:`<0` - - Similarly, if the amounts in a column have mixed commodities, convert -them to one commodity with '-B', '-V', '-X' or '--value', or make a -separate report for each commodity: - -$ hledger bal -% cur:\\$ -$ hledger bal -% cur:€ - - -File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance - -24.6.11 Multi-period balance report ------------------------------------ - -With a report interval (set by the '-D/--daily', '-W/--weekly', -'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag), -'balance' shows a tabular report, with columns representing successive -time periods (and a title): - -$ hledger -f examples/sample.journal bal --quarterly income expenses -E -Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 -===================++================================= - expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 --------------------++--------------------------------- - || $-1 $1 0 0 - - Notes: - - * The report's start/end dates will be expanded, if necessary, to - fully encompass the displayed subperiods (so that the first and - last subperiods have the same duration as the others). - * Leading and trailing periods (columns) containing all zeroes are - not shown, unless '-E/--empty' is used. - * Accounts (rows) containing all zeroes are not shown, unless - '-E/--empty' is used. - * Amounts with many commodities are shown in abbreviated form, unless - '--no-elide' is used. _(experimental)_ - * Average and/or total columns can be added with the '-A/--average' - and '-T/--row-total' flags. - * The '--transpose' flag can be used to exchange rows and columns. - * The '--pivot FIELD' option causes a different transaction field to - be used as "account name". See PIVOTING. - - Multi-period reports with many periods can be too wide for easy -viewing in the terminal. Here are some ways to handle that: - - * Hide the totals row with '-N/--no-total' - * Convert to a single currency with '-V' - * Maximize the terminal window - * Reduce the terminal's font size - * View with a pager like less, eg: 'hledger bal -D --color=yes | less - -RS' - * Output as CSV and use a CSV viewer like visidata ('hledger bal -D - -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or - a spreadsheet ('hledger bal -D -o a.csv && open a.csv') - * Output as HTML and view with a browser: 'hledger bal -D -o a.html - && open a.html' - - -File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance - -24.6.12 Balance change, end balance ------------------------------------ - -It's important to be clear on the meaning of the numbers shown in -balance reports. Here is some terminology we use: - - A *_balance change_* is the net amount added to, or removed from, an -account during some period. - - An *_end balance_* is the amount accumulated in an account as of some -date (and some time, but hledger doesn't store that; assume end of day -in your timezone). It is the sum of previous balance changes. - - We call it a *_historical end balance_* if it includes all balance -changes since the account was created. For a real world account, this -means it will match the "historical record", eg the balances reported in -your bank statements or bank web UI. (If they are correct!) - - In general, balance changes are what you want to see when reviewing -revenues and expenses, and historical end balances are what you want to -see when reviewing or reconciling asset, liability and equity accounts. - - 'balance' shows balance changes by default. To see accurate -historical end balances: - - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the - journal covers the account's full lifetime. - - 2. Include all of of the account's prior postings in the report, by - not specifying a report start date, or by using the - '-H/--historical' flag. ('-H' causes report start date to be - ignored when summing postings.) - - -File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance - -24.6.13 Balance report types ----------------------------- - -The balance command is quite flexible; here is the full detail on how to -control what it reports. If the following seems complicated, don't -worry - this is for advanced reporting, and it does take time and -experimentation to get familiar with all the report modes. - - There are three important option groups: - - 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] -...' - -* Menu: - -* Calculation type:: -* Accumulation type:: -* Valuation type:: -* Combining balance report types:: - - -File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types - -24.6.13.1 Calculation type -.......................... - -The basic calculation to perform for each table cell. It is one of: - - * '--sum' : sum the posting amounts (*default*) - * '--budget' : sum the amounts, but also show the budget goal amount - (for each account/period) - * '--valuechange' : show the change in period-end historical balance - values (caused by deposits, withdrawals, and/or market price - fluctuations) - * '--gain' : show the unrealised capital gain/loss, (the current - valued balance minus each amount's original cost) - * '--count' : show the count of postings - - -File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types - -24.6.13.2 Accumulation type -........................... - -How amounts should accumulate across report periods. Another way to say -it: which time period's postings should contribute to each cell's -calculation. It is one of: - - * '--change' : calculate with postings from column start to column - end, ie "just this column". Typically used to see - revenues/expenses. (*default for balance, incomestatement*) - - * '--cumulative' : calculate with postings from report start to - column end, ie "previous columns plus this column". Typically used - to show changes accumulated since the report's start date. Not - often used. - - * '--historical/-H' : calculate with postings from journal start to - column end, ie "all postings from before report start date until - this column's end". Typically used to see historical end balances - of assets/liabilities/equity. (*default for balancesheet, - balancesheetequity, cashflow*) - - -File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types - -24.6.13.3 Valuation type -........................ - -Which kind of value or cost conversion should be applied, if any, before -displaying the report. It is one of: - - * no valuation type : don't convert to cost or value (*default*) - * '--value=cost[,COMM]' : convert amounts to cost (then optionally to - some other commodity) - * '--value=then[,COMM]' : convert amounts to market value on - transaction dates - * '--value=end[,COMM]' : convert amounts to market value on period - end date(s) - (*default with '--valuechange', '--gain'*) - * '--value=now[,COMM]' : convert amounts to market value on today's - date - * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on - another date - - or one of the equivalent simpler flags: - - * '-B/--cost' : like -value=cost (though, note -cost and -value are - independent options which can both be used at once) - * '-V/--market' : like -value=end - * '-X COMM/--exchange COMM' : like -value=end,COMM - - See Cost reporting and Value reporting for more about these. - - -File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types - -24.6.13.4 Combining balance report types -........................................ - -Most combinations of these options should produce reasonable reports, -but if you find any that seem wrong or misleading, let us know. The -following restrictions are applied: - - * '--valuechange' implies '--value=end' - * '--valuechange' makes '--change' the default when used with the - 'balancesheet'/'balancesheetequity' commands - * '--cumulative' or '--historical' disables '--row-total/-T' - - For reference, here is what the combinations of accumulation and -valuation show: - -Valuation:>no valuation '--value= then' '--value= end' '--value= -Accumulation:v YYYY-MM-DD - /now' ------------------------------------------------------------------------------ -'--change'change in sum of period-end DATE-value - period posting-date value of of change in - market values change in period - in period period -'--cumulative'change from sum of period-end DATE-value - report start to posting-date value of of change - period end market values change from from report - from report report start start to - start to period to period end period end - end -'--historicalchange from sum of period-end DATE-value -/-H' journal start posting-date value of of change - to period end market values change from from journal - (historical end from journal journal start start to - balance) start to period to period end period end - end - - -File: hledger.info, Node: Budget report, Next: Balance report layout, Prev: Balance report types, Up: balance - -24.6.14 Budget report ---------------------- - -The '--budget' report type activates extra columns showing any budget -goals for each account and period. The budget goals are defined by -periodic transactions. This is useful for comparing planned and actual -income, expenses, time usage, etc. - - For example, you can take average monthly expenses in the common -expense categories to construct a minimal monthly budget: - -;; Budget -~ monthly - income $2000 - expenses:food $400 - expenses:bus $50 - expenses:movies $30 - assets:bank:checking - -;; Two months worth of expenses -2017-11-01 - income $1950 - expenses:food $396 - expenses:bus $49 - expenses:movies $30 - expenses:supplies $20 - assets:bank:checking - -2017-12-01 - income $2100 - expenses:food $412 - expenses:bus $53 - expenses:gifts $100 - assets:bank:checking - - You can now see a monthly budget report: - -$ hledger balance -M --budget -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - This is different from a normal balance report in several ways. -Currently: - - * Accounts with budget goals during the report period, and their - parents, are shown. - * Their subaccounts are not shown (regardless of the depth setting). - * Accounts without budget goals, if any, are aggregated and shown as - "". - * Amounts are always inclusive (subaccount-including), even in list - mode. - * After each actual amount, the corresponding goal amount and - percentage of goal reached are also shown, in square brackets. - - This means that the numbers displayed will not always add up! Eg -above, the 'expenses' actual amount includes the gifts and supplies -transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts -are not shown, as they have no budget amounts declared. - - This can be confusing. When you need to make things clearer, use the -'-E/--empty' flag, which will reveal all accounts including unbudgeted -ones, giving the full picture. Eg: - -$ hledger balance -M --budget --empty -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - expenses:supplies || $20 0 - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - You can roll over unspent budgets to next period with '--cumulative': - -$ hledger balance -M --budget --cumulative -Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec -======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] - expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] - expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] - income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] -----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - It's common to limit budgets/budget reports to just expenses - -hledger bal -M --budget expenses - - or just revenues and expenses (eg, using account types): - -hledger bal -M --budget type:rx - - It's also common to limit or convert them to a single currency -('cur:COMM' or '-X COMM [--infer-market-prices]'). If showing multiple -currencies, '--layout bare' or '--layout tall' can help. - - For more examples and notes, see Budgeting. - -* Menu: - -* Budget report start date:: -* Budgets and subaccounts:: -* Selecting budget goals:: -* Budget vs forecast:: - - -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report - -24.6.14.1 Budget report start date -.................................. - -This might be a bug, but for now: when making budget reports, it's a -good idea to explicitly set the report's start date to the first day of -a reporting period, because a periodic rule like '~ monthly' generates -its transactions on the 1st of each month, and if your journal has no -regular transactions on the 1st, the default report start date could -exclude that budget goal, which can be a little surprising. Eg here the -default report period is just the day of 2020-01-15: - -~ monthly in 2020 - (expenses:food) $500 - -2020-01-15 - expenses:food $400 - assets:checking - -$ hledger bal expenses --budget -Budget performance in 2020-01-15: - - || 2020-01-15 -==============++============ - || $400 ---------------++------------ - || $400 - - To avoid this, specify the budget report's period, or at least the -start date, with '-b'/'-e'/'-p'/'date:', to ensure it includes the -budget goal transactions (periodic transactions) that you want. Eg, -adding '-b 2020/1/1' to the above: - -$ hledger bal expenses --budget -b 2020/1/1 -Budget performance in 2020-01-01..2020-01-15: - - || 2020-01-01..2020-01-15 -===============++======================== - expenses:food || $400 [80% of $500] ----------------++------------------------ - || $400 [80% of $500] - - -File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report - -24.6.14.2 Budgets and subaccounts -................................. - -You can add budgets to any account in your account hierarchy. If you -have budgets on both parent account and some of its children, then -budget(s) of the child account(s) would be added to the budget of their -parent, much like account balances behave. - - In the most simple case this means that once you add a budget to any -account, all its parents would have budget as well. - - To illustrate this, consider the following budget: - -~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - - With this, monthly budget for electronics is defined to be $100 and -budget for personal expenses is an additional $1000, which implicitly -means that budget for both 'expenses:personal' and 'expenses' is $1100. - - Transactions in 'expenses:personal:electronics' will be counted both -towards its $100 budget and $1100 of 'expenses:personal' , and -transactions in any other subaccount of 'expenses:personal' would be -counted towards only towards the budget of 'expenses:personal'. - - For example, let's consider these transactions: - -~ monthly from 2019/01 - expenses:personal $1,000.00 - expenses:personal:electronics $100.00 - liabilities - -2019/01/01 Google home hub - expenses:personal:electronics $90.00 - liabilities $-90.00 - -2019/01/02 Phone screen protector - expenses:personal:electronics:upgrades $10.00 - liabilities - -2019/01/02 Weekly train ticket - expenses:personal:train tickets $153.00 - liabilities - -2019/01/03 Flowers - expenses:personal $30.00 - liabilities - - As you can see, we have transactions in -'expenses:personal:electronics:upgrades' and 'expenses:personal:train -tickets', and since both of these accounts are without explicitly -defined budget, these transactions would be counted towards budgets of -'expenses:personal:electronics' and 'expenses:personal' accordingly: - -$ hledger balance --budget -M -Budget performance in 2019/01: - - || Jan -===============================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] --------------------------------++------------------------------- - || 0 [ 0] - - And with '--empty', we can get a better picture of budget allocation -and consumption: - -$ hledger balance --budget -M --empty -Budget performance in 2019/01: - - || Jan -========================================++=============================== - expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] -----------------------------------------++------------------------------- - || 0 [ 0] - - -File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report - -24.6.14.3 Selecting budget goals -................................ - -The budget report evaluates periodic transaction rules to generate -special "goal transactions", which generate the goal amounts for each -account in each report subperiod. When troubleshooting, you can use -'print --forecast' to show these as forecasted transactions: - -$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated - - By default, the budget report uses all available periodic transaction -rules to generate goals. This includes rules with a different report -interval from your report. Eg if you have daily, weekly and monthly -periodic rules, all of these will contribute to the goals in a monthly -budget report. - - You can select a subset of periodic rules by providing an argument to -the '--budget' flag. '--budget=DESCPAT' will match all periodic rules -whose description contains DESCPAT, a case-insensitive substring (not a -regular expression or query). This means you can give your periodic -rules descriptions (remember that two spaces are needed), and then -select from multiple budgets defined in your journal. - - -File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report - -24.6.14.4 Budget vs forecast -............................ - -'hledger --forecast ...' and 'hledger balance --budget ...' are separate -features, though both of them use the periodic transaction rules defined -in the journal, and both of them generate temporary transactions for -reporting purposes ("forecast transactions" and "budget goal -transactions", respectively). You can use both features at the same -time if you want. Here are some differences between them, as of hledger -1.29: - - CLI: - - * -forecast is a general hledger option, usable with any command - * -budget is a 'balance' command option, usable only with that - command. - - Visibility of generated transactions: - - * forecast transactions are visible in any report, like ordinary - transactions - * budget goal transactions are invisible except for the goal amounts - they produce in -budget reports. - - Periodic transaction rules: - - * -forecast uses all available periodic transaction rules - * -budget uses all periodic rules ('--budget') or a selected subset - ('--budget=DESCPAT') - - Period of generated transactions: - - * -forecast generates forecast transactions - * from after the last regular transaction to the end of the - report period ('--forecast') - * or, during a specified period ('--forecast=PERIODEXPR') - * possibly further restricted by a period specified in the - periodic transaction rule - * and always restricted within the bounds of the report period - - * -budget generates budget goal transactions - * throughout the report period - * possibly restricted by a period specified in the periodic - transaction rule. - - -File: hledger.info, Node: Balance report layout, Next: Useful balance reports, Prev: Budget report, Up: balance - -24.6.15 Balance report layout ------------------------------ - -The '--layout' option affects how balance reports show multi-commodity -amounts and commodity symbols, which can improve readability. It can -also normalise the data for easy consumption by other programs. It has -four possible values: - - * '--layout=wide[,WIDTH]': commodities are shown on a single line, - optionally elided to WIDTH - * '--layout=tall': each commodity is shown on a separate line - * '--layout=bare': commodity symbols are in their own column, amounts - are bare numbers - * '--layout=tidy': data is normalised to easily-consumed "tidy" form, - with one row per data value - - Here are the '--layout' modes supported by each output format; note -only CSV output supports all of them: - -- txt csv html json sql ---------------------------------------- -wide Y Y Y -tall Y Y Y -bare Y Y Y -tidy Y - - Examples: - - * Wide layout. With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - * Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - * Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - * Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - * Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - * Note: bare layout will sometimes display an extra row for the - no-symbol commodity, because of zero amounts (hledger treats zeroes - as commodity-less, usually). This can break 'hledger-bar' - confusingly (workaround: add a 'cur:' query to exclude the - no-symbol row). - - * Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here's how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - -File: hledger.info, Node: Useful balance reports, Prev: Balance report layout, Up: balance - -24.6.16 Useful balance reports ------------------------------- - -Some frequently used 'balance' options/reports are: - - * 'bal -M revenues expenses' - Show revenues/expenses in each month. Also available as the - 'incomestatement' command. - - * 'bal -M -H assets liabilities' - Show historical asset/liability balances at each month end. Also - available as the 'balancesheet' command. - - * 'bal -M -H assets liabilities equity' - Show historical asset/liability/equity balances at each month end. - Also available as the 'balancesheetequity' command. - - * 'bal -M assets not:receivable' - Show changes to liquid assets in each month. Also available as the - 'cashflow' command. - - Also: - - * 'bal -M expenses -2 -SA' - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - * 'bal -M --budget expenses' - Show monthly expenses and budget goals. - - * 'bal -M --valuechange investments' - Show monthly change in market value of investment assets. - - * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert]' - Show top gainers [or losers] last week - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS - -24.7 balancesheet -================= - -(bs) - - This command displays a balance sheet, showing historical ending -balances of asset and liability accounts. (To see equity as well, use -the balancesheetequity command.) Amounts are shown with normal positive -sign, as in conventional financial statements. - - This report shows accounts declared with the 'Asset', 'Cash' or -'Liability' type (see account types). Or if no such accounts are -declared, it shows top-level accounts named 'asset' or 'liability' (case -insensitive, plurals allowed) and their subaccounts. - - Example: - -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance -H assets liabilities', but with -smarter account detection, and liabilities displayed with their sign -flipped. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS - -24.8 balancesheetequity -======================= - -(bse) - - This command displays a balance sheet, showing historical ending -balances of asset, liability and equity accounts. Amounts are shown -with normal positive sign, as in conventional financial statements. - - This report shows accounts declared with the 'Asset', 'Cash', -'Liability' or 'Equity' type (see account types). Or if no such -accounts are declared, it shows top-level accounts named 'asset', -'liability' or 'equity' (case insensitive, plurals allowed) and their -subaccounts. - - Example: - -$ hledger balancesheetequity -Balance Sheet With Equity - -Assets: - $-2 assets - $1 bank:saving - $-3 cash --------------------- - $-2 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Equity: - $1 equity:owner --------------------- - $1 - -Total: --------------------- - 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance -H assets liabilities equity', but -with smarter account detection, and liabilities/equity displayed with -their sign flipped. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS - -24.9 cashflow -============= - -(cf) - - This command displays a cashflow statement, showing the inflows and -outflows affecting "cash" (ie, liquid, easily convertible) assets. -Amounts are shown with normal positive sign, as in conventional -financial statements. - - This report shows accounts declared with the 'Cash' type (see account -types). Or if no such accounts are declared, it shows accounts - - * under a top-level account named 'asset' (case insensitive, plural - allowed) - * whose name contains some variation of 'cash', 'bank', 'checking' or - 'saving'. - - More precisely: all accounts matching this case insensitive regular -expression: - - '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)' - - and their subaccounts. - - An example cashflow report: - -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance assets not:fixed not:investment -not:receivable', but with smarter account detection. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS - -24.10 check -=========== - -Check for various kinds of errors in your data. - - hledger provides a number of built-in error checks to help prevent -problems in your data. Some of these are run automatically; or, you can -use this 'check' command to run them on demand, with no output and a -zero exit code if all is well. Specify their names (or a prefix) as -argument(s). - - Some examples: - -hledger check # basic checks -hledger check -s # basic + strict checks -hledger check ordereddates payees # basic + two other checks - - If you are an Emacs user, you can also configure flycheck-hledger to -run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available: - -* Menu: - -* Default checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: -* More about specific checks:: - - -File: hledger.info, Node: Default checks, Next: Strict checks, Up: check - -24.10.1 Default checks ----------------------- - -These checks are run automatically by (almost) all hledger commands: - - * *parseable* - data files are in a supported format, with no syntax - errors and no invalid include directives. - - * *autobalanced* - all transactions are balanced, after converting to - cost. Missing amounts and missing costs are inferred automatically - where possible. - - * *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: Default checks, Up: check - -24.10.2 Strict checks ---------------------- - -These additional checks are run when the '-s'/'--strict' (strict mode) -flag is used. Or, they can be run by giving their names as arguments to -'check': - - * *balanced* - all transactions are balanced after converting to - cost, without inferring missing costs. If conversion costs are - required, they must be explicit. - - * *accounts* - all account names used by transactions have been - declared - - * *commodities* - all commodity symbols used have been declared - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -24.10.3 Other checks --------------------- - -These checks can be run only by giving their names as arguments to -'check'. They are more specialised and not desirable for everyone: - - * *ordereddates* - transactions are ordered by date within each file - - * *payees* - all payees used by transactions have been declared - - * *recentassertions* - all accounts with balance assertions have a - balance assertion within 7 days of their latest posting - - * *tags* - all tags used by transactions have been declared - - * *uniqueleafnames* - all account leaf names are unique - - -File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check - -24.10.4 Custom checks ---------------------- - -A few more checks are are available as separate add-on commands, in -https://github.com/simonmichael/hledger/tree/master/bin: - - * *hledger-check-tagfiles* - all tag values containing / (a forward - slash) exist as file paths - - * *hledger-check-fancyassertions* - more complex balance assertions - are passing - - You could make similar scripts to perform your own custom checks. -See: Cookbook -> Scripting. - - -File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check - -24.10.5 More about specific checks ----------------------------------- - -'hledger check recentassertions' will complain if any balance-asserted -account has postings more than 7 days after its latest balance -assertion. This aims to prevent the situation where you are regularly -updating your journal, but forgetting to check your balances against the -real world, then one day must dig back through months of data to find an -error. It assumes that adding a balance assertion requires/reminds you -to check the real-world balance. (That may not be true if you -auto-generate balance assertions from bank data; in that case, I -recommend to import transactions uncleared, and when you manually review -and clear them, also check the latest assertion against the real-world -balance.) - - -File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS - -24.11 close -=========== - -(equity) - - Generate transactions which transfer account balances to and/or from -another account (typically equity). This can be useful for migrating -balances to a new journal file, or for merging earnings into equity at -end of accounting period. - - By default, it prints a transaction that zeroes out ALE accounts -(asset, liability, equity accounts; this requires account types to be -configured); or if ACCTQUERY is provided, the accounts matched by that. - - _(experimental)_ - - This command has four main modes, corresponding to the most common -use cases: - - 1. With '--close' (default), it prints a "closing balances" - transaction that zeroes out ALE (asset, liability, equity) accounts - by default (this requires account types to be inferred or - declared); or, the accounts matched by the provided ACCTQUERY - arguments. - - 2. With '--open', it prints an opposite "opening balances" transaction - that restores those balances from zero. This is similar to - Ledger's equity command. - - 3. With '--migrate', it prints both the closing and opening - transactions. This is the preferred way to migrate balances to a - new file: run 'hledger close --migrate', add the closing - transaction at the end of the old file, and add the opening - transaction at the start of the new file. The matching - closing/opening transactions cancel each other out, preserving - correct balances during multi-file reporting. - - 4. With '--retain', it prints a "retain earnings" transaction that - transfers RX (revenue and expense) balances to 'equity:retained - earnings'. Businesses traditionally do this at the end of each - accounting period; it is less necessary with computer-based - accounting, but it could still be useful if you want to see the - accounting equation (A=L+E) satisfied. - - In all modes, the defaults can be overridden: - - * the transaction descriptions can be changed with - '--close-desc=DESC' and '--open-desc=DESC' - * the account to transfer to/from can be changed with - '--close-acct=ACCT' and '--open-acct=ACCT' - * the accounts to be closed/opened can be changed with 'ACCTQUERY' - (account query arguments). - * the closing/opening dates can be changed with '-e DATE' (a report - end date) - - By default just one destination/source posting will be used, with its -amount left implicit. With '--x/--explicit', the amount will be shown -explicitly, and if it involves multiple commodities, a separate posting -will be generated for each of them (similar to 'print -x'). - - With '--show-costs', any amount costs are shown, with separate -postings for each cost. This is currently the best way to view -investment lots. If you have many currency conversion or investment -transactions, it can generate very large journal entries. - - With '--interleaved', each individual transfer is shown with source -and destination postings next to each other. This could be useful for -troubleshooting. - - The default closing date is yesterday, or the journal's end date, -whichever is later. You can change this by specifying a report end date -with '-e'. The last day of the report period will be the closing date, -eg '-e 2024' means "close on 2023-12-31". The opening date is always -the day after the closing date. - -* Menu: - -* close and balance assertions:: -* Example retain earnings:: -* Example migrate balances to a new file:: -* Example excluding closing/opening transactions:: - - -File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Up: close - -24.11.1 close and balance assertions ------------------------------------- - -Balance assertions will be generated, verifying that the accounts have -been reset to zero (and then restored to their previous balances, if -there is an opening transaction). - - These provide useful error checking, but you can ignore them -temporarily with '-I', or remove them if you prefer. - - You probably should avoid filtering transactions by status or -realness ('-C', '-R', 'status:'), or generating postings ('--auto'), -with this command, since the balance assertions would depend on these. - - Note custom posting dates spanning the file boundary will disrupt the -balance assertions: - -2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve that you can transfer the money to and from a temporary -account, in effect splitting the multi-day transaction into two -single-day transactions: - -; in 2022.journal: -2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - -; in 2023.journal: -2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - -File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close - -24.11.2 Example: retain earnings --------------------------------- - -Record 2022's revenues/expenses as retained earnings on 2022-12-31, -appending the generated transaction to the journal: - -$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - Note 2022's income statement will now show only zeroes, because -revenues and expenses have been moved entirely to equity. To see them -again, you could exclude the retain transaction: - -$ hledger -f 2022.journal is not:desc:'retain earnings' - - -File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close - -24.11.3 Example: migrate balances to a new file ------------------------------------------------ - -Close assets/liabilities/equity on 2022-12-31 and re-open them on -2023-01-01: - -$ hledger close --migrate -f 2022.journal -p 2022 -# copy/paste the closing transaction to the end of 2022.journal -# copy/paste the opening transaction to the start of 2023.journal - - Now 2022's balance sheet will show only zeroes, indicating a balanced -accounting equation. (Unless you are using @/@@ notation - in that -case, try adding -infer-equity.) To see the end-of-year balances again, -you could exclude the closing transaction: - -$ hledger -f 2022.journal bs not:desc:'closing balances' - - -File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close - -24.11.4 Example: excluding closing/opening transactions -------------------------------------------------------- - -When combining many files for multi-year reports, the closing/opening -transactions cause some noise in transaction-oriented reports like -'print' and 'register'. You can exclude them as shown above, but -'not:desc:...' is not ideal as it depends on consistent descriptions; -also you will want to avoid excluding the very first opening -transaction, which could be awkward. Here is one alternative, using -tags: - - Add 'clopen:' tags to all opening/closing balances transactions -except the first, like this: - -; 2021.journal -2021-06-01 first opening balances -... -2021-12-31 closing balances ; clopen:2022 -... - -; 2022.journal -2022-01-01 opening balances ; clopen:2022 -... -2022-12-31 closing balances ; clopen:2023 -... - -; 2023.journal -2023-01-01 opening balances ; clopen:2023 -... - - Now, assuming a combined journal like: - -; all.journal -include 2021.journal -include 2022.journal -include 2023.journal - - The 'clopen:' tag can exclude all but the first opening transaction. -To show a clean multi-year checking register: - -$ hledger -f all.journal areg checking not:tag:clopen - - And the year values allow more precision. To show 2022's year-end -balance sheet: - -$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 - - -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS - -24.12 codes -=========== - -List the codes seen in transactions, in the order parsed. - - This command prints the value of each transaction's code field, in -the order transactions were parsed. The transaction code is an optional -value written in parentheses between the date and description, often -used to store a cheque number, order number or similar. - - Transactions aren't required to have a code, and missing or empty -codes will not be shown by default. With the '-E'/'--empty' flag, they -will be printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - -2022/1/1 (123) Supermarket - Food $5.00 - Checking - -2022/1/2 (124) Post Office - Postage $8.32 - Checking - -2022/1/3 Supermarket - Food $11.23 - Checking - -2022/1/4 (126) Post Office - Postage $3.21 - Checking - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - -126 - - -File: hledger.info, Node: commodities, Next: demo, Prev: codes, Up: PART 4 COMMANDS - -24.13 commodities -================= - -List all commodity/currency symbols used or declared in the journal. - - -File: hledger.info, Node: demo, Next: descriptions, Prev: commodities, Up: PART 4 COMMANDS - -24.14 demo -========== - -Play demos of hledger usage in the terminal, if asciinema is installed. - - Run this command with no argument to list the demos. To play a demo, -write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/-speed SPEED option to set your preferred playback speed, -eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. -The default speed is 2x. - - Other asciinema options can be added following a double dash, eg '-- --i.1' to limit pauses or '-- -h' to list asciinema's other options. - - During playback, several keys are available: SPACE to pause/unpause, -. to step forward (while paused), CTRL-c quit. - - Examples: - -$ hledger demo # list available demos -$ hledger demo 1 # play the first demo at default speed (2x) -$ hledger demo install -s4 # play the "install" demo at 4x speed - - -File: hledger.info, Node: descriptions, Next: diff, Prev: demo, Up: PART 4 COMMANDS - -24.15 descriptions -================== - -List the unique descriptions that appear in transactions. - - This command lists the unique descriptions that appear in -transactions, in alphabetic order. You can add a query to select a -subset of transactions. - - Example: - -$ hledger descriptions -Store Name -Gas Station | Petrol -Person A - - -File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS - -24.16 diff -========== - -Compares a particular account's transactions in two input files. It -shows any transactions to this account which are in one file but not in -the other. - - More precisely, for each posting affecting this account in either -file, it looks for a corresponding posting in the other file which posts -the same amount to the same account (ignoring date, description, etc.) -Since postings not transactions are compared, this also works when -multiple bank transactions have been combined into a single journal -entry. - - This is useful eg if you have downloaded an account's transactions -from your bank (eg as CSV data). When hledger and your bank disagree -about the account balance, you can compare the bank data with your -journal to find out the cause. - - Examples: - -$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only: - -2014/01/01 Opening Balances - assets:bank:giro EUR ... - ... - equity:opening balances EUR -... - -These transactions are in the second file only: - - -File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS - -24.17 files -=========== - -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - - -File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS - -24.18 help -========== - -Show the hledger user manual in the terminal, with 'info', 'man', or a -pager. With a TOPIC argument, open it at that topic if possible. TOPIC -can be any heading in the manual, or a heading prefix, case insensitive. -Eg: 'commands', 'print', 'forecast', 'journal', 'amount', '"auto -postings"'. - - This command shows the hledger manual built in to your hledger -version. It can be useful when offline, or when you prefer the terminal -to a web browser, or when the appropriate hledger manual or viewing -tools are not installed on your system. - - By default it chooses the best viewer found in $PATH, trying (in this -order): 'info', 'man', '$PAGER', 'less', 'more'. You can force the use -of info, man, or a pager with the '-i', '-m', or '-p' flags, If no -viewer can be found, or the command is run non-interactively, it just -prints the manual to stdout. - - If using 'info', note that version 6 or greater is needed for TOPIC -lookup. If you are on mac you will likely have info 4.8, and should -consider installing a newer version, eg with 'brew install texinfo' -(#1770). - - Examples - -$ hledger help --help # show how the help command works -$ hledger help # show the hledger manual with info, man or $PAGER -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help -m journal # show it with man, even if info is installed - - -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS - -24.19 import -============ - -Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. - - This command may append new transactions to the main journal file -(which should be in journal format). Existing transactions are not -changed. This is one of the few hledger commands that writes to the -journal file (see also 'add'). - - Unlike other hledger commands, with 'import' the journal file is an -output file, and will be modified, though only by appending (existing -data will not be changed). The input files are specified as arguments, -so to import one or more CSV files to your main journal, you will run -'hledger import bank.csv' or perhaps 'hledger import *.csv'. - - Note you can import from any file format, though CSV files are the -most common import source, and these docs focus on that case. - -* Menu: - -* Deduplication:: -* Import testing:: -* Importing balance assignments:: -* Commodity display styles:: - - -File: hledger.info, Node: Deduplication, Next: Import testing, Up: import - -24.19.1 Deduplication ---------------------- - -'import' does _time-based deduplication_, to detect only the new -transactions since the last successful import. (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 downloaded data, which may overlap with -previous downloads. Eg if every week (or every day) you download a -bank's last three months of CSV data, you can safely run 'hledger import -thebank.csv' each time and only new transactions will be imported. - - 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.FILE" file in FILE's directory (after a -succesful import). - - 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. - - Related: CSV > Working with CSV > Deduplicating, importing. - - -File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import - -24.19.2 Import testing ----------------------- - -With '--dry-run', the transactions that will be imported are printed to -the terminal, without updating your journal or state files. The output -is valid journal format, like the print command, so you can re-parse it. -Eg, to see any importable transactions which CSV rules have not -categorised: - -$ hledger import --dry bank.csv | hledger -f- -I print unknown - - or (live updating): - -$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' - - Note: when importing from multiple files at once, it's currently -possible for some .latest files to be updated successfully, while the -actual import fails because of a problem in one of the files, leaving -them out of sync (and causing some transactions to be missed). To -prevent this, do a -dry-run first and fix any problems before the real -import. - - -File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import - -24.19.3 Importing balance assignments -------------------------------------- - -Entries added by import will have their posting amounts made explicit -(like 'hledger print -x'). This means that any balance assignments in -imported files must be evaluated; but, imported files don't get to see -the main file's account balances. As a result, importing entries with -balance assignments (eg from an institution that provides only balances -and not posting amounts) will probably generate incorrect posting -amounts. To avoid this problem, use print instead of import: - -$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - - (If you think import should leave amounts implicit like print does, -please test it and send a pull request.) - - -File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import - -24.19.4 Commodity display styles --------------------------------- - -Imported amounts will be formatted according to the canonical commodity -styles (declared or inferred) in the main journal file. - - -File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS - -24.20 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', 'tsv', 'html', -and (experimental) 'json'. - - -File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS - -24.21 notes -=========== - -List the unique notes that appear in transactions. - - This command lists the unique notes that appear in transactions, in -alphabetic order. You can add a query to select a subset of -transactions. The note is the part of the transaction description after -a | character (or if there is no |, the whole description). - - Example: - -$ hledger notes -Petrol -Snacks - - -File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS - -24.22 payees -============ - -List the unique payee/payer names that appear in transactions. - - This command lists unique payee/payer names which have been declared -with payee directives (-declared), used in transaction descriptions -(-used), or both (the default). - - The payee/payer is the part of the transaction description before a | -character (or if there is no |, the whole description). - - You can add query arguments to select a subset of transactions. This -implies -used. - - Example: - -$ hledger payees -Store Name -Gas Station -Person A - - -File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS - -24.23 prices -============ - -Print the market prices declared with P directives. With --infer-market-prices, also show any additional prices inferred from -costs. With -show-reverse, also show additional prices inferred by -reversing known prices. - - Price amounts are always displayed with their full precision, except -for reverse prices which are limited to 8 decimal digits. - - Prices can be filtered by a date:, cur: or amt: query. - - Generally if you run this command with -infer-market-prices --show-reverse, it will show the same prices used internally to calculate -value reports. But if in doubt, you can inspect those directly by -running the value report with -debug=2. - - -File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS - -24.24 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). - - 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/regenerate your journal you should take care to also copy -over the directives and inter-transaction comments. - - Eg: - -$ hledger print -f examples/sample.journal date:200806 -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 - -* Menu: - -* print explicitness:: -* print amount style:: -* print parseability:: -* print other features:: -* print output format:: - - -File: hledger.info, Node: print explicitness, Next: print amount style, Up: print - -24.24.1 print explicitness --------------------------- - -Normally, whether posting amounts are implicit or explicit is preserved. -For example, when an amount is omitted in the journal, it will not -appear in the output. Similarly, if a conversion cost is implied but -not written, it will not appear in the output. - - You can use the '-x'/'--explicit' flag to force explicit display of -all amounts and costs. This 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'. - - The '-x'/'--explicit' flag will cause any postings with a -multi-commodity amount (which can arise when a multi-commodity -transaction has an implicit amount) to be split into multiple -single-commodity postings, keeping the output parseable. - - -File: hledger.info, Node: print amount style, Next: print parseability, Prev: print explicitness, Up: print - -24.24.2 print amount style --------------------------- - -Amounts are shown right-aligned within each transaction (but not aligned -across all transactions; you can do that with ledger-mode in Emacs). - - Amounts will be (mostly) normalised to their commodity display style: -their symbol placement, decimal mark, and digit group marks will be made -consistent. By default, decimal digits are shown as they are written in -the journal. - - With the '--round' option, 'print' will try increasingly hard to -display decimal digits according to the commodity display styles: - - * '--round=none' show amounts with original precisions (default) - * '--round=soft' add/remove decimal zeros in amounts (except costs) - * '--round=hard' round amounts (except costs), possibly hiding - significant digits - * '--round=all' round all amounts and costs - - 'soft' is good for non-lossy cleanup, formatting amounts more -consistently where it's safe to do so. - - 'hard' and 'all' can cause 'print' to show invalid unbalanced journal -entries; they may be useful eg for stronger cleanup, with manual fixups -when needed. - - -File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print - -24.24.3 print parseability --------------------------- - -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 (though the same can be achieved with 'expr:' queries -now): - -# 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: - - * Value reporting 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. - - -File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print - -24.24.4 print, other features ------------------------------ - -With '-B'/'--cost', amounts with costs are shown converted to cost. - - With '--new', print shows 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.) - - With '-m DESC'/'--match=DESC', print shows one recent transaction -whose description is most similar to DESC. DESC should contain at least -two characters. If there is no similar-enough match, no transaction -will be shown and the program exit code will be non-zero. - - -File: hledger.info, Node: print output format, Prev: print other features, Up: print - -24.24.5 print output format ---------------------------- - -This command also supports the output destination and output format -options The output formats supported are 'txt', 'beancount', 'csv', -'tsv', 'json' and 'sql'. - - _Experimental:_ The 'beancount' format tries to produce -Beancount-compatible output, as follows: - - * Transaction and postings with unmarked status are converted to - cleared ('*') status. - * Transactions' payee and note are backslash-escaped and - double-quote-escaped and wrapped in double quotes. - * Transaction tags are copied to Beancount #tag format. - * Commodity symbols are converted to upper case, and a small number - of currency symbols like '$' are converted to the corresponding - currency names. - * Account name parts are capitalised and unsupported characters are - replaced with '-'. If an account name part does not begin with a - letter, or if the first part is not Assets, Liabilities, Equity, - Income, or Expenses, an error is raised. (Use '--alias' options to - bring your accounts into compliance.) - * An 'open' directive is generated for each account used, on the - earliest transaction date. - - Some limitations: - - * Balance assertions are removed. - * Balance assignments become missing amounts. - * Virtual and balanced virtual postings become regular postings. - * Directives are not converted. - - Here's an example of print's CSV output: - -$ hledger print -Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" -"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" -"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - * There is one CSV record per posting, with the parent transaction's - fields repeated. - * The "txnidx" (transaction index) field shows which postings belong - to the same transaction. (This number might change if transactions - are reordered within the file, files are parsed/included in a - different order, etc.) - * The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - * The numeric amount is repeated in either the "credit" or "debit" - column, for convenience. (Those names are not accurate in the - accounting sense; it just puts negative amounts under credit and - zero or greater amounts under debit.) - - -File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS - -24.25 register -============== - -(reg) - - Show postings and their running total. - - The register command displays matched postings, across all accounts, -in date order, with their running total or running historical balance. -(See also the 'aregister' command, which shows matched transactions in a -specific account.) - - register normally shows line per posting, but note that -multi-commodity amounts will occupy multiple lines (one line per -commodity). - - It is typically used with a query selecting a particular account, to -see that account's activity: - -$ hledger register checking -2008/01/01 income assets:bank:checking $1 $1 -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 - - With '--date2', it shows and sorts by secondary date instead. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -'--align-all' flag. - - The '--historical'/'-H' flag adds the balance from any undisplayed -prior postings to the running total. This is useful when you want to -see only recent activity, with a historically accurate running balance: - -$ hledger register checking -b 2008/6 --historical -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 - - The '--depth' option limits the amount of sub-account detail -displayed. - - The '--average'/'-A' flag shows the running average posting amount -instead of the running total (so, the final number displayed is the -average for the whole report period). This flag implies '--empty' (see -below). It is affected by '--historical'. It works best when showing -just one account and one commodity. - - The '--related'/'-r' flag shows the _other_ postings in the -transactions of the postings which would normally be shown. - - The '--invert' flag negates all amounts. For example, it can be used -on an income account where amounts are normally displayed as negative -numbers. It's also useful to show postings on the checking account -together with the related account: - -$ hledger register --related --invert assets:checking - - With a reporting interval, register shows summary postings, one per -interval, aggregating the postings to each account: - -$ hledger register --monthly income -2008/01 income:salary $-1 $-1 -2008/06 income:gifts $-1 $-2 - - Periods with no activity, and summary postings with a zero amount, -are not shown by default; use the '--empty'/'-E' flag to see them: - -$ hledger register --monthly income -E -2008/01 income:salary $-1 $-1 -2008/02 0 $-1 -2008/03 0 $-1 -2008/04 0 $-1 -2008/05 0 $-1 -2008/06 income:gifts $-1 $-2 -2008/07 0 $-2 -2008/08 0 $-2 -2008/09 0 $-2 -2008/10 0 $-2 -2008/11 0 $-2 -2008/12 0 $-2 - - Often, you'll want to see just one line per interval. The '--depth' -option helps with this, causing subaccounts to be aggregated: - -$ hledger register --monthly assets --depth 1h -2008/01 assets $1 $1 -2008/06 assets $-1 0 -2008/12 assets $-1 $-1 - - Note when using report intervals, if you specify start/end dates -these will be adjusted outward if necessary to contain a whole number of -intervals. This ensures that the first and last intervals are full -length and comparable to the others in the report. - - With '-m DESC'/'--match=DESC', register does a fuzzy search for one -recent posting whose description is most similar to DESC. DESC should -contain at least two characters. If there is no similar-enough match, -no posting will be shown and the program exit code will be non-zero. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -24.25.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', 'tsv', and -(experimental) 'json'. - - -File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS - -24.26 rewrite -============= - -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - - This is a start at a generic rewriter of transaction entries. It -reads the default journal and prints the transactions, like print, but -adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing -transaction's first posting amount. - - Examples: - -$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -$ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the -two spaces between account and amount. - - More: - -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for '--add-posting' option is a usual posting of transaction -with an exception for amount specification. More precisely, you can use -''*'' (star symbol) before the amount to indicate that that this is a -factor for an amount of original matched posting. If the amount -includes a commodity name, the new posting amount will be in the new -commodity; otherwise, it will be in the matched posting amount's -commodity. - -* Menu: - -* Re-write rules in a file:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -24.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 - -24.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 - -24.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: PART 4 COMMANDS - -24.27 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, also known as money-weighted rate of return) and time-weighted -rate of return (TWR) for your investments for the time period requested. -IRR is always annualized due to the way it is computed, but TWR is -reported both as a rate over the chosen reporting period and as an -annual rate. - - Price directives will be taken into account if you supply appropriate -'--cost' or '--value' flags (see VALUATION). - - Note, in some cases this report can fail, for these reasons: - - * Error (NotBracketed): No solution for Internal Rate of Return - (IRR). Possible causes: IRR is huge (>1000000%), balance of - investment becomes negative at some point in time. - * Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or - converges too slowly. - - Examples: - - * Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger - - * Cookbook > Return on Investment: https://hledger.org/roi.html - -* Menu: - -* Spaces and special characters in --inv and --pnl:: -* Semantics of --inv and --pnl:: -* IRR and TWR explained:: - - -File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi - -24.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 - -24.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 - -24.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, and -the time between them. Investment at a particular fixed interest rate -is going to give you more interest than the same amount invested at the -same interest rate, but made later in time. 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, -so your IRR will be smaller. And if you are adding to your investment, -you will receive bigger absolute gains, which will be a bigger -percentage of your initial investment, so your IRR will be larger. - - 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 -account for the effect of your in-flows and out-flows, but unlike IRR it -will try to compute the true rate of return of the underlying asset, -compensating for the effect that deposits and withdrawas have on the -apparent rate of growth of your investment. - - 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, and make TWR less sensitive than IRR to the effects of -cash in-flows and out-flows. - - References: - - * Explanation of rate of return - * Explanation of IRR - * Explanation of TWR - * IRR vs TWR - * Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS - -24.28 stats -=========== - -Show journal and performance statistics. - - The stats command displays summary information for the whole journal, -or a matched part of it. With a reporting interval, it shows a report -for each report period. - - At the end, it shows (in the terminal) the overall run time and -number of transactions processed per second. Note these are approximate -and will vary based on machine, current load, data size, hledger -version, haskell lib versions, GHC version.. but they may be of -interest. The 'stats' command's run time is similar to that of a -single-column balance report. - - Example: - -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s - - This command supports the -o/-output-file option (but not --O/-output-format selection). - - -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS - -24.29 tags -========== - -List the tags used in the journal, or their values. - - This command lists the tag names used in the journal, whether on -transactions, postings, or account declarations. - - With a TAGREGEX argument, only tag names matching this regular -expression (case insensitive, infix matched) are shown. - - With QUERY arguments, only transactions and accounts matching this -query are considered. If the query involves transaction fields (date:, -desc:, amt:, ...), the search is restricted to the matched transactions -and their accounts. - - With the -values flag, the tags' unique non-empty values are listed -instead. With -E/-empty, blank/empty values are also shown. - - With -parsed, tags or values are shown in the order they were parsed, -with duplicates included. (Except, tags from account declarations are -always shown first.) - - Tip: remember, accounts also acquire tags from their parents, -postings also acquire tags from their account and transaction, -transactions also acquire tags from their postings. - - -File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS - -24.30 test -========== - -Run built-in unit tests. - - This command runs the unit tests built in to hledger and hledger-lib, -printing the results on stdout. If any test fails, the exit code will -be non-zero. - - This is mainly used by hledger developers, but you can also use it to -sanity-check the installed hledger executable on your platform. All -tests are expected to pass - if you ever see a failure, please report as -a bug! - - This command also accepts tasty test runner options, written after a -- (double hyphen). Eg to run only the tests in Hledger.Data.Amount, -with ANSI colour codes disabled: - -$ hledger test -- -pData.Amount --color=never - - For help on these, see https://github.com/feuerbach/tasty#options -('-- --help' currently doesn't show them). - - -File: hledger.info, Node: PART 5 COMMON TASKS, Next: BUGS, Prev: PART 4 COMMANDS, Up: Top - -25 PART 5: COMMON TASKS -*********************** - -Here are some quick examples of how to do some basic tasks with hledger. - -* Menu: - -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting LEDGER_FILE:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: - - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS - -25.1 Getting help -================= - -Here's how to list commands and view options and command docs: - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version's manual in several formats by -using the help command. Eg: - -$ hledger help # show the hledger manual with info, man or $PAGER (best available) -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit -https://hledger.org. Chat and mail list support and discussion archives -can be found at https://hledger.org/support. - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS - -25.2 Constructing command lines -=============================== - -hledger has a flexible command line interface. We strive to keep it -simple and ergonomic, but if you run into one of the sharp edges -described in OPTIONS, here are some tips that might help: - - * command-specific options must go after the command (it's fine to - put common options there too: 'hledger CMD OPTS ARGS') - * running add-on executables directly simplifies command line parsing - ('hledger-ui OPTS ARGS') - * enclose "problematic" args in single quotes - * if needed, also add a backslash to hide regular expression - metacharacters from the shell - * to see how a misbehaving command line is being parsed, add - '--debug=2'. - - -File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: PART 5 COMMON TASKS - -25.3 Starting a journal file -============================ - -hledger looks for your accounting data in a journal file, -'$HOME/.hledger.journal' by default: - -$ hledger stats -The hledger journal file "/Users/simon/.hledger.journal" was not found. -Please create it first, eg with "hledger add" or a text editor. -Or, specify an existing journal file with -f or LEDGER_FILE. - - You can override this by setting the 'LEDGER_FILE' environment -variable (see below). 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 2023.journal -$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile -$ source ~/.profile -$ hledger stats -Main file : /Users/simon/finance/2023.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 LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: PART 5 COMMON TASKS - -25.4 Setting LEDGER_FILE -======================== - -How to set 'LEDGER_FILE' permanently depends on your setup: - - On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: - -$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile -$ source ~/.profile - - When correctly configured, in a new terminal window 'env | grep -LEDGER_FILE' will show your file, and so will 'hledger files'. - - On mac, this additional step might be helpful for GUI applications -(like Emacs started from the dock): add an entry to -'~/.MacOSX/environment.plist' like - -{ - "LEDGER_FILE" : "~/finance/2023.journal" -} - - and then run 'killall Dock' in a terminal window (or restart the -machine). - - On Windows, see https://www.java.com/en/download/help/path.html, or -try running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): - -> CD -> MKDIR finance -> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: PART 5 COMMON TASKS - -25.5 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: - - 2023-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/2023.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 [2023-02-07]: 2023-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): . - 2023-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 [2023-01-01]: . - - If you're using version control, this could be a good time to commit -the journal. Eg: - -$ git commit -m 'initial balances' 2023.journal - - -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS - -25.6 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: - -2023/1/10 * gift received - assets:cash $20 - income:gifts - -2023.1.12 * farmers market - expenses:food $13 - assets:cash - -2023-01-15 paycheck - income:salary - assets:bank:checking $1000 - - -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS - -25.7 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: - - 2023-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 '2023-01-15' and 'paycheck' - - If you're using version control, this can be another good time to -commit: - -$ git commit -m 'txns' 2023.journal - - -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS - -25.8 Reporting -============== - -Here are some basic reports. - - Show all transactions: - -$ hledger print -2023-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -2023-01-10 * gift received - assets:cash $20 - income:gifts - -2023-01-12 * farmers market - expenses:food $13 - assets:cash - -2023-01-15 * paycheck - income:salary - assets:bank:checking $1000 - -2023-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - -$ hledger accounts --tree -assets - bank - checking - savings - cash -equity - opening/closing balances -expenses - food - misc -income - gifts - salary -liabilities - creditcard - - Show all account totals: - -$ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard --------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to -depth 2: - -$ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard --------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple -balance sheet: - -$ hledger bs -2 -Balance Sheet 2023-01-16 - - || 2023-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 2023-01-01-2023-01-16 - - || 2023-01-01-2023-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 -2023-01-01 opening balances assets:cash $100 $100 -2023-01-10 gift received assets:cash $20 $120 -2023-01-12 farmers market assets:cash $-13 $107 -2023-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - -$ hledger activity -W -2019-12-30 ***** -2023-01-06 **** -2023-01-13 **** - - -File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS - -25.9 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: BUGS, Prev: PART 5 COMMON TASKS, Up: Top - -26 BUGS -******* - -We welcome bug reports in the hledger issue tracker (shortcut: -http://bugs.hledger.org), or on the #hledger chat or hledger mail list -(https://hledger.org/support). - - Some known issues and limitations: - - The need to precede add-on command options with '--' when invoked -from hledger is awkward. (See Command options, Constructing command -lines.) - - A UTF-8-aware system locale must be configured to work with non-ascii -data. (See Unicode characters, Troubleshooting.) - - On Microsoft Windows, depending whether you are running in a CMD -window or a Cygwin/MSYS/Mintty window and how you installed hledger, -non-ascii characters and colours may not be supported, and the tab key -may not be supported by 'hledger add'. (Running in a WSL window should -resolve these.) - - When processing large data files, hledger uses more memory than -Ledger. - -* Menu: - -* Troubleshooting:: - - -File: hledger.info, Node: Troubleshooting, Up: BUGS - -26.1 Troubleshooting -==================== - -Here are some common issues you might encounter when you run hledger, -and how to resolve them (and remember also you can usually get quick -Support): - - *PATH issues: I get an error like "No command 'hledger' found"* -Depending how you installed hledger, the executables may not be in your -shell's PATH. Eg on unix systems, stack installs hledger in -'~/.local/bin' and cabal installs it in '~/.cabal/bin'. You may need to -add one of these directories to your shell's PATH, and/or open a new -terminal window. - - *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not -using it* - - * 'LEDGER_FILE' should be a real environment variable, not just a - shell variable. Eg on unix, the command 'env | grep LEDGER_FILE' - should show it. You may need to use 'export' (see - https://stackoverflow.com/a/7411509). - * You may need to force your shell to see the new configuration. A - simple way is to close your terminal window and open a new one. - - *LANG issues: I get 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 -the system locale to be UTF-8-aware, or they will fail when they -encounter non-ascii characters. To fix it, set the LANG environment -variable to a locale which supports UTF-8 and which is installed on your -system. - - On unix, 'locale -a' lists the installed locales. Look for one which -mentions 'utf8', 'UTF-8' or similar. Some examples: 'C.UTF-8', -'en_US.utf-8', 'fr_FR.utf8'. If necessary, use your system package -manager to install one. Then select it by setting the 'LANG' -environment variable. Note, exact spelling and capitalisation of the -locale name may be important: Here's one common way to configure this -permanently for your shell: - -$ echo "export LANG=en_US.utf8" >>~/.profile -# close and re-open terminal window - - If you are using Nix (not NixOS) for GHC and Hledger, you might need -to set the 'LOCALE_ARCHIVE' variable: - -$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile -# close and re-open terminal window - - *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file* -Not all of Ledger's journal file syntax or feature set is supported. -See hledger and Ledger for full details. - - -Tag Table: -Node: Top210 -Node: PART 1 USER INTERFACE3820 -Ref: #part-1-user-interface3959 -Node: Input3959 -Ref: #input4069 -Node: Data formats5018 -Ref: #data-formats5131 -Node: Standard input6493 -Ref: #standard-input6633 -Node: Multiple files6860 -Ref: #multiple-files6999 -Node: Strict mode7597 -Ref: #strict-mode7707 -Node: Commands8431 -Ref: #commands8533 -Node: Add-on commands9600 -Ref: #add-on-commands9702 -Node: Options10818 -Ref: #options10930 -Node: General help options11258 -Ref: #general-help-options11404 -Node: General input options11686 -Ref: #general-input-options11868 -Node: General reporting options12570 -Ref: #general-reporting-options12731 -Node: Command line tips16121 -Ref: #command-line-tips16251 -Node: Option repetition16510 -Ref: #option-repetition16654 -Node: Special characters16758 -Ref: #special-characters16931 -Node: Single escaping shell metacharacters17094 -Ref: #single-escaping-shell-metacharacters17335 -Node: Double escaping regular expression metacharacters17938 -Ref: #double-escaping-regular-expression-metacharacters18249 -Node: Triple escaping for add-on commands18775 -Ref: #triple-escaping-for-add-on-commands19035 -Node: Less escaping19679 -Ref: #less-escaping19833 -Node: Unicode characters20157 -Ref: #unicode-characters20332 -Node: Regular expressions21744 -Ref: #regular-expressions21917 -Node: hledger's regular expressions25013 -Ref: #hledgers-regular-expressions25172 -Node: Argument files26558 -Ref: #argument-files26694 -Node: Output27191 -Ref: #output27303 -Node: Output destination27430 -Ref: #output-destination27561 -Node: Output format27986 -Ref: #output-format28132 -Node: CSV output29729 -Ref: #csv-output29845 -Node: HTML output29948 -Ref: #html-output30086 -Node: JSON output30180 -Ref: #json-output30318 -Node: SQL output31240 -Ref: #sql-output31356 -Node: Commodity styles32091 -Ref: #commodity-styles32231 -Node: Colour32830 -Ref: #colour32948 -Node: Box-drawing33352 -Ref: #box-drawing33470 -Node: Paging33760 -Ref: #paging33874 -Node: Debug output34827 -Ref: #debug-output34933 -Node: Environment35596 -Ref: #environment35720 -Node: PART 2 DATA FORMATS36264 -Ref: #part-2-data-formats36407 -Node: Journal36407 -Ref: #journal36516 -Node: Journal cheatsheet37173 -Ref: #journal-cheatsheet37312 -Node: About journal format41297 -Ref: #about-journal-format41457 -Node: Comments43073 -Ref: #comments43203 -Node: Transactions44019 -Ref: #transactions44142 -Node: Dates45156 -Ref: #dates45263 -Node: Simple dates45308 -Ref: #simple-dates45424 -Node: Posting dates45924 -Ref: #posting-dates46042 -Node: Status47011 -Ref: #status47112 -Node: Code48820 -Ref: #code48923 -Node: Description49155 -Ref: #description49286 -Node: Payee and note49606 -Ref: #payee-and-note49712 -Node: Transaction comments50047 -Ref: #transaction-comments50200 -Node: Postings50563 -Ref: #postings50696 -Node: Account names51691 -Ref: #account-names51821 -Node: Amounts53495 -Ref: #amounts53610 -Node: Decimal marks digit group marks54595 -Ref: #decimal-marks-digit-group-marks54770 -Node: Commodity55629 -Ref: #commodity55816 -Node: Directives influencing number parsing and display56768 -Ref: #directives-influencing-number-parsing-and-display57027 -Node: Commodity display style57479 -Ref: #commodity-display-style57685 -Node: Rounding59095 -Ref: #rounding59213 -Node: Costs59663 -Ref: #costs59779 -Node: Other cost/lot notations61975 -Ref: #other-costlot-notations62107 -Node: Balance assertions64696 -Ref: #balance-assertions64847 -Node: Assertions and ordering65930 -Ref: #assertions-and-ordering66119 -Node: Assertions and multiple included files66819 -Ref: #assertions-and-multiple-included-files67079 -Node: Assertions and multiple -f files67579 -Ref: #assertions-and-multiple--f-files67830 -Node: Assertions and commodities68227 -Ref: #assertions-and-commodities68449 -Node: Assertions and prices69629 -Ref: #assertions-and-prices69835 -Node: Assertions and subaccounts70262 -Ref: #assertions-and-subaccounts70483 -Node: Assertions and virtual postings70807 -Ref: #assertions-and-virtual-postings71045 -Node: Assertions and auto postings71177 -Ref: #assertions-and-auto-postings71407 -Node: Assertions and precision72052 -Ref: #assertions-and-precision72234 -Node: Posting comments72501 -Ref: #posting-comments72647 -Node: Tags73024 -Ref: #tags73138 -Node: Tag values74331 -Ref: #tag-values74420 -Node: Directives75179 -Ref: #directives75306 -Node: Directives and multiple files76636 -Ref: #directives-and-multiple-files76814 -Node: Directive effects77581 -Ref: #directive-effects77735 -Node: account directive80748 -Ref: #account-directive80904 -Node: Account comments82302 -Ref: #account-comments82452 -Node: Account subdirectives82960 -Ref: #account-subdirectives83151 -Node: Account error checking83293 -Ref: #account-error-checking83491 -Node: Account display order84680 -Ref: #account-display-order84868 -Node: Account types85969 -Ref: #account-types86110 -Node: alias directive89737 -Ref: #alias-directive89898 -Node: Basic aliases90948 -Ref: #basic-aliases91079 -Node: Regex aliases91823 -Ref: #regex-aliases91980 -Node: Combining aliases92870 -Ref: #combining-aliases93048 -Node: Aliases and multiple files94324 -Ref: #aliases-and-multiple-files94528 -Node: end aliases directive95107 -Ref: #end-aliases-directive95326 -Node: Aliases can generate bad account names95475 -Ref: #aliases-can-generate-bad-account-names95723 -Node: Aliases and account types96308 -Ref: #aliases-and-account-types96500 -Node: commodity directive97196 -Ref: #commodity-directive97370 -Node: Commodity directive syntax98555 -Ref: #commodity-directive-syntax98740 -Node: Commodity error checking100119 -Ref: #commodity-error-checking100300 -Node: decimal-mark directive100594 -Ref: #decimal-mark-directive100776 -Node: include directive101173 -Ref: #include-directive101337 -Node: P directive102249 -Ref: #p-directive102394 -Node: payee directive103283 -Ref: #payee-directive103432 -Node: tag directive103748 -Ref: #tag-directive103903 -Node: Periodic transactions104371 -Ref: #periodic-transactions104536 -Node: Periodic rule syntax106242 -Ref: #periodic-rule-syntax106420 -Node: Periodic rules and relative dates107065 -Ref: #periodic-rules-and-relative-dates107331 -Node: Two spaces between period expression and description!107842 -Ref: #two-spaces-between-period-expression-and-description108119 -Node: Auto postings108803 -Ref: #auto-postings108951 -Node: Auto postings and multiple files111388 -Ref: #auto-postings-and-multiple-files111552 -Node: Auto postings and dates111953 -Ref: #auto-postings-and-dates112201 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions112376 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112732 -Node: Auto posting tags113235 -Ref: #auto-posting-tags113517 -Node: Auto postings on forecast transactions only114153 -Ref: #auto-postings-on-forecast-transactions-only114399 -Node: Other syntax114646 -Ref: #other-syntax114762 -Node: Balance assignments115389 -Ref: #balance-assignments115545 -Node: Balance assignments and prices116918 -Ref: #balance-assignments-and-prices117133 -Node: Balance assignments and multiple files117344 -Ref: #balance-assignments-and-multiple-files117575 -Node: Bracketed posting dates117768 -Ref: #bracketed-posting-dates117952 -Node: D directive118466 -Ref: #d-directive118634 -Node: apply account directive120234 -Ref: #apply-account-directive120414 -Node: Y directive121101 -Ref: #y-directive121261 -Node: Secondary dates122089 -Ref: #secondary-dates122243 -Node: Star comments123057 -Ref: #star-comments123217 -Node: Valuation expressions123749 -Ref: #valuation-expressions123926 -Node: Virtual postings124048 -Ref: #virtual-postings124225 -Node: Other Ledger directives125662 -Ref: #other-ledger-directives125825 -Node: CSV126391 -Ref: #csv126484 -Node: CSV rules cheatsheet128564 -Ref: #csv-rules-cheatsheet128693 -Node: source130491 -Ref: #source130614 -Node: separator131494 -Ref: #separator131607 -Node: skip132147 -Ref: #skip132255 -Node: date-format132799 -Ref: #date-format132920 -Node: timezone133644 -Ref: #timezone133767 -Node: newest-first134772 -Ref: #newest-first134910 -Node: intra-day-reversed135487 -Ref: #intra-day-reversed135641 -Node: decimal-mark136089 -Ref: #decimal-mark136230 -Node: fields list136569 -Ref: #fields-list136708 -Node: Field assignment138379 -Ref: #field-assignment138523 -Node: Field names139600 -Ref: #field-names139731 -Node: date field140934 -Ref: #date-field141052 -Node: date2 field141100 -Ref: #date2-field141241 -Node: status field141297 -Ref: #status-field141440 -Node: code field141489 -Ref: #code-field141634 -Node: description field141679 -Ref: #description-field141839 -Node: comment field141898 -Ref: #comment-field142053 -Node: account field142346 -Ref: #account-field142496 -Node: amount field143066 -Ref: #amount-field143215 -Node: currency field145907 -Ref: #currency-field146060 -Node: balance field146317 -Ref: #balance-field146449 -Node: if block146821 -Ref: #if-block146942 -Node: Matchers148350 -Ref: #matchers148464 -Node: Match groups150048 -Ref: #match-groups150149 -Node: if table150896 -Ref: #if-table151018 -Node: balance-type152580 -Ref: #balance-type152709 -Node: include153409 -Ref: #include153536 -Node: Working with CSV153980 -Ref: #working-with-csv154127 -Node: Rapid feedback154534 -Ref: #rapid-feedback154667 -Node: Valid CSV155119 -Ref: #valid-csv155265 -Node: File Extension155997 -Ref: #file-extension156170 -Node: Reading CSV from standard input156734 -Ref: #reading-csv-from-standard-input156958 -Node: Reading multiple CSV files157122 -Ref: #reading-multiple-csv-files157353 -Node: Reading files specified by rule157594 -Ref: #reading-files-specified-by-rule157822 -Node: Valid transactions158993 -Ref: #valid-transactions159192 -Node: Deduplicating importing159820 -Ref: #deduplicating-importing160015 -Node: Setting amounts161051 -Ref: #setting-amounts161222 -Node: Amount signs163580 -Ref: #amount-signs163750 -Node: Setting currency/commodity164647 -Ref: #setting-currencycommodity164851 -Node: Amount decimal places166025 -Ref: #amount-decimal-places166231 -Node: Referencing other fields166543 -Ref: #referencing-other-fields166756 -Node: How CSV rules are evaluated167653 -Ref: #how-csv-rules-are-evaluated167870 -Node: Well factored rules169323 -Ref: #well-factored-rules169491 -Node: CSV rules examples169815 -Ref: #csv-rules-examples169950 -Node: Bank of Ireland170015 -Ref: #bank-of-ireland170152 -Node: Coinbase171614 -Ref: #coinbase171752 -Node: Amazon172799 -Ref: #amazon172924 -Node: Paypal174643 -Ref: #paypal174751 -Node: Timeclock182395 -Ref: #timeclock182500 -Node: Timedot184678 -Ref: #timedot184801 -Node: Timedot examples187906 -Ref: #timedot-examples188012 -Node: PART 3 REPORTING CONCEPTS190183 -Ref: #part-3-reporting-concepts190365 -Node: Amount formatting parseability190365 -Ref: #amount-formatting-parseability190562 -Node: Time periods192767 -Ref: #time-periods192906 -Node: Report start & end date193024 -Ref: #report-start-end-date193176 -Node: Smart dates194835 -Ref: #smart-dates194988 -Node: Report intervals196856 -Ref: #report-intervals197011 -Node: Date adjustment197429 -Ref: #date-adjustment197589 -Node: Period expressions198440 -Ref: #period-expressions198581 -Node: Period expressions with a report interval200345 -Ref: #period-expressions-with-a-report-interval200579 -Node: More complex report intervals200793 -Ref: #more-complex-report-intervals201038 -Node: Multiple weekday intervals202839 -Ref: #multiple-weekday-intervals203028 -Node: Depth203850 -Ref: #depth203952 -Node: Queries204248 -Ref: #queries204350 -Node: Query types205475 -Ref: #query-types205596 -Node: Combining query terms208932 -Ref: #combining-query-terms209109 -Node: Queries and command options210377 -Ref: #queries-and-command-options210576 -Node: Queries and valuation210825 -Ref: #queries-and-valuation211020 -Node: Querying with account aliases211249 -Ref: #querying-with-account-aliases211460 -Node: Querying with cost or value211590 -Ref: #querying-with-cost-or-value211767 -Node: Pivoting212068 -Ref: #pivoting212182 -Node: Generating data213959 -Ref: #generating-data214091 -Node: Forecasting215674 -Ref: #forecasting215799 -Node: --forecast216330 -Ref: #forecast216461 -Node: Inspecting forecast transactions217507 -Ref: #inspecting-forecast-transactions217709 -Node: Forecast reports218839 -Ref: #forecast-reports219012 -Node: Forecast tags219948 -Ref: #forecast-tags220108 -Node: Forecast period in detail220568 -Ref: #forecast-period-in-detail220762 -Node: Forecast troubleshooting221656 -Ref: #forecast-troubleshooting221824 -Node: Budgeting222727 -Ref: #budgeting222847 -Node: Cost reporting223284 -Ref: #cost-reporting223418 -Node: Recording costs224079 -Ref: #recording-costs224215 -Node: Reporting at cost225806 -Ref: #reporting-at-cost225981 -Node: Equity conversion postings226571 -Ref: #equity-conversion-postings226785 -Node: Inferring equity conversion postings229216 -Ref: #inferring-equity-conversion-postings229479 -Node: Combining costs and equity conversion postings230231 -Ref: #combining-costs-and-equity-conversion-postings230541 -Node: Requirements for detecting equity conversion postings231529 -Ref: #requirements-for-detecting-equity-conversion-postings231851 -Node: Infer cost and equity by default ?233051 -Ref: #infer-cost-and-equity-by-default233280 -Node: Value reporting233488 -Ref: #value-reporting233630 -Node: -V Value234404 -Ref: #v-value234536 -Node: -X Value in specified commodity234731 -Ref: #x-value-in-specified-commodity234932 -Node: Valuation date235081 -Ref: #valuation-date235258 -Node: Finding market price236041 -Ref: #finding-market-price236252 -Node: --infer-market-prices market prices from transactions237421 -Ref: #infer-market-prices-market-prices-from-transactions237703 -Node: Valuation commodity240465 -Ref: #valuation-commodity240684 -Node: Simple valuation examples241897 -Ref: #simple-valuation-examples242101 -Node: --value Flexible valuation242760 -Ref: #value-flexible-valuation242970 -Node: More valuation examples244614 -Ref: #more-valuation-examples244829 -Node: Interaction of valuation and queries246099 -Ref: #interaction-of-valuation-and-queries246346 -Node: Effect of valuation on reports246818 -Ref: #effect-of-valuation-on-reports247021 -Node: PART 4 COMMANDS254718 -Ref: #part-4-commands254867 -Node: Commands overview255246 -Ref: #commands-overview255380 -Node: DATA ENTRY255559 -Ref: #data-entry255683 -Node: DATA CREATION255882 -Ref: #data-creation256036 -Node: DATA MANAGEMENT256154 -Ref: #data-management256319 -Node: REPORTS FINANCIAL256440 -Ref: #reports-financial256615 -Node: REPORTS VERSATILE256920 -Ref: #reports-versatile257093 -Node: REPORTS BASIC257346 -Ref: #reports-basic257498 -Node: HELP258007 -Ref: #help258129 -Node: ADD-ONS258239 -Ref: #add-ons258345 -Node: accounts258924 -Ref: #accounts259057 -Node: activity260944 -Ref: #activity261063 -Node: add261437 -Ref: #add261547 -Node: aregister264358 -Ref: #aregister264479 -Node: aregister and posting dates267367 -Ref: #aregister-and-posting-dates267512 -Node: balance268268 -Ref: #balance268394 -Node: balance features269379 -Ref: #balance-features269519 -Node: Simple balance report271485 -Ref: #simple-balance-report271670 -Node: Balance report line format273295 -Ref: #balance-report-line-format273497 -Node: Filtered balance report275655 -Ref: #filtered-balance-report275847 -Node: List or tree mode276174 -Ref: #list-or-tree-mode276342 -Node: Depth limiting277687 -Ref: #depth-limiting277853 -Node: Dropping top-level accounts278454 -Ref: #dropping-top-level-accounts278654 -Node: Showing declared accounts278964 -Ref: #showing-declared-accounts279163 -Node: Sorting by amount279694 -Ref: #sorting-by-amount279861 -Node: Percentages280531 -Ref: #percentages280690 -Node: Multi-period balance report281238 -Ref: #multi-period-balance-report281438 -Node: Balance change end balance283713 -Ref: #balance-change-end-balance283922 -Node: Balance report types285350 -Ref: #balance-report-types285531 -Node: Calculation type286029 -Ref: #calculation-type286184 -Node: Accumulation type286733 -Ref: #accumulation-type286913 -Node: Valuation type287815 -Ref: #valuation-type288003 -Node: Combining balance report types289004 -Ref: #combining-balance-report-types289198 -Node: Budget report291036 -Ref: #budget-report291198 -Node: Budget report start date296852 -Ref: #budget-report-start-date297030 -Node: Budgets and subaccounts298362 -Ref: #budgets-and-subaccounts298569 -Node: Selecting budget goals302009 -Ref: #selecting-budget-goals302208 -Node: Budget vs forecast303243 -Ref: #budget-vs-forecast303402 -Node: Balance report layout305032 -Ref: #balance-report-layout305212 -Node: Useful balance reports313397 -Ref: #useful-balance-reports313557 -Node: balancesheet314642 -Ref: #balancesheet314787 -Node: balancesheetequity316114 -Ref: #balancesheetequity316272 -Node: cashflow317668 -Ref: #cashflow317799 -Node: check319234 -Ref: #check319348 -Node: Default checks320152 -Ref: #default-checks320278 -Node: Strict checks320775 -Ref: #strict-checks320920 -Node: Other checks321400 -Ref: #other-checks321542 -Node: Custom checks322075 -Ref: #custom-checks322232 -Node: More about specific checks322649 -Ref: #more-about-specific-checks322811 -Node: close323517 -Ref: #close323628 -Node: close and balance assertions327093 -Ref: #close-and-balance-assertions327271 -Node: Example retain earnings328422 -Ref: #example-retain-earnings328639 -Node: Example migrate balances to a new file329071 -Ref: #example-migrate-balances-to-a-new-file329336 -Node: Example excluding closing/opening transactions329912 -Ref: #example-excluding-closingopening-transactions330161 -Node: codes331379 -Ref: #codes331496 -Node: commodities332360 -Ref: #commodities332488 -Node: demo332558 -Ref: #demo332679 -Node: descriptions333595 -Ref: #descriptions333725 -Node: diff334016 -Ref: #diff334131 -Node: files335173 -Ref: #files335282 -Node: help335423 -Ref: #help-1335532 -Node: import336905 -Ref: #import337028 -Node: Deduplication338136 -Ref: #deduplication338261 -Node: Import testing340280 -Ref: #import-testing340445 -Node: Importing balance assignments341288 -Ref: #importing-balance-assignments341494 -Node: Commodity display styles342143 -Ref: #commodity-display-styles342316 -Node: incomestatement342445 -Ref: #incomestatement342587 -Node: notes343915 -Ref: #notes344037 -Node: payees344399 -Ref: #payees344514 -Node: prices345033 -Ref: #prices345148 -Node: print345801 -Ref: #print345916 -Node: print explicitness346892 -Ref: #print-explicitness347035 -Node: print amount style347814 -Ref: #print-amount-style347984 -Node: print parseability349036 -Ref: #print-parseability349208 -Node: print other features349957 -Ref: #print-other-features350136 -Node: print output format350657 -Ref: #print-output-format350805 -Node: register353924 -Ref: #register354046 -Node: Custom register output359077 -Ref: #custom-register-output359208 -Node: rewrite360552 -Ref: #rewrite360670 -Node: Re-write rules in a file362568 -Ref: #re-write-rules-in-a-file362731 -Node: Diff output format363880 -Ref: #diff-output-format364063 -Node: rewrite vs print --auto365155 -Ref: #rewrite-vs.-print---auto365315 -Node: roi365871 -Ref: #roi365978 -Node: Spaces and special characters in --inv and --pnl367790 -Ref: #spaces-and-special-characters-in---inv-and---pnl368030 -Node: Semantics of --inv and --pnl368518 -Ref: #semantics-of---inv-and---pnl368757 -Node: IRR and TWR explained370607 -Ref: #irr-and-twr-explained370767 -Node: stats374020 -Ref: #stats374128 -Node: tags375515 -Ref: #tags-1375622 -Node: test376631 -Ref: #test376724 -Node: PART 5 COMMON TASKS377466 -Ref: #part-5-common-tasks377612 -Node: Getting help377910 -Ref: #getting-help378051 -Node: Constructing command lines378811 -Ref: #constructing-command-lines379012 -Node: Starting a journal file379669 -Ref: #starting-a-journal-file379871 -Node: Setting LEDGER_FILE381073 -Ref: #setting-ledger_file381265 -Node: Setting opening balances382222 -Ref: #setting-opening-balances382423 -Node: Recording transactions385564 -Ref: #recording-transactions385753 -Node: Reconciling386309 -Ref: #reconciling386461 -Node: Reporting388718 -Ref: #reporting388867 -Node: Migrating to a new file392852 -Ref: #migrating-to-a-new-file393009 -Node: BUGS393308 -Ref: #bugs393398 -Node: Troubleshooting394277 -Ref: #troubleshooting394377 + This manual is for hledger's command line interface, version 1.32.1. +It also describes the common options, file formats and concepts used by +all hledger programs. It might accidentally teach you some +bookkeeping/accounting as well! You don't need to know everything in +here to use hledger productively, but when you have a question about +functionality, this doc should answer it. It is detailed, so do skip +ahead or skim when needed. You can read it on hledger.org, or as an +info manual or man page on your system. You can also get it from +hledger itself with +'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'. + + The main function of the hledger CLI is to read plain text files +describing financial transactions, crunch the numbers, and print a +useful report on the terminal (or save it as HTML, CSV, JSON or SQL). +Many reports are available, as subcommands. hledger will also detect +other 'hledger-*' executables as extra subcommands. + + hledger usually reads from (and appends to) a journal file specified +by the 'LEDGER_FILE' environment variable (defaulting to +'$HOME/.hledger.journal'); or you can specify files with '-f' options. +It can also read timeclock files, timedot files, or any CSV/SSV/TSV file +with a date field. + + Here is a small journal file describing one transaction: + +2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more +_accounts_: bank accounts, your wallet, revenue/expense categories, +people, etc. You can choose any account names you wish, using ':' to +indicate subaccounts. There must be at least two spaces between account +name and amount. Positive amounts are inflow to that account (_debit_), +negatives are outflow from it (_credit_). (Some reports show revenue, +liability and equity account balances as negative numbers as a result; +this is normal.) + + hledger's add command can help you add transactions, or you can +install other data entry UIs like hledger-web or hledger-iadd. For more +extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM ++ vim-ledger, or VS Code + hledger-vscode are some good choices (see +https://hledger.org/editors.html). + + To get started, run 'hledger add' and follow the prompts, or save +some entries like the above in '$HOME/.hledger.journal', then try +commands like: +'hledger print -x' +'hledger aregister assets' +'hledger balance' +'hledger balancesheet' +'hledger incomestatement'. +Run 'hledger' to list the commands. See also the "Starting a journal +file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +* Menu: + +* PART 1 USER INTERFACE:: +* Input:: +* Commands:: +* Options:: +* Command line tips:: +* Output:: +* Environment:: +* PART 2 DATA FORMATS:: +* Journal:: +* CSV:: +* Timeclock:: +* Timedot:: +* PART 3 REPORTING CONCEPTS:: +* Amount formatting parseability:: +* Time periods:: +* Depth:: +* Queries:: +* Pivoting:: +* Generating data:: +* Forecasting:: +* Budgeting:: +* Cost reporting:: +* Value reporting:: +* PART 4 COMMANDS:: +* PART 5 COMMON TASKS:: +* BUGS:: + + +File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: Top + +1 PART 1: USER INTERFACE +************************ + + +File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top + +2 Input +******* + +hledger reads one or more data files, each time you run it. You can +specify a file with '-f', like so + +$ hledger -f FILE print + + Files are most often in hledger's journal format, with the '.journal' +file extension ('.hledger' or '.j' also work); these files describe +transactions, like an accounting general journal. + + When no file is specified, hledger looks for '.hledger.journal' in +your home directory. + + But most people prefer to keep financial files in a dedicated folder, +perhaps with version control. Also, starting a new journal file each +year is common (it's not required, but helps keep things fast and +organised). So we usually configure a different journal file, by +setting the 'LEDGER_FILE' environment variable, to something like +'~/finance/2023.journal'. For more about how to do that on your system, +see Common tasks > Setting LEDGER_FILE. + +* Menu: + +* Data formats:: +* Standard input:: +* Multiple files:: +* Strict mode:: + + +File: hledger.info, Node: Data formats, Next: Standard input, Up: Input + +2.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 '.journal' '.j' '.hledger' + some Ledger journals, for '.ledger' + transactions +'timeclock' timeclock files, for precise '.timeclock' + time logging +'timedot' timedot files, for '.timedot' + approximate time logging +'csv' CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv' + values, for data import '.csv.rules' '.ssv.rules' + '.tsv.rules' + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions +shown above. If it can't recognise the file extension, it assumes +'journal' format. So for non-journal files, it's important to use a +recognised file extension, so as to either read successfully or to show +relevant error messages. + + You can also force a specific reader/format by prefixing the file +path with the format and a colon. Eg, to read a .dat file as csv +format: + +$ hledger -f csv:/some/csv-file.dat stats + + +File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input + +2.2 Standard input +================== + +The file name '-' means standard input: + +$ cat FILE | hledger -f- print + + If reading non-journal data in this way, you'll need to add a file +format prefix, like: + +$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- + + +File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input + +2.3 Multiple files +================== + +You can specify multiple '-f' options, to read multiple files as one big +journal. When doing this, note that certain features (described below) +will be affected: + + * Balance assertions will not see the effect of transactions in + previous files. (Usually this doesn't matter as each file will set + the corresponding opening balances.) + * Some directives will not affect previous or subsequent files. + + If needed, you can work around these by using a single parent file +which includes the others, or concatenating the files into one, eg: 'cat +a.journal b.journal | hledger -f- CMD'. + + +File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input + +2.4 Strict mode +=============== + +hledger checks input files for valid data. By default, the most +important errors are detected, while still accepting easy journal files +without a lot of declarations: + + * Are the input files parseable, with valid syntax ? + * Are all transactions balanced ? + * Do all balance assertions pass ? + + With the '-s'/'--strict' flag, additional checks are performed: + + * Are all accounts posted to, declared with an 'account' directive ? + (Account error checking) + * Are all commodities declared with a 'commodity' directive ? + (Commodity error checking) + * Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks - the ones +listed above and some more. + + +File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top + +3 Commands +********** + +hledger provides various subcommands for getting things done. Most of +these commands do not change the journal file; they just read it and +output a report. A few commands assist with adding data and file +management. + + To show the commands list, run 'hledger' with no arguments. The +commands are described in detail in PART 4: COMMANDS, below. + + To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', + + * CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + * CMDOPTS are command-specific options, if any. Command-specific + options must be written after the command name. Eg: 'hledger print + -x'. + + * CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit + the data in some way. Eg: 'hledger reg assets:checking'. + + To list a command's options, arguments, and documentation in the +terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. + +* Menu: + +* Add-on commands:: + + +File: hledger.info, Node: Add-on commands, Up: Commands + +3.1 Add-on commands +=================== + +In addition to the built-in commands, you can install _add-on commands_: +programs or scripts named "hledger-SOMETHING", which will also appear in +hledger's commands list. If you used the hledger-install script, you +will have several add-ons installed already. Some more can be found in +hledger's bin/ directory, documented at +https://hledger.org/scripts.html. + + More precisely, add-on commands are programs or scripts in your +shell's PATH, whose name starts with "hledger-" and ends with no +extension or a recognised extension (".bat", ".com", ".exe", ".hs", +".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), +and (on unix and mac) which has executable permission for the current +user. + + You can run add-on commands using hledger, much like built-in +commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'. But note +the double hyphen argument, required before add-on-specific options. +Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'. If this causes +difficulty, you can always run the add-on directly, without using +'hledger': 'hledger-ui --watch' or 'hledger-web --serve'. + + +File: hledger.info, Node: Options, Next: Command line tips, Prev: Commands, Up: Top + +4 Options +********* + +Run 'hledger -h' to see general command line help, and general options +which are common to most hledger commands. These options can be written +anywhere on the command line. They can be grouped into help, input, and +reporting options: + +* Menu: + +* General help options:: +* General input options:: +* General reporting options:: + + +File: hledger.info, Node: General help options, Next: General input options, Up: Options + +4.1 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) + + +File: hledger.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: Options + +4.2 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) + + +File: hledger.info, Node: General reporting options, Prev: General input options, Up: Options + +4.3 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-equity' + + infer conversion equity postings from costs +'--infer-costs' + + infer costs from conversion equity postings +'--infer-market-prices' + + use costs as additional market prices, as if they were P directives +'--forecast' + + generate transactions from periodic rules, between the latest + recorded txn and 6 months from today, or during the specified + PERIOD (= is required). Auto posting rules will be applied to + these transactions as well. Also, in hledger-ui make future-dated + transactions visible. +'--auto' + + generate extra postings by applying auto posting rules to all txns + (not just forecast txns) +'--verbose-tags' + + add visible tags indicating transactions or postings which have + been generated/modified +'--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 line tips, Next: Output, Prev: Options, Up: Top + +5 Command line tips +******************* + +Here are some details useful to know about for hledger command lines +(and elsewhere). Feel free to skip this section until you need it. + +* Menu: + +* Option repetition:: +* Special characters:: +* Unicode characters:: +* Regular expressions:: +* Argument files:: + + +File: hledger.info, Node: Option repetition, Next: Special characters, Up: Command line tips + +5.1 Option repetition +===================== + +If options are repeated in a command line, hledger will generally use +the last (right-most) occurence. + + +File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Option repetition, Up: Command line tips + +5.2 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 + +5.2.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 + +5.2.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 + +5.2.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 + +5.2.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: Command line tips + +5.3 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, Next: Argument files, Prev: Unicode characters, Up: Command line tips + +5.4 Regular expressions +======================= + +A regular expression (regexp) is a small piece of text where certain +characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have +special meanings, forming a tiny language for matching text precisely - +very useful in hledger and elsewhere. To learn all about them, visit +regular-expressions.info. + + hledger supports regexps whenever you are entering a pattern to match +something, eg in query arguments, account aliases, CSV if rules, +hledger-web's search form, hledger-ui's '/' search, etc. You may need +to wrap them in quotes, especially at the command line (see Special +characters above). Here are some examples: + + Account name queries (quoted for command line use): + +Regular expression: Matches: +------------------- ------------------------------------------------------------ +bank assets:bank, assets:bank:savings, expenses:art:banksy, ... +:bank assets:bank:savings, expenses:art:banksy +:bank: assets:bank:savings +'^bank' none of those ( ^ matches beginning of text ) +'bank$' assets:bank ( $ matches end of text ) +'big \$ bank' big $ bank ( \ disables following character's special meaning ) +'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) +'(sav|check)ing' saving or checking ( (|) matches either alternative ) +'saving|checking' saving or checking ( outer parentheses are not needed ) +'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) +'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) +'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) +'b.nk' bank, bonk, b nk, ... ( . matches any character ) + + Some other queries: + +desc:'amazon|amzn|audible' Amazon transactions +cur:EUR amounts with commodity symbol containing EUR +cur:'\$' amounts with commodity symbol containing $ +cur:'^\$$' only $ amounts, not eg AU$ or CA$ +cur:....? amounts with 4-or-more-character symbols +tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 + + Account name aliases: accept '.' instead of ':' as account separator: + +alias /\./=: replaces all periods in account names with colons + + Show multiple top-level accounts combined as one: + +--alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) + + Show accounts with the second-level part removed: + +--alias '/^([^:]+):[^:]+/ = \1' + match a top-level account and a second-level account + and replace those with just the top-level account + ( \1 in the replacement text means "whatever was matched + by the first parenthesised part of the regexp" + + CSV rules: match CSV records containing dining-related MCC codes: + +if \?MCC581[124] + + Match CSV records with a specific amount around the end/start of +month: + +if %amount \b3\.99 +& %date (29|30|31|01|02|03)$ + +* Menu: + +* hledger's regular expressions:: + + +File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions + +5.4.1 hledger's regular expressions +----------------------------------- + +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. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the + replacement string to reference capturing groups in the search + regexp. Otherwise, if you write '\1', it will match the digit '1'. + 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: Argument files, Prev: Regular expressions, Up: Command line tips + +5.5 Argument files +================== + +You can save a set of command line options and arguments in a file, and +then reuse them by writing '@FILENAME' as a command line argument. Eg: +'hledger bal @foo.args'. + + Inside the argument file, each line should contain just one option or +argument. Don't use spaces except inside quotes (or you'll see a +confusing error); write '=' (or nothing) between a flag and its +argument. For the special characters mentioned above, use one less +level of quoting than you would at the command prompt. + + +File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips, Up: Top + +6 Output +******** + +* Menu: + +* Output destination:: +* Output format:: +* Commodity styles:: +* Colour:: +* Box-drawing:: +* Paging:: +* Debug output:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: Output + +6.1 Output destination +====================== + +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: + +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the '-o/--output-file' option, which does the same thing without +needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) + + +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output + +6.2 Output format +================= + +Some commands offer other kinds of output, not just text on the +terminal. Here are those commands and the formats currently supported: + +- txt csv/tsv html json sql +------------------------------------------------------------------------------- +aregister Y Y Y Y +balance Y _1_ Y _1_ Y _1,2_ Y +balancesheet Y _1_ Y _1_ Y _1_ Y +balancesheetequityY _1_ Y _1_ Y _1_ Y +cashflow Y _1_ Y _1_ Y _1_ Y +incomestatement Y _1_ Y _1_ Y _1_ Y +print Y Y Y Y +register Y Y Y + + * _1 Also affected by the balance commands' '--layout' option._ + * _2 'balance' does not support html output without a report interval + or with '--budget'._ + + The output format is selected by the '-O/--output-format=FMT' option: + +$ hledger print -O csv # print CSV on stdout + + or by the filename extension of an output file specified with the +'-o/--output-file=FILE.FMT' option: + +$ hledger balancesheet -o foo.csv # write CSV to foo.csv + + The '-O' option can be combined with '-o' to override the file +extension, if needed: + +$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt + + Some notes about the various output formats: + +* Menu: + +* CSV output:: +* HTML output:: +* JSON output:: +* SQL output:: + + +File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format + +6.2.1 CSV output +---------------- + + * In CSV output, digit group marks (such as thousands separators) are + disabled automatically. + + +File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format + +6.2.2 HTML output +----------------- + + * HTML output can be styled by an optional 'hledger.css' file in the + same directory. + + +File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format + +6.2.3 JSON output +----------------- + + * This is not yet much used; real-world feedback is welcome. + + * Our JSON is rather large and verbose, since it is a faithful + representation of hledger's internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + + * hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction + prices), and would break most JSON consumers. So in JSON, we show + quantities as simple Numbers with at most 10 decimal places. We + don't limit the number of integer digits, but that part is under + your control. We hope this approach will not cause problems in + practice; if you find otherwise, please let us know. (Cf #1195) + + +File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format + +6.2.4 SQL output +---------------- + + * This is not yet much used; real-world feedback is welcome. + + * SQL output is expected to work at least with SQLite, MySQL and + Postgres. + + * For SQLite, it will be more useful if you modify the generated 'id' + field to be a PRIMARY KEY. Eg: + + $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... + + * SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables + created via SQL output of hledger, you would probably want to + either clear tables of existing data (via 'delete' or 'truncate' + SQL statements) or drop tables completely as otherwise your + postings will be duped. + + +File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output + +6.3 Commodity styles +==================== + +When displaying amounts, hledger infers a standard display style for +each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a '-c/--commodity-style' option +(except for cost amounts and amounts displayed by the 'print' command, +which are always displayed with all decimal digits). For example, the +following will force dollar amounts to be displayed as shown: + +$ hledger print -c '$1.000,0' + + This option can repeated to set the display style for multiple +commodities/currencies. Its argument is as described in the commodity +directive. + + +File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output + +6.4 Colour +========== + +In terminal output, some commands can produce colour when the terminal +supports it: + + * if the '--color/--colour' option is given a value of 'yes' or + 'always' (or 'no' or 'never'), colour will (or will not) be used; + * otherwise, if the 'NO_COLOR' environment variable is set, colour + will not be used; + * otherwise, colour will be used if the output (terminal or file) + supports it. + + +File: hledger.info, Node: Box-drawing, Next: Paging, Prev: Colour, Up: Output + +6.5 Box-drawing +=============== + +In terminal output, you can enable unicode box-drawing characters to +render prettier tables: + + * if the '--pretty' option is given a value of 'yes' or 'always' (or + 'no' or 'never'), unicode characters will (or will not) be used; + * otherwise, unicode characters will not be used. + + +File: hledger.info, Node: Paging, Next: Debug output, Prev: Box-drawing, Up: Output + +6.6 Paging +========== + +When showing long output in the terminal, hledger will try to use the +pager specified by the 'PAGER' environment variable, or 'less', or +'more'. (A pager is a helper program that shows one page at a time +rather than scrolling everything off screen). Currently it does this +only for help output, not for reports; specifically, + + * when listing commands, with 'hledger' + * when showing help with 'hledger [CMD] --help', + * when viewing manuals with 'hledger help' or 'hledger --man'. + + Note the pager is expected to handle ANSI codes, which hledger uses +eg for bold emphasis. For the common pager 'less' (and its 'more' +compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment +variables to make this work. If you use a different pager, you might +need to configure it similarly, to avoid seeing junk on screen (let us +know). Otherwise, you can set the 'NO_COLOR' environment variable to 1 +to disable all ANSI output (see Colour). + + +File: hledger.info, Node: Debug output, Prev: Paging, Up: Output + +6.7 Debug output +================ + +We intend hledger to be relatively easy to troubleshoot, introspect and +develop. You can add '--debug[=N]' to any hledger command line to see +additional debug output. N ranges from 1 (least output, the default) to +9 (maximum output). Typically you would start with 1 and increase until +you are seeing enough. Debug output goes to stderr, and is not affected +by '-o/--output-file' (unless you redirect stderr to stdout, eg: +'2>&1'). It will be interleaved with normal output, which can help +reveal when parts of the code are evaluated. To capture debug output in +a log file instead, you can usually redirect stderr, eg: + +hledger bal --debug=3 2>hledger.log + + +File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top + +7 Environment +************* + +These environment variables affect hledger: + + *COLUMNS* This is normally set by your terminal; some hledger +commands ('register') will format their output to this width. If not +set, they will try to use the available terminal width. + + *LEDGER_FILE* The main journal file to use when not specified with +'-f/--file'. Default: '$HOME/.hledger.journal'. + + *NO_COLOR* If this environment variable is set (with any value), +hledger will not use ANSI color codes in terminal output, unless +overridden by an explicit '--color/--colour' option. + + +File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top + +8 PART 2: DATA FORMATS +********************** + + +File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top + +9 Journal +********* + +hledger's default file format, representing a General Journal. Here's a +cheatsheet/mini-tutorial, or you can skip ahead to About journal format. + +* Menu: + +* Journal cheatsheet:: +* About journal format:: +* Comments:: +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Transaction comments:: +* Postings:: +* Account names:: +* Amounts:: +* Costs:: +* Balance assertions:: +* Posting comments:: +* Tags:: +* Directives:: +* account directive:: +* alias directive:: +* commodity directive:: +* decimal-mark directive:: +* include directive:: +* P directive:: +* payee directive:: +* tag directive:: +* Periodic transactions:: +* Auto postings:: +* Other syntax:: + + +File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal + +9.1 Journal cheatsheet +====================== + +# Here is the main syntax of hledger's journal format +# (omitting extra Ledger compatibility syntax). +# hledger journals contain comments, directives, and transactions, in any order: + +############################################################################### +# 1. Comment lines are for notes or temporarily disabling things. +# They begin with #, ;, or a line containing the word "comment". + +# hash comment line +; semicolon comment line +comment +These lines +are commented. +end comment + +# Some but not all hledger entries can have same-line comments attached to them, +# from ; (semicolon) to end of line. + +############################################################################### +# 2. Directives modify parsing or reports in some way. +# They begin with a word or letter (or symbol). + +account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. +account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) +alias chkg = assets:checking +commodity $0.00 +decimal-mark . +include /dev/null +payee Whole Foods +P 2022-01-01 AAAA $1.40 +~ monthly budget goals ; <- 2+ spaces between period expression and description + expenses:food $400 + expenses:home $1000 + budgeted + +############################################################################### +# 3. Transactions are what it's all about; they are dated events, +# usually describing movements of money. +# They begin with a date. + +# DATE DESCRIPTION ; This is a transaction comment. +# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. +# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. +# ; ^^ At least 2 spaces between account and amount. +# ... ; Any number of postings is allowed. The amounts must balance (sum to 0). + +2022-01-01 opening balances are declared this way + assets:checking $1000 ; Account names can be anything. lower case is easy to type. + assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. + assets:cash:wallet $100 ; : indicates subaccounts. + liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. + equity ; One amount can be left blank; $-1900 is inferred here. + +2022-04-15 * (#12345) pay taxes + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a transaction code (text in parentheses) after the date/status. + ; Amounts' sign represents direction of flow, or credit/debit: + assets:checking $-500 ; minus means removed from this account (credit) + expenses:tax:us:2021 $500 ; plus means added to this account (debit) + ; revenue/expense categories are also "accounts" + +2022-01-01 ; The description is optional. + ; Any currency/commodity symbols are allowed, on either side. + assets:cash:wallet GBP -10 + expenses:clothing GBP 10 + assets:gringotts -10 gold + assets:pouch 10 gold + revenues:gifts -2 "Liquorice Wands" ; Complex symbols + assets:bag 2 "Liquorice Wands" ; must be double-quoted. + +2022-01-01 Cost in another commodity can be noted with @ or @@ + assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments 3.0 AAAA @@ $4 ; @@ means total cost + assets:checking $-7.00 + +2022-01-02 assert balances + ; Balances can be asserted for extra error checking, in any transaction. + assets:investments 0 AAAA = 5.0 AAAA + assets:pouch 0 gold = 10 gold + assets:savings $0 = $1000 + +1999-12-31 Ordering transactions by date is recommended but not required. + ; Postings are not required. + +2022.01.01 These date +2022/1/1 formats are +12/31 also allowed (but consistent YYYY-MM-DD is recommended). + + +File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal + +9.2 About journal format +======================== + +hledger's usual data source is a plain text file containing journal +entries in hledger journal format. This file represents a standard +accounting general journal. I use file names ending in '.journal', but +that's not required. The journal file contains a number of transaction +entries, each describing a transfer of money (or any commodity) between +two or more named accounts, in a simple format readable by both hledger +and humans. + + hledger's journal format is compatible with most of Ledger's journal +format, but not all of it. The differences and interoperation tips are +described at hledger and Ledger. With some care, and by avoiding +incompatible features, you can keep your hledger journal readable by +Ledger and vice versa. This can useful eg for comparing the behaviour +of one app against the other. + + You can use hledger without learning any more about this file; just +use the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and +track changes with a version control system such as git. Editor addons +such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and +hledger-vscode for Visual Studio Code, make this easier, adding colour, +formatting, tab completion, and useful commands. See Editor +configuration at hledger.org for the full list. + + Here's a description of each part of the file format (and hledger's +data model). + + A hledger journal file can contain three kinds of thing: file +comments, transactions, and/or directives (counting periodic transaction +rules and auto posting rules as directives). + + +File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal + +9.3 Comments +============ + +Lines in the journal will be ignored if they begin with a hash ('#') or +a semicolon (';'). (See also Other syntax.) hledger will also ignore +regions beginning with a 'comment' line and ending with an 'end comment' +line (or file end). Here's a suggestion for choosing between them: + + * '#' for top-level notes + * ';' for commenting out things temporarily + * 'comment' for quickly commenting large regions (remember it's + there, or you might get confused) + + Eg: + +# a comment line +; another commentline +comment +A multi-line comment block, +continuing until "end comment" directive +or the end of the current file. +end comment + + Some hledger entries can have same-line comments attached to them, +from ; (semicolon) to end of line. See Transaction comments, Posting +comments, and Account comments below. + + +File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal + +9.4 Transactions +================ + +Transactions are the main unit of information in a journal file. They +represent events, typically a movement of some quantity of commodities +between two or more named accounts. + + Each transaction is recorded as a journal entry, beginning with a +simple date in column 0. This can be followed by any of the following +optional fields, separated by spaces: + + * a status character (empty, '!', or '*') + * a code (any short number or text, enclosed in parentheses) + * a description (any remaining text until end of line or a semicolon) + * a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + * 0 or more indented _posting_ lines, describing what was transferred + and the accounts involved (indented comment lines are also allowed, + but not blank lines or non-indented lines). + + Here's a simple journal file containing one transaction: + +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + +File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal + +9.5 Dates +========= + +* Menu: + +* Simple dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates + +9.5.1 Simple dates +------------------ + +Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or +'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may +be omitted, in which case it will be inferred from the context: the +current transaction, the default year set with a 'Y' directive, or the +current date when the command is run. Some examples: '2010-01-31', +'2010/01/31', '2010.1.31', '1/31'. + + (The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.) + + +File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates + +9.5.2 Posting dates +------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like 'date:DATE'. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction's date. +The 'date:' tag must have a valid simple date value if it is present, eg +a 'date:' tag with no value is not allowed. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal + +9.6 Status +========== + +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +'!' pending +'*' cleared + + When reporting, you can filter by status with the '-U/--unmarked', +'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', +and 'status:*' queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" +state is called "uncleared". As of hledger 1.3 we have renamed it to +unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching +pending, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here's one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use '-PC' to see the current balance at +your bank, '-U' to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal + +9.7 Code +======== + +After the status mark, but before the description, you can optionally +write a transaction "code", enclosed in parentheses. This is a good +place to record a check number, or some other important transaction id +or reference number. + + +File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal + +9.8 Description +=============== + +A transaction's description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +9.8.1 Payee and note +-------------------- + +You can optionally include a '|' (pipe) character in descriptions to +subdivide the description into separate fields for payee/payer name on +the left (up to the first '|') and an additional note field on the right +(after the first '|'). This may be worthwhile if you need to do more +precise querying and pivoting by payee or by note. + + +File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal + +9.9 Transaction comments +======================== + +Text following ';', after a transaction description, and/or on indented +lines immediately below it, form comments for that transaction. They +are reproduced by 'print' but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal + +9.10 Postings +============= + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + * (optional) a status character (empty, '!', or '*'), followed by a + space + * (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + * (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, one amount may be left blank; it will be inferred so as to +balance the transaction. + + Be sure to note the unusual two-space delimiter between account name +and amount. This makes it easy to write account names containing +spaces. But if you accidentally leave only one space (or tab) before +the amount, the amount will be considered part of the account name. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal + +9.11 Account names +================== + +Accounts are the main way of categorising things in hledger. As in +Double Entry Bookkeeping, they can represent real world accounts (such +as a bank account), or more abstract categories such as "money borrowed +from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the +traditional accounting categories, which in english are 'assets', +'liabilities', 'equity', 'revenues', 'expenses'. (You might see these +referred to as A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts +into more detailed subaccounts, by writing a full colon between account +name parts. For example, from the account names 'assets:bank:checking' +and 'expenses:food', hledger will infer this hierarchy of five accounts: + +assets +assets:bank +assets:bank:checking +expenses +expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + +assets + bank + checking +expenses + food + + hledger reports can summarise the account tree to any depth, so you +can go as deep as you like with subcategories, but keeping your account +names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, +numbers, symbols, or single spaces. Note, when an account name and an +amount are written on the same line, they must be separated by *two or +more spaces* (or tabs). + + Parentheses or brackets enclosing the full account name indicate +virtual postings, described below. Parentheses or brackets internal to +the account name have no special meaning. + + Account names can be altered temporarily or permanently by account +aliases. + + +File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal + +9.12 Amounts +============ + +After the account name, there is usually an amount. (Important: between +account name and amount, there must be *two or more spaces*.) + + hledger's amount format is flexible, supporting several international +formats. Here are some examples. Amounts have a number (the +"quantity"): + +1 + + ..and usually a currency symbol or commodity name (more on this +below), to the left or right of the quantity, with or without a +separating space: + +$1 +4000 AAPL +3 "green apples" + + Amounts can be preceded by a minus sign (or a plus sign, though plus +is the default), The sign can be written before or after a left-side +commodity symbol: + +-$1 +$-1 + + One or more spaces between the sign and the number are acceptable +when parsing (but they won't be displayed in output): + ++ $1 +$- 1 + + Scientific E notation is allowed: + +1E-6 +EUR 1E3 + +* Menu: + +* Decimal marks digit group marks:: +* Commodity:: +* Directives influencing number parsing and display:: +* Commodity display style:: +* Rounding:: + + +File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts + +9.12.1 Decimal marks, digit group marks +--------------------------------------- + +A _decimal mark_ can be written as a period or a comma: + +1.23 +1,23 + + 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 + + hledger is not biased towards period or comma decimal marks, so a +number containing just one period or comma, like '1,000' or '1.000', is +ambiguous. In such cases hledger assumes it is a decimal mark, parsing +both of these as 1. + + To disambiguate these and ensure accurate number parsing, especially +if you use digit group marks, we recommend declaring the decimal mark. +You can declare it for each file with 'decimal-mark' directives, or for +each commodity with 'commodity' directives (described below). + + +File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts + +9.12.2 Commodity +---------------- + +Amounts in hledger have both a "quantity", which is a signed decimal +number, and a "commodity", which is a currency symbol, stock ticker, or +any word or phrase describing something you are tracking. + + If the commodity name contains non-letters (spaces, numbers, or +punctuation), you must always write it inside double quotes ('"green +apples"', '"ABC123"'). + + If you write just a bare number, that too will have a commodity, with +name '""'; we call that the "no-symbol commodity". + + Actually, hledger combines these single-commodity amounts into more +powerful multi-commodity amounts, which are what it works with most of +the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 +TSLA'. In practice, you will only see multi-commodity amounts in +hledger's output; you can't write them directly in the journal file. + + (If you are writing scripts or working with hledger's internals, +these are the 'Amount' and 'MixedAmount' types.) + + +File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts + +9.12.3 Directives influencing number parsing and display +-------------------------------------------------------- + +You can add 'decimal-mark' and 'commodity' directives to the journal, to +declare and control these things more explicitly and precisely. These +are described below, but here's a quick example: + +# the decimal mark character used by all amounts in this file (all commodities) +decimal-mark . + +# display styles for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 + + +File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts + +9.12.4 Commodity display style +------------------------------ + +For the amounts in each commodity, hledger chooses a consistent display +style (symbol placement, decimal mark and digit group marks, number of +decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a 'D' directive declaring a default commodity, that +commodity symbol and amount format is applied to all no-symbol amounts +in the journal. + + Then each commodity's display style is determined from its +'commodity' directive. We recommend always declaring commodities with +'commodity' directives, since they help ensure consistent display styles +and precisions, and bring other benefits such as error checking for +commodity symbols. + + But if a 'commodity' directive is not present, hledger infers a +commodity's display styles from its amounts as they are written in the +journal (excluding cost amounts and amounts in periodic transaction +rules or auto posting rules). It uses + + * the symbol placement and decimal mark of the first amount seen + * the digit group marks of the first amount with digit group marks + * and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a +default style, like '$1000.00' (symbol on the left with no space, period +as decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the +'-c/--commodity-style' command line option. + + +File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts + +9.12.5 Rounding +--------------- + +Amounts are stored internally as decimal numbers with up to 255 decimal +places. They are displayed with their original journal precisions by +print and print-like reports, and rounded to their display precision +(the number of decimal digits specified by the commodity display style) +by other reports. When rounding, hledger uses banker's rounding (it +rounds to the nearest even digit). So eg 0.5 displayed with zero +decimal digits appears as "0". + + +File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal + +9.13 Costs +========== + +After a posting amount, you can note its cost (when buying) or selling +price (when selling) in another commodity, by writing either '@ +UNITPRICE' or '@@ TOTALPRICE' after it. This indicates a conversion +transaction, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, +discussions, or code; that term was directionally neutral and reminded +that it is a price specific to a transaction, but we now just call it +"cost", with the understanding that the transaction could be a purchase +or a sale.) + + Costs are usually written explicitly with '@' or '@@', but can also +be inferred automatically for simple multi-commodity transactions. +Note, if costs are inferred, the order of postings is significant; the +first posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign +currency in hledger, using the cost notation either explicitly or +implicitly: + + 1. Write the price per unit, as '@ UNITPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as '@@ TOTALPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction. + Note the effect of posting order: the price is added to first + posting, making it '€100 @@ $135', as in example 2: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the '-B/--cost' +flag; this is discussed more in the Cost reporting section. + + Note that the cost normally should be a positive amount, though it's +not required to be. This can be a little confusing, see discussion at +-infer-market-prices: market prices from transactions. + +* Menu: + +* Other cost/lot notations:: + + +File: hledger.info, Node: Other cost/lot notations, Up: Costs + +9.13.1 Other cost/lot notations +------------------------------- + +A slight digression for Ledger and Beancount users. Ledger has a number +of cost/lot-related notations: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a conversion rate, as in hledger + * when buying, also creates a lot than can be selected at + selling time + + * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) + * like the above, but also means "this cost was exceptional, + don't use it when inferring market prices". + + Currently, hledger treats the above like '@' and '@@'; the +parentheses are ignored. + + * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) + * when buying, means "this cost is also the fixed price, don't + let it fluctuate in value reports" + + * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) + * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', + also creates a lot + * when selling, combined with '@ ...', specifies an investment + lot by its cost basis; does not check if that lot is present + + * and related: '[YYYY/MM/DD]' (lot date) + * when buying, attaches this acquisition date to the lot + * when selling, selects a lot by its acquisition date + + * '(SOME TEXT)' (lot note) + * when buying, attaches this note to the lot + * when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after +the posting amount, but ignores them. (This can break transaction +balancing.) + + For Beancount users, the notation and behaviour is different: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a cost without creating a lot, as in hledger + * when buying (augmenting) or selling (reducing) a lot, combined + with '{...}': documents the cost/selling price (not used for + transaction balancing) + + * '{UNITCOST}' and '{{TOTALCOST}}' + * when buying (augmenting), expresses the cost for transaction + balancing, and also creates a lot with this cost basis + attached + * when selling (reducing), + * selects a lot by its cost basis + * raises an error if that lot is not present or can not be + selected unambiguously (depending on booking method + configured) + * expresses the selling price for transaction balancing + + Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation +but ignores it. + + * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, + "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. + + Currently, hledger rejects these. + + +File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal + +9.14 Balance assertions +======================= + +hledger supports Ledger-style balance assertions in journal files. +These look like, for example, '= EXPECTEDBALANCE' following a posting's +amount. Eg here we assert the expected dollar balance in accounts a and +b after each posting: + +2013/1/1 + a $1 =$1 + b =$-1 + +2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the '-I/--ignore-assertions' flag, which can be useful for +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, described below). + +* Menu: + +* Assertions and ordering:: +* Assertions and multiple included files:: +* Assertions and multiple -f files:: +* Assertions and commodities:: +* Assertions and prices:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: +* Assertions and auto postings:: +* Assertions and precision:: + + +File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions + +9.14.1 Assertions and ordering +------------------------------ + +hledger sorts an account's postings and assertions first by date and +then (for postings on the same day) by parse order. Note this is +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder +differently-dated transactions within the journal. But if you reorder +same-dated transactions or postings, assertions might break and require +updating. This order dependence does bring an advantage: precise +control over the order of postings and assertions within a day, so you +can assert intra-day balances. + + +File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions + +9.14.2 Assertions and multiple included files +--------------------------------------------- + +Multiple files included with the 'include' directive are processed as if +concatenated into one file, preserving their order and the posting order +within each file. It means that balance assertions in later files will +see balance from earlier files. + + And if you have multiple postings to an account on the same day, +split across multiple files, and you want to assert the account's +balance on that day, you'll need to put the assertion in the right file +- the last one in the sequence, probably. + + +File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions + +9.14.3 Assertions and multiple -f files +--------------------------------------- + +Unlike 'include', when multiple files are specified on the command line +with multiple '-f/--file' options, balance assertions will not see +balance from earlier files. This can be useful when you do not want +problems in earlier files to disrupt valid assertions in later files. + + If you do want assertions to see balance from earlier files, use +'include', or concatenate the files temporarily. + + +File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions + +9.14.4 Assertions and commodities +--------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity's balance within the +(possibly multi-commodity) account balance. This is how assertions work +in Ledger also. We could call this a "partial" balance assertion. + + To assert the balance of more than one commodity in an account, you +can write multiple postings, each asserting one commodity's balance. + + You can make a stronger "total" balance assertion by writing a double +equals sign ('== EXPECTEDBALANCE'). This asserts that there are no +other commodities in the account besides the asserted one (or at least, +that their balance is 0). + +2013/1/1 + a $1 + a 1€ + b $-1 + c -1€ + +2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1€ + b 0 == $-1 + c 0 == -1€ + +2013/1/3 ; This assertion fails as 'a' also contains 1€ + a 0 == $1 + + It's not yet possible to make a complete assertion about a balance +that has multiple commodities. One workaround is to isolate each +commodity into its own subaccount: + +2013/1/1 + a:usd $1 + a:euro 1€ + b + +2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1€ + + +File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions + +9.14.5 Assertions and prices +---------------------------- + +Balance assertions ignore costs, and should normally be written without +one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below). + + +File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions + +9.14.6 Assertions and subaccounts +--------------------------------- + +The balance assertions above ('=' and '==') do not count the balance +from subaccounts; they check the account's exclusive balance only. You +can assert the balance including subaccounts by writing '=*' or '==*', +eg: + +2019/1/1 + equity:opening balances + checking:a 5 + checking:b 5 + checking 1 ==* 11 + + +File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions + +9.14.7 Assertions and virtual postings +-------------------------------------- + +Balance assertions always consider both real and virtual postings; they +are not affected by the '--real/-R' flag or 'real:' query. + + +File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions + +9.14.8 Assertions and auto postings +----------------------------------- + +Balance assertions _are_ affected by the '--auto' flag, which generates +auto postings, which can alter account balances. Because auto postings +are optional in hledger, accounts affected by them effectively have two +balances. But balance assertions can only test one or the other of +these. So to avoid making fragile assertions, either: + + * assert the balance calculated with '--auto', and always use + '--auto' with that file + * or assert the balance calculated without '--auto', and never use + '--auto' with that file + * or avoid balance assertions on accounts affected by auto postings + (or avoid auto postings entirely). + + +File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions + +9.14.9 Assertions and precision +------------------------------- + +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. Eg a commodity directive may limit the +display precision, but this will not affect balance assertions. Balance +assertion failure messages show exact amounts. + + +File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal + +9.15 Posting comments +===================== + +Text following ';', at the end of a posting line, and/or on indented +lines immediately below it, form comments for that posting. They are +reproduced by 'print' but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + +File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal + +9.16 Tags +========= + +Tags are a way to add extra labels or labelled data to transactions, +postings, or accounts, which you can then search or pivot on. + + They are written as a word (optionally hyphenated) immediately +followed by a full colon, in a transaction or posting or account +directive's comment. (This is an exception to the usual rule that +things in comments are ignored.) Eg, here four different tags are +recorded: one on the checking account, two on the transaction, and one +on the expenses posting: + +account assets:checking ; accounttag: + +2017/1/16 bought groceries ; transactiontag-1: + ; transactiontag-2: + assets:checking $-1 + expenses:food $1 ; postingtag: + + Postings also inherit tags from their transaction and their account. +And transactions also acquire tags from their postings (and postings' +accounts). So in the example above, the expenses posting effectively +has all four tags (by inheriting from account and transaction), and the +transaction also has all four tags (by acquiring from the expenses +posting). + + You can list tag names with 'hledger tags [NAMEREGEX]', or match by +tag name with a 'tag:NAMEREGEX' query. + +* Menu: + +* Tag values:: + + +File: hledger.info, Node: Tag values, Up: Tags + +9.16.1 Tag values +----------------- + +Tags can have a value, which is any text after the colon up until a +comma or end of line (with surrounding whitespace removed). Note this +means that hledger tag values can not contain commas. Eg in the +following posting, the three tags' values are "value 1", "value 2", and +"" (empty) respectively: + + expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz + + Note that tags can be repeated, and are additive rather than +overriding: when the same tag name is seen again with a new value, the +new name:value pair is added to the tags. (It is not possible to +override a tag's value or remove a tag.) + + You can list a tag's values with 'hledger tags TAGNAME --values', or +match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query. + + +File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal + +9.17 Directives +=============== + +Besides transactions, there is something else you can put in a 'journal' +file: directives. These are declarations, beginning with a keyword, +that modify hledger's behaviour. Some directives can have more specific +subdirectives, indented below them. hledger's directives are similar to +Ledger's in many cases, but there are also many differences. Directives +are not required, but can be useful. Here are the main directives: + +purpose directive +-------------------------------------------------------------------------- +*READING DATA:* +Rewrite account names 'alias' +Comment out sections of the file 'comment' +Declare file's decimal mark, to help 'decimal-mark' +parse amounts accurately +Include other data files 'include' +*GENERATING DATA:* +Generate recurring transactions or '~' +budget goals +Generate extra postings on existing '=' +transactions +*CHECKING FOR ERRORS:* +Define valid entities to provide more 'account', 'commodity', +error checking 'payee', 'tag' +*REPORTING:* +Declare accounts' type and display 'account' +order +Declare commodity display styles 'commodity' +Declare market prices 'P' + +* Menu: + +* Directives and multiple files:: +* Directive effects:: + + +File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives + +9.17.1 Directives and multiple files +------------------------------------ + +Directives vary in their scope, ie which journal entries and which input +files they affect. Most often, a directive will affect the following +entries and included files if any, until the end of the current file - +and no further. You might find this inconvenient! For example, 'alias' +directives do not affect parent or sibling files. But there are usually +workarounds; for example, put 'alias' directives in your top-most file, +before including other files. + + The restriction, though it may be annoying at first, is in a good +cause; it allows reports to be stable and deterministic, independent of +the order of input. Without it, reports could show different numbers +depending on the order of -f options, or the positions of include +directives in your files. + + +File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives + +9.17.2 Directive effects +------------------------ + +Here are all hledger's directives, with their effects and scope +summarised - nine main directives, plus four others which we consider +non-essential: + +directivewhat it does ends + at + file + end? +--------------------------------------------------------------------------- +*'account'*Declares an account, for checking all entries in all files; andN + its display order and type. Subdirectives: any text, ignored. +*'alias'*Rewrites account names, in following entries until end of Y + current file or 'end aliases'. Command line equivalent: + '--alias' +*'comment'*Ignores part of the journal file, until end of current file orY + 'end comment'. +*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N + all amounts in all files 2. the decimal mark for parsing + amounts of this commodity, in the following entries until end of + current file (if there is no 'decimal-mark' directive) 3. and + the display style for amounts of this commodity 4. which is + also the precision to use for balanced-transaction checking in + this commodity. Takes precedence over 'D'. Subdirectives: + 'format' (Ledger-compatible syntax). Command line equivalent: + '-c/--commodity-style' +*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y + commodities in following entries until next 'decimal-mark' or + end of current file. Included files can override. Takes + precedence over 'commodity' and 'D'. +*'include'*Includes entries and directives from another file, as if theyN + were written inline. Command line alternative: multiple + '-f/--file' +*'payee'*Declares a payee name, for checking all entries in all files. N +*'P'*Declares the market price of a commodity on some date, for value N + reports. +*'~'*Declares a periodic transaction rule that generates future N +(tilde)transactions with '--forecast' and budget goals with 'balance + --budget'. +Other +syntax: +*'applyPrepends a common parent account to all account names, in Y +account'*following entries until end of current file or 'end apply + account'. +*'D'*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no 'commodity' directive for this commodity: its + decimal mark, balancing precision, and display style, as above. +*'Y'*Sets a default year to use for any yearless dates, in following Y + entries until end of current file. +*'='*Declares an auto posting rule that generates extra postings on partly +(equals)matched transactions with '--auto', in current, parent, and + child files (but not sibling files, see #1212). +*OtherOther directives from Ledger's file format are accepted but +Ledgerignored. +directives* + + +File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal + +9.18 'account' directive +======================== + +'account' directives can be used to declare accounts (ie, the places +that amounts are transferred from and to). Though not required, these +declarations can provide several benefits: + + * They can document your intended chart of accounts, providing a + reference. + * In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + * They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + * They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + * They can store additional account information as comments, or as + tags which can be used to filter or pivot reports. + * They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), affecting reports like balancesheet and + incomestatement. + + They are written as the word 'account' followed by a hledger-style +account name, eg: + +account assets:bank:checking + + Note, however, that accounts declared in account directives are not +allowed to have surrounding brackets and parentheses, unlike accounts +used in postings. So the following journal will not parse: + +account (assets:bank:checking) + +* Menu: + +* Account comments:: +* Account subdirectives:: +* Account error checking:: +* Account display order:: +* Account types:: + + +File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive + +9.18.1 Account comments +----------------------- + +Text following *two or more spaces* and ';' at the end of an account +directive line, and/or following ';' on indented lines immediately below +it, form comments for that account. They are ignored except they may +contain tags, which are not ignored. + + The two-space requirement for same-line account comments is because +';' is allowed in account names. + +account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + +File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive + +9.18.2 Account subdirectives +---------------------------- + +Ledger-style indented subdirectives are also accepted, but currently +ignored: + +account assets:bank:checking + format subdirective is ignored + + +File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive + +9.18.3 Account error checking +----------------------------- + +By default, accounts need not be declared; they come into existence when +a posting references them. This is convenient, but it means hledger +can't warn you when you mis-spell an account name in the journal. +Usually you'll find that error later, as an extra account in balance +reports, or an incorrect balance when reconciling. + + In strict mode, enabled with the '-s'/'--strict' flag, hledger will +report an error if any transaction uses an account name that has not +been declared by an account directive. Some notes: + + * The declaration is case-sensitive; transactions must use the + correct account name capitalisation. + * The account directive's scope is "whole file and below" (see + directives). This means it affects all of the current file, and + any files it includes, but not parent or sibling files. The + position of account directives within the file does not matter, + though it's usual to put them at the top. + * Accounts can only be declared in 'journal' files, but will affect + included files of all types. + * It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + +File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive + +9.18.4 Account display order +---------------------------- + +The order in which account directives are written influences the order +in which accounts appear in reports, hledger-ui, hledger-web etc. By +default accounts appear in alphabetical order, but if you add these +account directives to the journal file: + +account assets +account liabilities +account equity +account revenues +account expenses + + those accounts will be displayed in declaration order: + +$ hledger accounts -1 +assets +liabilities +equity +revenues +expenses + + Any undeclared accounts are displayed last, in alphabetical order. + + Sorting is done at each level of the account tree, within each group +of sibling accounts under the same parent. And currently, this +directive: + +account other:zoo + + would influence the position of 'zoo' among 'other''s subaccounts, +but not the position of 'other' among the top-level accounts. This +means: + + * you will sometimes declare parent accounts (eg 'account other' + above) that you don't intend to post to, just to customize their + display order + * sibling accounts stay together (you couldn't display 'x:y' in + between 'a:b' and 'a:c'). + + +File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive + +9.18.5 Account types +-------------------- + +hledger knows that accounts come in several types: assets, liabilities, +expenses and so on. This enables easy reports like balancesheet and +incomestatement, and filtering by account type with the 'type:' query. + + As a convenience, hledger will detect these account types +automatically if you are using common english-language top-level account +names (described below). But generally we recommend you declare types +explicitly, by adding a 'type:' tag to your top-level account +directives. Subaccounts will inherit the type of their parent. The +tag's value should be one of the five main account types: + + * 'A' or 'Asset' (things you own) + * 'L' or 'Liability' (things you owe) + * 'E' or 'Equity' (investment/ownership; balanced counterpart of + assets & liabilities) + * 'R' or 'Revenue' (what you received money from, AKA income; + technically part of Equity) + * 'X' or 'Expense' (what you spend money on; technically part of + Equity) + + or, it can be (these are used less often): + + * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the + cashflow report) + * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost + reporting).) + + Here is a typical set of account type declarations: + +account assets ; type: A +account liabilities ; type: L +account equity ; type: E +account revenues ; type: R +account expenses ; type: X + +account assets:bank ; type: C +account assets:cash ; type: C + +account equity:conversion ; type: V + + Here are some tips for working with account types. + + * The rules for inferring types from account names are as follows. + These are just a convenience that sometimes help new users get + going; if they don't work for you, just ignore them and declare + your account types. See also Regular expressions. + + If account's name contains this (CI) regular expression: | its type is: + --------------------------------------------------------------------|------------- + ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash + ^assets?(:|$) | Asset + ^(debts?|liabilit(y|ies))(:|$) | Liability + ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion + ^equity(:|$) | Equity + ^(income|revenue)s?(:|$) | Revenue + ^expenses?(:|$) | Expense + + * If you declare any account types, it's a good idea to declare an + account for all of the account types, because a mixture of declared + and name-inferred types can disrupt certain reports. + + * Certain uses of account aliases can disrupt account types. See + Rewriting accounts > Aliases and account types. + + * As mentioned above, subaccounts will inherit a type from their + parent account. More precisely, an account's type is decided by + the first of these that exists: + + 1. A 'type:' declaration for this account. + 2. A 'type:' declaration in the parent accounts above it, + preferring the nearest. + 3. An account type inferred from this account's name. + 4. An account type inferred from a parent account's name, + preferring the nearest parent. + 5. Otherwise, it will have no type. + + * For troubleshooting, you can list accounts and their types with: + + $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] + + +File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal + +9.19 'alias' directive +====================== + +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. This can be useful for: + + * expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + * adapting old journals to your current chart of accounts + * experimenting with new account organisations, like a new hierarchy + * combining two accounts into one, eg to see their sum or difference + on one line + * customising reports + + Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger-web. + + Account aliases are very powerful. They are generally easy to use +correctly, but you can also generate invalid account names with them; +more on this below. + + See also Rewrite account names. + +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Combining aliases:: +* Aliases and multiple files:: +* end aliases directive:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive + +9.19.1 Basic aliases +-------------------- + +To set an account alias, use the 'alias' directive in your journal file. +This affects all subsequent journal entries in the current file or its +included files (but note: not sibling or parent files). The spaces +around the = are optional: + +alias OLD = NEW + + Or, you can use the '--alias 'OLD=NEW'' option on the command line. +This affects all entries. It's useful for trying out aliases +interactively. + + OLD and NEW are case sensitive full account names. hledger will +replace any occurrence of the old account name with the new one. +Subaccounts are also affected. Eg: + +alias checking = assets:bank:wells fargo:checking +; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + +File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive + +9.19.2 Regex aliases +-------------------- + +There is also a more powerful variant that uses a regular expression, +indicated by wrapping the pattern in forward slashes. (This is the only +place where hledger requires forward slashes around a regular +expression.) + + Eg: + +alias /REGEX/ = REPLACEMENT + + or: + +$ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by +REPLACEMENT. REGEX is case-insensitive as usual. + + If you need to match a forward slash, escape it with a backslash, eg +'/\/=:'. + + If REGEX contains parenthesised match groups, these can be referenced +by the usual backslash and number in REPLACEMENT: + +alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 +; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + REPLACEMENT continues to the end of line (or on command line, to end +of option argument), so it can contain trailing whitespace. + + +File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive + +9.19.3 Combining aliases +------------------------ + +You can define as many aliases as you like, using journal directives +and/or command line options. + + Recursive aliases - where an account name is rewritten by one alias, +then by another alias, and so on - are allowed. Each alias sees the +effect of previously applied aliases. + + In such cases it can be important to understand which aliases will be +applied and in which order. For (each account name in) each journal +entry, we apply: + + 1. 'alias' directives preceding the journal entry, most recently + parsed first (ie, reading upward from the journal entry, bottom to + top) + 2. '--alias' options, in the order they appeared on the command line + (left to right). + + In other words, for (an account name in) a given journal entry: + + * the nearest alias declaration before/above the entry is applied + first + * the next alias before/above that will be be applied next, and so on + * aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps +provide semantic stability - aliases will keep working the same way +independent of which files are being read and in which order. + + In case of trouble, adding '--debug=6' to the command line will show +which aliases are being applied when. + + +File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive + +9.19.4 Aliases and multiple files +--------------------------------- + +As explained at Directives and multiple files, 'alias' directives do not +affect parent or sibling files. Eg in this command, + +hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn't work either: + +include a.aliases + +2023-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 + +2023-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected + + +File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive + +9.19.5 'end aliases' directive +------------------------------ + +You can clear (forget) all currently defined aliases (seen in the +journal so far, or defined on the command line) with this directive: + +end aliases + + +File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive + +9.19.6 Aliases can generate bad account names +--------------------------------------------- + +Be aware that account aliases can produce malformed account names, which +could cause confusing reports or invalid 'print' output. For example, +you could erase all account names: + +2021-01-01 + a:aa 1 + b + +$ hledger print --alias '/.*/=' +2021-01-01 + 1 + + The above 'print' output is not a valid journal. Or you could insert +an illegal double space, causing 'print' output that would give a +different journal when reparsed: + +2021-01-01 + old 1 + other + +$ hledger print --alias old="new USD" | hledger -f- print +2021-01-01 + new USD 1 + other + + +File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive + +9.19.7 Aliases and account types +-------------------------------- + +If an account with a type declaration (see Declaring accounts > Account +types) is renamed by an alias, normally the account type remains in +effect. + + However, renaming in a way that reshapes the account tree (eg +renaming parent accounts but not their children, or vice versa) could +prevent child accounts from inheriting the account type of their +parents. + + Secondly, if an account's type is being inferred from its name, +renaming it by an alias could prevent or alter that. + + If you are using account aliases and the 'type:' query is not +matching accounts as you expect, try troubleshooting with the accounts +command, eg something like: + +$ hledger accounts --alias assets=bassetts type:a + + +File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal + +9.20 'commodity' directive +========================== + +The 'commodity' directive performs several functions: + + 1. It declares which commodity symbols may be used in the journal, + enabling useful error checking with strict mode or the check + command. (See Commodity error checking below.) + + 2. It declares the precision with which this commodity's amounts + should be compared when checking for balanced transactions. + + 3. It declares how this commodity's amounts should be displayed, eg + their symbol placement, digit group mark if any, digit group sizes, + decimal mark (period or comma), and the number of decimal places. + (See Commodity display style above.) + + 4. It sets which decimal mark (period or comma) to expect when parsing + subsequent amounts in this commodity (if there is no 'decimal-mark' + directive in effect. See Decimal marks, digit group marks above. + For related dev discussion, see #793.) + + Declaring commodities solves several common parsing/display problems, +so we recommend it. Generally you should put 'commodity' directives at +the top of your journal file (because function 4 is position-sensitive). + +* Menu: + +* Commodity directive syntax:: +* Commodity error checking:: + + +File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive + +9.20.1 Commodity directive syntax +--------------------------------- + +A commodity directive is normally the word 'commodity' followed by a +sample amount (and optionally a comment). Only the amount's symbol and +format is significant. Eg: + +commodity $1000.00 +commodity 1.000,00 EUR +commodity 1 000 000.0000 ; the no-symbol commodity + + Commodities do not have tags (tags in the comment will be ignored). + + A commodity directive's sample amount must always include a period or +comma decimal mark (this rule helps disambiguate decimal marks and digit +group marks). If you don't want to show any decimal digits, write the +decimal mark at the end: + +commodity 1000. AAAA ; show AAAA with no decimals + + Commodity symbols containing spaces, numbers, or punctuation must be +enclosed in double quotes, as usual: + +commodity 1.0000 "AAAA 2023" + + Commodity directives normally include a sample amount, but can +declare only a symbol (ie, just function 1 above): + +commodity $ +commodity INR +commodity "AAAA 2023" +commodity "" ; the no-symbol commodity + + Commodity directives may also be written with an indented 'format' +subdirective, as in Ledger. The symbol is repeated and must be the same +in both places. Other subdirectives are currently ignored: + +; 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 + an unsupported subdirective ; ignored by hledger + + +File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive + +9.20.2 Commodity error checking +------------------------------- + +In strict mode ('-s'/'--strict') (or when you run 'hledger check +commodities'), hledger will report an error if an undeclared commodity +symbol is used. (With one exception: zero amounts are always allowed to +have no commodity symbol.) It works like account error checking +(described above). + + +File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal + +9.21 'decimal-mark' directive +============================= + +You can use a 'decimal-mark' directive - usually one per file, at the +top of the file - to declare which character represents a decimal mark +when parsing amounts in this file. It can look like + +decimal-mark . + + or + +decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we +recommend it, especially if the file contains digit group marks (eg +thousands separators). + + +File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal + +9.22 'include' directive +======================== + +You can pull in the content of additional files by writing an include +directive, like this: + +include FILEPATH + + Only journal files can include, and only journal, timeclock or +timedot files can be included (not CSV files, currently). + + If the file path does not begin with a slash, it is relative to the +current file's folder. + + A tilde means home directory, eg: 'include ~/main.journal'. + + The path may contain glob patterns to match multiple files, eg: +'include *.journal'. + + There is limited support for recursive wildcards: '**/' (the slash is +required) matches 0 or more subdirectories. It's not super convenient +since you have to avoid include cycles and including directories, but +this can be done, eg: 'include */**/*.journal'. + + The path may also be prefixed to force a specific file format, +overriding the file extension (as described in Data formats): 'include +timedot:~/notes/2023*.md'. + + +File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal + +9.23 'P' directive +================== + +The 'P' directive declares a market price, which is a conversion rate +between two commodities on a certain date. This allows value reports to +convert amounts of one commodity to their value in another, on or after +that date. These prices are often obtained from a stock exchange, +cryptocurrency exchange, the or foreign exchange market. + + The format is: + +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the +commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and +quantity) of commodity 2 that one unit of commodity 1 is worth on this +date. Examples: + +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 € $1.35 + +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 € $1.40 + + The '-V', '-X' and '--value' flags use these market prices to show +amount values in another commodity. See Value reporting. + + +File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal + +9.24 'payee' directive +====================== + +'payee PAYEE NAME' + + This directive can be used to declare a limited set of payees which +may appear in transaction descriptions. The "payees" check will report +an error if any transaction refers to a payee that has not been +declared. Eg: + +payee Whole Foods ; a comment + + Payees do not have tags (tags in the comment will be ignored). + + To declare the empty payee name, use '""'. + +payee "" + + Ledger-style indented subdirectives, if any, are currently ignored. + + +File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal + +9.25 'tag' directive +==================== + +'tag TAGNAME' + + This directive can be used to declare a limited set of tag names +allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + +tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is +used. It is quite easy to accidentally create a tag through normal use +of colons in comments(#comments]; if you want to prevent this, you can +declare and check your tags . + + +File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal + +9.26 Periodic transactions +========================== + +The '~' directive declares recurring transactions. Such directives +allow hledger to generate temporary future transactions (visible in +reports, not in the journal file) to help with forecasting or budgeting. + + Periodic transactions can be a little tricky, so before you use them, +read this whole section, or at least these tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + 2. For troubleshooting, show the generated transactions with 'hledger + print --forecast tag:generated' or 'hledger register --forecast + tag:generated'. + 3. Forecasted transactions will begin only after the last + non-forecasted transaction's date. + 4. Forecasted transactions will end 6 months from today, by default. + See below for the exact start/end rules. + 5. period expressions can be tricky. Their documentation needs + improvement, but is worth studying. + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in 'weekly from DATE', DATE + must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give + an error. + 7. Other period expressions with an interval are automatically + expanded to cover a whole number of that interval. (This is done + to improve reports, but it also affects periodic transactions. + Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th + day of month from 2023/01', which is equivalent to '~ every 10th + day of month from 2023/01/01', will be adjusted to start on + 2019/12/10. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +9.26.1 Periodic rule syntax +--------------------------- + +A periodic transaction rule looks like a normal journal entry, with the +date replaced by a tilde ('~') followed by a period expression +(mnemonic: '~' looks like a recurring sine wave.): + +# every first of month +~ monthly + expenses:rent $2000 + assets:bank:checking + +# every 15th of month in 2023's first quarter: +~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying +multi-period reports, just interpreted differently; there, it specifies +report periods; here it specifies recurrence dates (the periods' start +dates). + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +9.26.2 Periodic rules and relative dates +---------------------------------------- + +Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', +'next quarter') are usually not recommended in periodic rules, since the +results will change as time passes. If used, they will be interpreted +relative to, in order of preference: + + 1. the first day of the default year specified by a recent 'Y' + directive + 2. or the date specified with '--today' + 3. or the date on which you are running the report. + + They will not be affected at all by report period or forecast period +dates. + + +File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions + +9.26.3 Two spaces between period expression and description! +------------------------------------------------------------ + +If the period expression is followed by a transaction description, these +must be separated by *two or more spaces*. This helps hledger know +where the period expression ends, so that descriptions can not +accidentally alter their meaning, as in this example: + +; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" +; || +; vv +~ every 2 months in 2023, 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: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal + +9.27 Auto postings +================== + +The '=' directive declares a rule for generating temporary extra +postings on transactions. Wherever the rule matches an existing +posting, it can add one or more companion postings below that one, +optionally influenced by the matched posting's amount. This can be +useful for generating tax postings with a standard percentage, for +example. + + Note that depending on generated data is not ideal for financial +records (it's less portable, less future-proof, less auditable by +others, and less robust, since other features like balance assertions +will depend on using or not using '--auto'). + + 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:: + + +File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings + +9.27.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). + +* Menu: + +* Auto postings and dates:: +* Auto postings and transaction balancing / inferred amounts / balance assertions:: +* Auto posting tags:: +* Auto postings on forecast transactions only:: + + +File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files + +9.27.1.1 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 and multiple files + +9.27.1.2 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, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files + +9.27.1.3 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: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files + +9.27.1.4 Auto postings on forecast transactions only +.................................................... + +Tip: you can can make auto postings that will apply to forecast +transactions but not recorded transactions, by adding +'tag:_generated-transaction' to their QUERY. This can be useful when +generating new journal entries to be saved in the journal. + + +File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal + +9.28 Other syntax +================= + +hledger journal format supports quite a few other features, mainly to +make interoperating with or converting from Ledger easier. Note some of +the features below are powerful and can be useful in special cases, but +in general, features in this section are considered less important or +even not recommended for most users. Downsides are mentioned to help +you decide if you want to use them. + +* Menu: + +* Balance assignments:: +* Bracketed posting dates:: +* D directive:: +* apply account directive:: +* Y directive:: +* Secondary dates:: +* Star comments:: +* Valuation expressions:: +* Virtual postings:: +* Other Ledger directives:: + + +File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax + +9.28.1 Balance assignments +-------------------------- + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). + + Downsides: using balance assignments makes your journal less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. Also balance +assignments' forcing of balances can hide errors. These things make +your financial data less portable, less future-proof, and less +trustworthy in an audit. + +* Menu: + +* Balance assignments and prices:: +* Balance assignments and multiple files:: + + +File: hledger.info, Node: Balance assignments and prices, Next: Balance assignments and multiple files, Up: Balance assignments + +9.28.1.1 Balance assignments and prices +....................................... + +A cost in a balance assignment will cause the calculated amount to have +that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019-01-01 + (a) $1 @ €2 = $1 @ €2 + + +File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and prices, Up: Balance assignments + +9.28.1.2 Balance assignments and multiple files +............................................... + +Balance assignments handle multiple files like balance assertions. They +see balance from other files previously included from the current file, +but not from previous sibling or parent files. + + +File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax + +9.28.2 Bracketed posting dates +------------------------------ + +For setting posting dates and secondary posting dates, Ledger's +bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or +'[=DATE2]' in posting comments. hledger will attempt to parse any +square-bracketed sequence of the '0123456789/-.=' characters in this +way. With this syntax, DATE infers its year from the transaction and +DATE2 infers its year from DATE. + + Downsides: another syntax to learn, redundant with hledger's +'date:'/'date2:' tags, and confusingly similar to Ledger's lot date +syntax. + + +File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax + +9.28.3 'D' directive +-------------------- + +'D AMOUNT' + + This directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. This effect lasts until the next 'D' directive, or the end +of the journal. + + For compatibility/historical reasons, 'D' also acts like a +'commodity' directive (setting the commodity's decimal mark for parsing +and display style for output). So its argument is not just a commodity +symbol, but a full amount demonstrating the style. The amount must +include a decimal mark (either period or comma). Eg: + +; commodity-less amounts should be treated as dollars +; (and displayed with the dollar sign on the left, thousands separators and two decimal places) +D $1,000.00 + +1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity's display style, a 'commodity' directive has +highest priority, then a 'D' directive. + + For detecting a commodity's decimal mark during parsing, +'decimal-mark' has highest priority, then 'commodity', then 'D'. + + For checking commodity symbols with the check command, a 'commodity' +directive is required ('hledger check commodities' ignores 'D' +directives). + + Downsides: omitting commodity symbols makes your financial data less +explicit, less portable, and less trustworthy in an audit. It is +usually an unsustainable shortcut; sooner or later you will want to +track multiple commodities. D is overloaded with functions redundant +with 'commodity' and 'decimal-mark'. And it works differently from +Ledger's 'D'. + + +File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax + +9.28.4 'apply account' directive +-------------------------------- + +This directive sets a default parent account, which will be prepended to +all accounts in following entries, until an 'end apply account' +directive or end of current file. Eg: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + 'account' directives are also affected, and so is any 'include'd +content. + + Account names entered via hledger add or hledger-web are not +affected. + + Account aliases, if any, are applied after the parent account is +prepended. + + Downsides: this can make your financial data less explicit, less +portable, and less trustworthy in an audit. + + +File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax + +9.28.5 'Y' directive +-------------------- + +'Y YEAR' + + or (deprecated backward-compatible forms): + + 'year YEAR' 'apply year YEAR' + + The space is optional. This sets a default year to be used for +subsequent dates which don't specify a year. Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +year 2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at +least) makes your financial data less explicit, less portable, and less +trustworthy in an audit. Such dates can get separated from their +corresponding Y directive, eg when evaluating a region of the journal in +your editor. A missing Y directive makes reports dependent on today's +date. + + +File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax + +9.28.6 Secondary dates +---------------------- + +A secondary date is written after the primary date, following an equals +sign. If the year is omitted, the primary date's year is assumed. When +running reports, the primary (left) date is used by default, but with +the '--date2' flag (or '--aux-date' or '--effective'), the secondary +(right) date will be used instead. + + The meaning of secondary dates is up to you, but it's best to follow +a consistent rule. Eg "primary = the bank's clearing date, secondary = +date the transaction was initiated, if different". + + Downsides: makes your financial data more complicated, less portable, +and less trustworthy in an audit. Keeping the meaning of the two dates +consistent requires discipline, and you have to remember which reporting +mode is appropriate for a given report. Posting dates are simpler and +better. + + +File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax + +9.28.7 Star comments +-------------------- + +Lines beginning with '*' (star/asterisk) are also comment lines. This +feature allows Emacs users to insert org headings in their journal, +allowing them to fold/unfold/navigate it like an outline when viewed +with org mode. + + Downsides: another, unconventional comment syntax to learn. +Decreases your journal's portability. And switching to Emacs org mode +just for folding/unfolding meant losing the benefits of ledger mode; +nowadays you can add outshine mode to ledger mode to get folding without +losing ledger mode's features. + + +File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax + +9.28.8 Valuation expressions +---------------------------- + +Ledger allows a valuation function or value to be written in double +parentheses after an amount. hledger ignores these. + + +File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax + +9.28.9 Virtual postings +----------------------- + +A posting with parentheses around the account name ('(some:account)') is +called a _unbalanced virtual posting_. Such postings do not participate +in transaction balancing. (And if you write them without an amount, a +zero amount is always inferred.) These can occasionally be convenient +for special circumstances, but they violate double entry bookkeeping and +make your data less portable across applications, so many people avoid +using them at all. + + A posting with brackets around the account name ('[some:account]') is +called a _balanced virtual posting_. The balanced virtual postings in a +transaction must add up to zero, just like ordinary postings, but +separately from them. These are not part of double entry bookkeeping +either, but they are at least balanced. An example: + +2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Ordinary postings, whose account names are neither parenthesised nor +bracketed, are called _real postings_. You can exclude virtual postings +from reports with the '-R/--real' flag or a 'real:1' query. + + +File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax + +9.28.10 Other Ledger directives +------------------------------- + +These other Ledger directives are currently accepted but ignored. This +allows hledger to read more Ledger files, but be aware that hledger's +reports may differ from Ledger's if you use these. + +apply fixed COMM AMT +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR +end apply fixed +end apply tag +end apply year +end tag +eval / expr EXPR +python + PYTHONCODE +tag NAME +value EXPR +--command-line-flags + + See also https://hledger.org/ledger.html for a detailed +hledger/Ledger syntax comparison. + + +File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top + +10 CSV +****** + +hledger can read CSV files (Character Separated Value - usually comma, +semicolon, or tab) containing dated records, automatically converting +each record into a transaction. + + (To learn about _writing_ CSV, see CSV output.) + + For best error messages when reading CSV/TSV/SSV files, make sure +they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use +a hledger file prefix (see File Extension below). + + Each CSV file must be described by a corresponding _rules file_. +This contains rules describing the CSV data (header line, fields layout, +date format etc.), how to construct hledger transactions from it, and +how to categorise transactions based on description or other attributes. + + By default hledger looks for a rules file named like the CSV file +with an extra '.rules' extension, in the same directory. Eg when asked +to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'. You can +specify a different rules file with the '--rules-file' option. If no +rules file is found, hledger will create a sample rules file, which +you'll need to adjust. + + At minimum, the rules file must identify the date and amount fields, +and often it also specifies the date format and how many header lines +there are. Here's a simple CSV file and a rules file for it: + +Date, Description, Id, Amount +12/11/2019, Foo, 123, 10.23 + +# basic.csv.rules +skip 1 +fields date, description, , amount +date-format %d/%m/%Y + +$ hledger print -f basic.csv +2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There's an introductory Importing CSV data tutorial on hledger.org, +and more CSV rules examples below, and a larger collection at +https://github.com/simonmichael/hledger/tree/master/examples/csv. + +* Menu: + +* CSV rules cheatsheet:: +* source:: +* separator:: +* skip:: +* date-format:: +* timezone:: +* newest-first:: +* intra-day-reversed:: +* decimal-mark:: +* fields list:: +* Field assignment:: +* Field names:: +* if block:: +* Matchers:: +* if table:: +* balance-type:: +* include:: +* Working with CSV:: +* CSV rules examples:: + + +File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV + +10.1 CSV rules cheatsheet +========================= + +The following kinds of rule can appear in the rules file, in any order. +(Blank lines and lines beginning with '#' or ';' or '*' are ignored.) + +*'source'* optionally declare which file to read data + from +*'separator'* declare the field separator, instead of + relying on file extension +*'skip'* skip one or more header lines at start of file +*'date-format'* declare how to parse CSV dates/date-times +*'timezone'* declare the time zone of ambiguous CSV + date-times +*'newest-first'* improve txn order when: there are multiple + records, newest first, all with the same date +*'intra-day-reversed'* improve txn order when: same-day txns are in + opposite order to the overall file +*'decimal-mark'* declare the decimal mark used in CSV amounts, + when ambiguous +*'fields' list* name CSV fields for easy reference, and + optionally assign their values to hledger + fields +*Field assignment* assign a CSV value or interpolated text value + to a hledger field +*'if' block* conditionally assign values to hledger fields, + or 'skip' a record or 'end' (skip rest of + file) +*'if' table* conditionally assign values to hledger fields, + using compact syntax +*'balance-type'* select which type of balance + assertions/assignments to generate +*'include'* inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are +evaluated. + + +File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV + +10.2 'source' +============= + +If you tell hledger to read a csv file with '-f foo.csv', it will look +for rules in 'foo.csv.rules'. Or, you can tell it to read the rules +file, with '-f foo.csv.rules', and it will look for data in 'foo.csv' +(since 1.30). + + These are mostly equivalent, but the second method provides some +extra features. For one, the data file can be missing, without causing +an error; it is just considered empty. And, you can specify a different +data file by adding a "source" rule: + +source ./Checking1.csv + + If you specify just a file name with no path, hledger will look for +it in your system's downloads directory ('~/Downloads', currently): + +source Checking1.csv + + And if you specify a glob pattern, hledger will read the most recent +of the matched files (useful with repeated downloads): + +source Checking1*.csv + + See also "Working with CSV > Reading files specified by rule". + + +File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV + +10.3 'separator' +================ + +You can use the 'separator' rule to read other kinds of +character-separated data. The argument is any single separator +character, or the words 'tab' or 'space' (case insensitive). Eg, for +comma-separated values (CSV): + +separator , + + or for semicolon-separated values (SSV): + +separator ; + + or for tab-separated values (TSV): + +separator TAB + + If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a +'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be +inferred automatically, and you won't need this rule. + + +File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV + +10.4 'skip' +=========== + +skip N + + The word 'skip' followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines at the start of the input +data. You'll need this whenever your CSV data contains header lines. +Note, empty and blank lines are skipped automatically, so you don't need +to count those. + + 'skip' has a second meaning: it can be used inside if blocks +(described below), to skip one or more records whenever the condition is +true. Records skipped in this way are ignored, except they are still +required to be valid CSV. + + +File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV + +10.5 'date-format' +================== + +date-format DATEFMT + + This is a helper for the 'date' (and 'date2') fields. If your CSV +dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD', +you'll need to add a date-format rule describing them with a +strptime-style date parsing pattern - see +https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime. +The pattern must parse the CSV date value completely. Some examples: + +# MM/DD/YY +date-format %m/%d/%y + +# D/M/YYYY +# The - makes leading zeros optional. +date-format %-d/%-m/%Y + +# YYYY-Mmm-DD +date-format %Y-%h-%d + +# M/D/YYYY HH:MM AM some other junk +# Note the time and junk must be fully parsed, though only the date is used. +date-format %-m/%-d/%Y %l:%M %p some other junk + + +File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV + +10.6 'timezone' +=============== + +timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone +other than yours, but containing no explicit time zone information, you +can use this rule to declare the CSV's native time zone, which helps +prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don't +need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ', +'%Ez'; see the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware +conversion, localising the CSV date-times to your current system time +zone. If you prefer to localise to some other time zone, eg for +reproducibility, you can (on unix at least) set the output timezone with +the TZ environment variable, eg: + +$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + 'timezone' currently does not understand timezone names, except +"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". +For others, use numeric format: +HHMM or -HHMM. + + +File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV + +10.7 'newest-first' +=================== + +hledger tries to ensure that the generated transactions will be ordered +chronologically, including same-day transactions. Usually it can +auto-detect how the CSV records are ordered. But if it encounters CSV +where all records are on the same date, it assumes that the records are +oldest first. If in fact the CSV's records are normally newest first, +like: + +2022-10-01, txn 3... +2022-10-01, txn 2... +2022-10-01, txn 1... + + you can add the 'newest-first' rule to help hledger generate the +transactions in correct order. + +# same-day CSV records are newest first +newest-first + + +File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV + +10.8 'intra-day-reversed' +========================= + +If CSV records within a single day are ordered opposite to the overall +record order, you can add the 'intra-day-reversed' rule to improve the +order of journal entries. Eg, here the overall record order is newest +first, but same-day records are oldest first: + +2022-10-02, txn 3... +2022-10-02, txn 4... +2022-10-01, txn 1... +2022-10-01, txn 2... + +# transactions within each day are reversed with respect to the overall date order +intra-day-reversed + + +File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV + +10.9 'decimal-mark' +=================== + +decimal-mark . + + or: + +decimal-mark , + + hledger automatically accepts either period or comma as a decimal +mark when parsing numbers (cf Amounts). However if any numbers in the +CSV contain digit group marks, such as thousand-separating commas, you +should declare the decimal mark explicitly with this rule, to avoid +misparsed numbers. + + +File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV + +10.10 'fields' list +=================== + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word 'fields' followed by comma-separated field +names) is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say + '%SomeField' instead of remembering '%13'. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and + build a transaction. + + Here's an example that says "use the 1st, 2nd and 4th fields as the +transaction's date, description and amount; name the last two fields for +later reference; and ignore the others": + +fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to +the CSV file's separator. Also: + + * There must be least two items in the list (at least one comma). + * Field names may not contain spaces. Spaces before/after field + names are optional. + * Field names may contain '_' (underscore) or '-' (hyphen). + * Fields you don't care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it's convenient to use these for +your field names, suitably modified (eg lower-cased with spaces replaced +by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning +to a hledger field with the same name. Eg you could call the CSV's +"balance" field 'balance_' to avoid directly setting hledger's 'balance' +field (and generating a balance assertion). + + +File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV + +10.11 Field assignment +====================== + +HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to +hledger fields. They can be used instead of or in addition to a fields +list (see above). + + To assign a value to a hledger field, write the field name (any of +the standard hledger field/pseudo-field names, defined below), a space, +followed by a text value on the same line. This text value may +interpolate CSV fields, referenced either by their 1-based position in +the CSV record ('%N') or by the name they were given in the fields list +('%CSVFIELD'), and regular expression match groups ('\N'). + + Some examples: + +# set the amount to the 4th CSV field, with " USD" appended +amount %4 USD + +# combine three fields to make a comment, containing note: and date: tags +comment note: %somefield - %anotherfield, date: %1 + + Tips: + + * Interpolation strips outer whitespace (so a CSV value like '" 1 "' + becomes '1' when interpolated) (#1051). + * Interpolations always refer to a CSV field - you can't interpolate + a hledger field. (See Referencing other fields below). + + +File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV + +10.12 Field names +================= + +Note the two kinds of field names mentioned here, and used only in +hledger CSV rules files: + + 1. *CSV field names* ('CSVFIELD' in these docs): you can optionally + name the CSV columns for easy reference (since hledger doesn't yet + automatically recognise column headings in a CSV file), by writing + arbitrary names in a 'fields' list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you + must set at least some of these to generate the hledger transaction + from a CSV record, by writing them as the left hand side of a field + assignment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a 'fields' list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what +happens when you assign values to them: + +* Menu: + +* date field:: +* date2 field:: +* status field:: +* code field:: +* description field:: +* comment field:: +* account field:: +* amount field:: +* currency field:: +* balance field:: + + +File: hledger.info, Node: date field, Next: date2 field, Up: Field names + +10.12.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 + +10.12.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 + +10.12.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 + +10.12.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 + +10.12.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 + +10.12.6 comment field +--------------------- + +'comment' sets the transaction's comment, if any. + + 'commentN', where N is a number, sets the Nth posting's comment. + + You can assign multi-line comments by writing literal '\n' in the +code. A comment starting with '\n' will begin on a new line. + + Comments can contain tags, as usual. + + +File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names + +10.12.7 account field +--------------------- + +Assigning to 'accountN', where N is 1 to 99, sets the account name of +the Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you'll want to set 'account1' +and 'account2'. Typically 'account1' is associated with the CSV file, +and is set once with a top-level assignment, while 'account2' is set +based on each transaction's description, in conditional rules. + + If a posting's account name is left unset but its amount is set (see +below), a default account name will be chosen (like "expenses:unknown" +or "income:unknown"). + + +File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names + +10.12.8 amount field +-------------------- + +There are several ways to set posting amounts from CSV, useful in +different situations. + + 1. *'amount'* is the oldest and simplest. Assigning to this sets the + amount of the first and second postings. In the second posting, + the amount will be negated; also, if it has a cost attached, it + will be converted to cost. + + 2. *'amount-in'* and *'amount-out'* work exactly like the above, but + should be used when the CSV has two amount fields (such as "Debit" + and "Credit", or "Inflow" and "Outflow"). Whichever field has a + non-zero value will be used as the amount of the first and second + postings. Here are some tips to avoid confusion: + + * It's not "amount-in for posting 1 and amount-out for posting + 2", it is "extract a single amount from the amount-in or + amount-out field, and use that for posting 1 and (negated) for + posting 2". + * Don't use both 'amount' and 'amount-in'/'amount-out' in the + same rules file; choose based on whether the amount is in a + single CSV field or spread across two fields. + * In each record, at most one of the two CSV fields should + contain a non-zero amount; the other field must contain a zero + or nothing. + * hledger assumes both CSV fields contain unsigned numbers, and + it automatically negates the amount-out values. + * If the data doesn't fit these requirements, you'll probably + need an if rule (see below). + + 3. *'amountN'* (where N is a number from 1 to 99) sets the amount of + only a single posting: the Nth posting in the transaction. You'll + usually need at least two such assignments to make a balanced + transaction. You can also generate more than two postings, to + represent more complex transactions. The posting numbers don't + have to be consecutive; with if rules, higher posting numbers can + be useful to ensure a certain order of postings. + + 4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but + should be used when the CSV has two amount fields. This is + analogous to 'amount-in' and 'amount-out', and those tips also + apply here. + + 5. Remember that a 'fields' list can also do assignments. So in a + fields list if you name a CSV field "amount", that counts as + assigning to 'amount'. (If you don't want that, call it something + else in the fields list, like "amount_".) + + 6. The above don't handle every situation; if you need more + flexibility, use an 'if' rule to set amounts conditionally. See + "Working with CSV > Setting amounts" below for more on this and on + amount-setting generally. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +10.12.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 + +10.12.10 balance field +---------------------- + +'balanceN' sets a balance assertion amount (or if the posting amount is +left empty, a balance assignment) on posting N. + + 'balance' is a compatibility spelling for hledger <1.17; it is +equivalent to 'balance1'. + + You can adjust the type of assertion/assignment with the +'balance-type' rule (see below). + + See Tips below for more about setting amounts and currency. + + +File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV + +10.13 'if' block +================ + +Rules can be applied conditionally, depending on patterns in the CSV +data. This allows flexibility; in particular, it is how you can +categorise transactions, selecting an appropriate account name based on +their description (for example). There are two ways to write +conditional rules: "if blocks", described here, and "if tables", +described below. + + An if block is the word 'if' and one or more "matcher" expressions +(can be a word or phrase), one per line, starting either on the same or +next line; followed by one or more indented rules. Eg, + +if MATCHER + RULE + + or + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be +applied. They are usually field assignments, but the following special +rules may also be used within an if block: + + * 'skip' - skips the matched CSV record (generating no transaction + from it) + * 'end' - skips the rest of the current CSV file. + + Some examples: + +# if the record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the record contains any of these phrases, set account2 and a transaction comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + +# if an empty record is seen (assuming five fields), ignore the rest of the CSV file +if ,,,, + end + + +File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV + +10.14 Matchers +============== + +There are two kinds: + + 1. A record matcher is a word or single-line text fragment or regular + expression ('REGEX'), which hledger will try to match + case-insensitively anywhere within the CSV record. + Eg: 'whole foods' + + 2. A field matcher is preceded with a percent sign and CSV field name + ('%CSVFIELD REGEX'). hledger will try to match these just within + the named CSV field. + Eg: '%date 2023' + + The regular expression is (as usual in hledger) a POSIX extended +regular expression, that also supports GNU word boundaries ('\b', '\B', +'\<', '\>'), and nothing else. If you have trouble, see "Regular +expressions" in the hledger manual +(https://hledger.org/hledger.html#regular-expressions). + +* Menu: + +* What matchers match:: +* Combining matchers:: +* Match groups:: + + +File: hledger.info, Node: What matchers match, Next: Combining matchers, Up: Matchers + +10.14.1 What matchers match +--------------------------- + +With record matchers, it's important to know that the record matched is +not the original CSV record, but a modified one: separators will be +converted to commas, and enclosing double quotes (but not enclosing +whitespace) are removed. So for example, when reading an SSV file, if +the original record was: + +2023-01-01; "Acme, Inc."; 1,000 + + the regex would see, and try to match, this modified record text: + +2023-01-01,Acme, Inc., 1,000 + + +File: hledger.info, Node: Combining matchers, Next: Match groups, Prev: What matchers match, Up: Matchers + +10.14.2 Combining matchers +-------------------------- + +When an if block has multiple matchers, they are combined as follows: + + * By default they are OR'd (any one of them can match) + * When a matcher is preceded by ampersand ('&') it will be AND'ed + with the previous matcher (both of them must match) + * When a matcher is preceded by an exclamation mark ('!'), the + matcher is negated (it may not match). + + Currently there is a limitation: you can't use both '&' and '!' on +the same line (you can't AND a negated matcher). + + +File: hledger.info, Node: Match groups, Prev: Combining matchers, Up: Matchers + +10.14.3 Match groups +-------------------- + +Matchers can define match groups: parenthesised portions of the regular +expression which are available for reference in field assignments. +Groups are enclosed in regular parentheses ('(' and ')') and can be +nested. Each group is available in field assignments using the token +'\N', where N is an index into the match groups for this conditional +block (e.g. '\1', '\2', etc.). + + Example: Warp credit card payment postings to the beginning of the +billing period (Month start), to match how they are presented in +statements, using posting dates: + +if %date (....-..)-.. + comment2 date:\1-01 + + Another example: Read the expense account from the CSV field, but +throw away a prefix: + +if %account1 liabilities:family:(expenses:.*) + account1 \1 + + +File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV + +10.15 'if' table +================ + +"if tables" are an alternative to if blocks; they can express many +matchers and field assignments in a more compact tabular format, like +this: + +if,HLEDGERFIELD1,HLEDGERFIELD2,... +MATCHERA,VALUE1,VALUE2,... +MATCHERB,VALUE1,VALUE2,... +MATCHERC,VALUE1,VALUE2,... + + + The first character after 'if' is taken to be this if table's field +separator. It is unrelated to the separator used in the CSV file. It +should be a non-alphanumeric character like ',' or '|' that does not +appear anywhere else in the table (it should not be used in field names +or matchers or values, and it cannot be escaped with a backslash). + + Each line must contain the same number of separators; empty values +are allowed. Whitespace can be used in the matcher lines for +readability (but not in the if line, currently). The table must be +terminated by an empty line (or end of file). + + An if table like the above is interpreted as follows: try all of the +matchers; whenever a matcher succeeds, assign all of the values on that +line to the corresponding hledger fields; later lines can overrider +earlier ones. It is equivalent to this sequence of if blocks: + +if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERB + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + +if,account2,comment +atm transaction fee,expenses:business:banking,deductible? check it +%description groceries,expenses:groceries, +2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + +File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV + +10.16 'balance-type' +==================== + +Balance assertions generated by assigning to balanceN are of the simple +'=' type by default, which is a single-commodity, subaccount-excluding +assertion. You may find the subaccount-including variants more useful, +eg if you have created some virtual subaccounts of checking to help with +budgeting. You can select a different type of assertion with the +'balance-type' rule: + +# balance assertions will consider all commodities and all subaccounts +balance-type ==* + + Here are the balance assertion types for quick reference: + += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts + + +File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV + +10.17 'include' +=============== + +include RULESFILE + + This includes the contents of another CSV rules file at this point. +'RULESFILE' is an absolute file path or a path relative to the current +file's directory. This can be useful for sharing common rules between +several rules files, eg: + +# someaccount.csv.rules + +## someaccount-specific rules +fields date,description,amount +account1 assets:someaccount +account2 expenses:misc + +## common rules +include categorisation.rules + + +File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV + +10.18 Working with CSV +====================== + +Some tips: + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading CSV from standard input:: +* Reading multiple CSV files:: +* Reading files specified by rule:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Amount signs:: +* Setting currency/commodity:: +* Amount decimal places:: +* Referencing other fields:: +* How CSV rules are evaluated:: +* Well factored rules:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV + +10.18.1 Rapid feedback +---------------------- + +It's a good idea to get rapid feedback while creating/troubleshooting +CSV rules. Here's a good way, using entr from eradman.com/entrproject: + +$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions +of interest. "bash -c" is used to run multiple commands, so we can echo +a separator each time the command re-runs, making it easier to read the +output. + + +File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV + +10.18.2 Valid CSV +----------------- + +Note that hledger will only accept valid CSV conforming to RFC 4180, and +equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab +as separators). This means, eg: + + * Values may be enclosed in double quotes, or not. Enclosing in + single quotes is not allowed. (Eg ''A','B'' is rejected.) + * When values are enclosed in double quotes, spaces outside the + quotes are not allowed. (Eg '"A", "B"' is rejected.) + * When values are not enclosed in quotes, they may not contain double + quotes. (Eg 'A"A, B' is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you'll need to +transform it before reading with hledger. Try using sed, or a more +permissive CSV parser like python's csv lib. + + +File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV + +10.18.3 File Extension +---------------------- + +To help hledger choose the CSV file reader and show the right error +messages (and choose the right field separator character by default), +it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv' +filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV +reader (and the default field separator) by prefixing the file path with +'csv:', 'ssv:' or 'tsv:': Eg: + +$ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator +rule if needed. + + +File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV + +10.18.4 Reading CSV from standard input +--------------------------------------- + +You'll need the file format prefix when reading CSV from stdin also, +since hledger assumes journal format by default. Eg: + +$ cat foo.dat | hledger -f ssv:- print + + +File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV + +10.18.5 Reading multiple CSV files +---------------------------------- + +If you use multiple '-f' options to read multiple CSV files at once, +hledger will look for a correspondingly-named rules file for each CSV +file. But if you use the '--rules-file' option, that rules file will be +used for all the CSV files. + + +File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV + +10.18.6 Reading files specified by rule +--------------------------------------- + +Instead of specifying a CSV file in the command line, you can specify a +rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will +read data from foo.csv in the same directory, but you can add a source +rule to specify a different data file, perhaps located in your web +browser's download directory. + + This feature was added in hledger 1.30, so you won't see it in most +CSV rules examples. But it helps remove some of the busywork of +managing CSV downloads. Most of your financial institutions's default +CSV filenames are different and can be recognised by a glob pattern. So +you can put a rule like 'source Checking1*.csv' in +foo-checking.csv.rules, and then periodically follow a workflow like: + + 1. Download CSV from Foo's website, using your browser's defaults + 2. Run 'hledger import foo-checking.csv.rules' to import any new + transactions + + After import, you can: discard the CSV, or leave it where it is for a +while, or move it into your archives, as you prefer. If you do nothing, +next time your browser will save something like Checking1-2.csv, and +hledger will use that because of the '*' wild card and because it is the +most recent. + + +File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV + +10.18.7 Valid transactions +-------------------------- + +After reading a CSV file, hledger post-processes and validates the +generated journal entries as it would for a journal file - balancing +them, applying balance assignments, and canonicalising amount styles. +Any errors at this stage will be reported in the usual way, displaying +the problem entry. + + There is one exception: balance assertions, if you have generated +them, will not be checked, since normally these will work only when the +CSV data is part of the main journal. If you do need to check balance +assertions generated from CSV right away, pipe into another hledger: + +$ hledger -f file.csv print | hledger -f- print + + +File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV + +10.18.8 Deduplicating, importing +-------------------------------- + +When you download a CSV file periodically, eg to get your latest bank +transactions, the new file may overlap with the old one, containing some +of the same records. + + The import command will (a) detect the new transactions, and (b) +append just those transactions to your main journal. It is idempotent, +so you don't have to remember how many times you ran it or with which +version of the CSV. (It keeps state in a hidden '.latest.FILE.csv' +file.) This is the easiest way to import CSV data. Eg: + +# download the latest CSV files, then run this command. +# Note, no -f flags needed here. +$ hledger import *.csv [--dry] + + This method works for most CSV files. (Where records have a stable +chronological order, and new records appear only at the new end.) + + A number of other tools and workflows, hledger-specific and +otherwise, exist for converting, deduplicating, classifying and managing +CSV data. See: + + * https://hledger.org/cookbook.html#setups-and-workflows + * https://plaintextaccounting.org -> data import/conversion + + +File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV + +10.18.9 Setting amounts +----------------------- + +Continuing from amount field above, here are more tips for +amount-setting: + + 1. *If the amount is in a single CSV field:* + + a. *If its sign indicates direction of flow:* + Assign it to 'amountN', to set the Nth posting's amount. N is + usually 1 or 2 but can go up to 99. + + b. *If another field indicates direction of flow:* + Use one or more conditional rules to set the appropriate + amount sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. *If the amount is in two CSV fields (such as Debit and Credit, or + In and Out):* + + a. *If both fields are unsigned:* + Assign one field to 'amountN-in' and the other to + 'amountN-out'. hledger will automatically negate the "out" + field, and will use whichever field value is non-zero as + posting N's amount. + + b. *If either field is signed:* + You will probably need to override hledger's sign for one or + the other field, as in the following example: + + # Negate the -out value, but only if it is not empty: + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields can contain a non-zero value (or both can be + empty):* + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such + as '1' and 'none'. For such cases, use conditional rules to + help select the amount. Eg, to handle the above you could + select the value containing non-zero digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. *If you want posting 2's amount converted to cost:* + Use the unnumbered 'amount' (or 'amount-in' and 'amount-out') + syntax. + + 4. *If the CSV has only balance amounts, not transaction amounts:* + Assign to 'balanceN', to set a balance assignment on the Nth + posting, causing the posting's amount to be calculated + automatically. 'balance' with no number is equivalent to + 'balance1'. In this situation hledger is more likely to guess the + wrong default account name, so you may need to set that explicitly. + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV + +10.18.10 Amount signs +--------------------- + +There is some special handling making it easier to parse and to reverse +amount signs. (This only works for whole amounts, not for cost amounts +such as COST in 'amount1 AMT @ COST'): + + * *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 '""'. + + It's not possible (without preprocessing the CSV) to set an amount to +its absolute value, ie discard its sign. + + +File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV + +10.18.11 Setting currency/commodity +----------------------------------- + +If the currency/commodity symbol is included in the CSV's amount +field(s): + +2023-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 + +2023-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + +2023-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 + +2023-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 + +2023-01-01 foo + expenses:unknown 123.00 USD + income:unknown -123.00 USD + + Note we used a temporary field name ('cur') that is not 'currency' - +that would trigger the prepending effect, which we don't want here. + + +File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV + +10.18.12 Amount decimal places +------------------------------ + +Like amounts in a journal file, the amounts generated by CSV rules like +'amount1' influence commodity display styles, such as the number of +decimal places displayed in reports. + + The original amounts as written in the CSV file do not affect display +style (because we don't yet reliably know their commodity). + + +File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV + +10.18.13 Referencing other fields +--------------------------------- + +In field assignments, you can interpolate only CSV fields, not hledger +fields. In the example below, there's both a CSV field and a hledger +field named amount1, but %amount1 always means the CSV field, not the +hledger field: + +# Name the third CSV field "amount1" +fields date,description,amount1 + +# Set hledger's amount1 to the CSV amount1 field followed by USD +amount1 %amount1 USD + +# Set comment to the CSV amount1 (not the amount1 assigned above) +comment %amount1 + + Here, since there's no CSV amount1 field, %amount1 will produce a +literal "amount1": + +fields date,description,csvamount +amount1 %csvamount USD +# Can't interpolate amount1 here +comment %amount1 + + When there are multiple field assignments to the same hledger field, +only the last one takes effect. Here, comment's value will be be B, or +C if "something" is matched, but never A: + +comment A +comment B +if something + comment C + + +File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV + +10.18.14 How CSV rules are evaluated +------------------------------------ + +Here's how to think of CSV rules being evaluated (if you really need +to). First, + + * 'include' - all includes are inlined, from top to bottom, depth + first. (At each include point the file is inlined and scanned for + further includes, recursively, before proceeding.) + + Then "global" rules are evaluated, top to bottom. If a rule is +repeated, the last one wins: + + * 'skip' (at top level) + * 'date-format' + * 'newest-first' + * 'fields' - names the CSV fields, optionally sets up initial + assignments to hledger fields + + Then for each CSV record in turn: + + * test all 'if' blocks. If any of them contain a 'end' rule, skip + all remaining CSV records. Otherwise if any of them contain a + 'skip' rule, skip that many CSV records. If there are multiple + matched 'skip' rules, the first one wins. + * collect all field assignments at top level and in matched 'if' + blocks. When there are multiple assignments for a field, keep only + the last one. + * compute a value for each hledger field - either the one that was + assigned to it (and interpolate the %CSVFIELD references), or a + default + * generate a hledger transaction (journal entry) from these values. + + This is all part of the CSV reader, one of several readers hledger +can use to parse input files. When all files have been read +successfully, the transactions are passed as input to whichever hledger +command the user specified. + + +File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV + +10.18.15 Well factored rules +---------------------------- + +Some things than can help reduce duplication and complexity in rules +files: + + * Extracting common rules usable with multiple CSV files into a + 'common.rules', and adding 'include common.rules' to each CSV's + rules file. + + * Splitting if blocks into smaller if blocks, extracting the + frequently used parts. + + +File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV + +10.19 CSV rules examples +======================== + +* Menu: + +* Bank of Ireland:: +* Coinbase:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples + +10.19.1 Bank of Ireland +----------------------- + +Here's a CSV with two amount fields (Debit and Credit), and a balance +field, which we can use to add balance assertions, which is not +necessary but provides extra error checking: + +Date,Details,Debit,Credit,Balance +07/12/2012,LODGMENT 529898,,10.0,131.21 +07/12/2012,PAYMENT,5,,126 + +# bankofireland-checking.csv.rules + +# skip the header line +skip + +# name the csv fields, and assign some of them as journal entry fields +fields date, description, amount-out, amount-in, balance + +# We generate balance assertions by assigning to "balance" +# above, but you may sometimes need to remove these because: +# +# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience +# +# - it is sometimes calculated based on non-chronological ordering, +# eg when multiple transactions clear on the same day + +# date is in UK/Ireland format +date-format %d/%m/%Y + +# set the currency +currency EUR + +# set the base account for all txns +account1 assets:bank:boi:checking + +$ hledger -f bankofireland-checking.csv print +2012-12-07 LODGMENT 529898 + assets:bank:boi:checking EUR10.0 = EUR131.2 + income:unknown EUR-10.0 + +2012-12-07 PAYMENT + assets:bank:boi:checking EUR-5.0 = EUR126.0 + expenses:unknown EUR5.0 + + The balance assertions don't raise an error above, because we're +reading directly from CSV, but they will be checked if these entries are +imported into a journal file. + + +File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples + +10.19.2 Coinbase +---------------- + +A simple example with some CSV from Coinbase. The spot price is +recorded using cost notation. The legacy 'amount' field name +conveniently sets amount 2 (posting 2's amount) to the total cost. + +# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes +# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + +# coinbase.csv.rules +skip 1 +fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes +date %Timestamp +date-format %Y-%m-%dT%T%Z +description %Notes +account1 assets:coinbase:cc +amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + +$ hledger print -f coinbase.csv +2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + +File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples + +10.19.3 Amazon +-------------- + +Here we convert amazon.com order history, and use an if block to +generate a third posting if there's a fee. (In practice you'd probably +get this data from your bank instead, but it's an example.) + +"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" +"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" +"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" + +# amazon-orders.csv.rules + +# skip one header line +skip 1 + +# name the csv fields, and assign the transaction's date, amount and code. +# Avoided the "status" and "amount" hledger field names to prevent confusion. +fields date, _, toorfrom, name, amzstatus, amzamount, fees, code + +# how to parse the date +date-format %b %-d, %Y + +# combine two fields to make the description +description %toorfrom %name + +# save the status as a tag +comment status:%amzstatus + +# set the base account for all transactions +account1 assets:amazon +# leave amount1 blank so it can balance the other(s). +# I'm assuming amzamount excludes the fees, don't remember + +# set a generic account2 +account2 expenses:misc +amount2 %amzamount +# and maybe refine it further: +#include categorisation.rules + +# add a third posting for fees, but only if they are non-zero. +if %fees [1-9] + account3 expenses:fees + amount3 %fees + +$ hledger -f amazon-orders.csv print +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed + assets:amazon + expenses:misc $20.00 + +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed + assets:amazon + expenses:misc $25.00 + expenses:fees $1.00 + + +File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples + +10.19.4 Paypal +-------------- + +Here's a real-world rules file for (customised) Paypal CSV, with some +Paypal-specific rules, and a second rules file included: + +"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" +"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" +"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" +"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" +"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" +"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" +"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" +"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" + +# paypal-custom.csv.rules + +# Tips: +# Export from Activity -> Statements -> Custom -> Activity download +# Suggested transaction type: "Balance affecting" +# Paypal's default fields in 2018 were: +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" +# This rules file assumes the following more detailed fields, configured in "Customize report fields": +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" + +fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note + +skip 1 + +date-format %-m/%-d/%Y + +# ignore some paypal events +if +In Progress +Temporary Hold +Update to + skip + +# add more fields to the description +description %description_ %itemtitle + +# save some other fields as tags +comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ + +# convert to short currency symbols +if %currency USD + currency $ +if %currency EUR + currency E +if %currency GBP + currency P + +# generate postings + +# the first posting will be the money leaving/entering my paypal account +# (negative means leaving my account, in all amount fields) +account1 assets:online:paypal +amount1 %netamount + +# the second posting will be money sent to/received from other party +# (account2 is set below) +amount2 -%grossamount + +# if there's a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] + account3 expenses:banking:paypal + amount3 -%feeamount + comment3 business: + +# choose an account for the second posting + +# override the default account names: +# if the amount is positive, it's income (a debit) +if %grossamount ^[^-] + account2 income:unknown +# if negative, it's an expense (a credit) +if %grossamount ^- + account2 expenses:unknown + +# apply common rules for setting account2 & other tweaks +include common.rules + +# apply some overrides specific to this csv + +# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case. +if +Bank Account +Bank Deposit to PP Account + description %type for %referencetxnid %itemtitle + account2 assets:bank:wf:pchecking + account1 assets:online:paypal + +# Currency conversions +if Currency Conversion + account2 equity:currency conversion + +# common.rules + +if +darcs +noble benefactor + account2 revenues:foss donations:darcshub + comment2 business: + +if +Calm Radio + account2 expenses:online:apps + +if +electronic frontier foundation +Patreon +wikimedia +Advent of Code + account2 expenses:dues + +if Google + account2 expenses:online:apps + description google | music + +$ hledger -f paypal-custom.csv print +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed + assets:online:paypal $-6.99 = $-6.99 + expenses:online:apps $6.99 + +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $6.99 = $0.00 + assets:bank:wf:pchecking $-6.99 + +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed + assets:online:paypal $-7.00 = $-7.00 + expenses:dues $7.00 + +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $7.00 = $0.00 + assets:bank:wf:pchecking $-7.00 + +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed + assets:online:paypal $-2.00 = $-2.00 + expenses:dues $2.00 + expenses:banking:paypal ; business: + +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $2.00 = $0.00 + assets:bank:wf:pchecking $-2.00 + +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed + assets:online:paypal $9.41 = $9.41 + revenues:foss donations:darcshub $-10.00 ; business: + expenses:banking:paypal $0.59 ; business: + + +File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top + +11 Timeclock +************ + +The time logging format of timeclock.el, as read by hledger. + + hledger can read time logs in timeclock format. As with Ledger, +these are (a subset of) timeclock.el's format, containing clock-in and +clock-out entries as in the example below. The date is a simple date. +The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are +optional. The timezone, if present, must be four digits and is ignored +(currently the time is always interpreted as a local time). Lines +beginning with '#' or ';' or '*', and blank lines, are ignored. + +i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: +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 2 spaces ; optional comment, tags: + (some account) 0.33h + +2015-03-31 * 22:21-23:59 + (another:account) 1.64h + +2015-04-01 * 00:00-02:00 + (another:account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + +$ hledger -f sample.timeclock balance # current time balances +$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + * use emacs and the built-in timeclock.el, or the extended + timeclock-x.el and perhaps the extras in ledgerutils.el + + * at the command line, use these bash aliases: 'shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' + + * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + +File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top + +12 Timedot +********** + +'timedot' format is hledger's human-friendly time logging format. +Compared to 'timeclock' format, it is more convenient for quick, +approximate, and retroactive time logging, and more human-readable (you +can see at a glance where time was spent). A quick example: + +2023-05-01 +hom:errands .... .... ; two hours; the space is ignored +fos:hledger:timedot .. ; half an hour +per:admin:finance ; no time spent yet + + hledger reads this as a transaction on this day with three +(unbalanced) postings, where each dot represents "0.25". No commodity +symbol is assumed, but we typically interpret it as hours. + +$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required +2023-05-01 * + (hom:errands) 2.00 ; two hours + (fos:hledger:timedot) 0.50 ; half an hour + (per:admin:finance) 0 + + A timedot file contains a series of transactions (usually one per +day). Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D), +optionally be followed on the same line by a transaction description, +and/or a transaction comment following a semicolon. + + After the date line are zero or more time postings, consisting of: + + * *An account name* - any hledger-style account name, optionally + indented. + + * *Two or more spaces* - required if there is an amount (as in + journal format). + + * *A timedot amount*, which can be + + * empty (representing zero) + + * a number, optionally followed by a unit 's', 'm', 'h', 'd', + 'w', 'mo', or 'y', representing a precise number of seconds, + minutes, hours, days weeks, months or years (hours is assumed + by default), which will be converted to hours according to 60s + = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. + + * one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can + be used for grouping/alignment. + + * one or more letters. These are like dots but they also + generate a tag 't:' (short for "type") with the letter as its + value, and a separate posting for each of the values. This + provides a second dimension of categorisation, viewable in + reports with '--pivot t'. + + * *An optional comment* following a semicolon (a hledger-style + posting comment). + + There is some flexibility to help with keeping time log data and +notes in the same file: + + * Blank lines and lines beginning with '#' or ';' are ignored. + + * After the first date line, lines which do not contain a double + space are parsed as postings with zero amount. (hledger's register + reports will show these if you add -E). + + * Before the first date line, lines beginning with '*' (eg org + headings) are ignored. And from the first date line onward, Emacs + org mode heading prefixes at the start of lines (one or more '*''s + followed by a space) will be ignored. This means the time log can + also be a org outline. + +* Menu: + +* Timedot examples:: + + +File: hledger.info, Node: Timedot examples, Up: Timedot + +12.1 Timedot examples +===================== + +Numbers: + +2016/2/3 +inc:client1 4 +fos:hledger 3h +biz:research 60m + + Dots: + +# 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 . + +$ 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 + + Letters: + +# Activity types: +# c cleanup/catchup/repair +# e enhancement +# s support +# l learning/research + +2023-11-01 +work:adm ccecces + +$ hledger -f a.timedot print +2023-11-01 + (work:adm) 1 ; t:c + (work:adm) 0.5 ; t:e + (work:adm) 0.25 ; t:s + +$ hledger -f a.timedot bal + 1.75 work:adm +-------------------- + 1.75 + +$ hledger -f a.timedot bal --pivot t + 1.00 c + 0.50 e + 0.25 s +-------------------- + 1.75 + + Org: + +* 2023 Work Diary +** Q1 +*** 2023-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 + + Using '.' as account name separator: + +2016/2/4 +fos.hledger.timedot 4h +fos.ledger .. + +$ hledger -f a.timedot --alias '/\./=:' bal -t + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +-------------------- + 4.50 + + +File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Amount formatting parseability, Prev: Timedot, Up: Top + +13 PART 3: REPORTING CONCEPTS +***************************** + + +File: hledger.info, Node: Amount formatting parseability, Next: Time periods, Prev: PART 3 REPORTING CONCEPTS, Up: Top + +14 Amount formatting, parseability +********************************** + +If you're wondering why your 'print' report sometimes shows trailing +decimal marks, with no decimal digits; it does this when showing amounts +that have digit group marks but no decimal digits, to disambiguate them +and allow them to be re-parsed reliably (see also Decimal marks, digit +group marks. Eg: + +commodity $1,000.00 + +2023-01-02 + (a) $1000 + +$ hledger print +2023-01-02 + (a) $1,000. + + If this is a problem (eg when exporting to Ledger), you can avoid it +by disabling digit group marks, eg with -c/-commodity (for each affected +commodity): + +$ hledger print -c '$1000.00' +2023-01-02 + (a) $1000 + + or by forcing print to always show decimal digits, with -round: + +$ hledger print -c '$1,000.00' --round=soft +2023-01-02 + (a) $1,000.00 + + More generally: hledger output falls into three rough categories, +which format amounts a little bit differently to suit different +consumers: + + *1. "hledger-readable output" - should be readable by hledger (and +by humans)* + + * This is produced by reports that show full journal entries: + 'print', 'import', 'close', 'rewrite' etc. + * It shows amounts with their original journal precisions, which may + not be consistent. + * It adds a trailing decimal mark when needed to avoid showing + ambiguous amounts. + * It can be parsed reliably (by hledger and ledger2beancount at + least, but perhaps not by Ledger..) + + *2. "human-readable output" - usually for humans* + + * This is produced by all other reports. + * It shows amounts with standard display precisions, which will be + consistent within each commodity. + * It shows ambiguous amounts unmodified. + * It can be parsed reliably in the context of a known report (when + you know decimals are consistently not being shown, you can assume + a single mark is a digit group mark). + + *3. "machine-readable output" - usually for other software* + + * This is produced by all reports when an output format like 'csv', + 'tsv', 'json', or 'sql' is selected. + * It shows amounts as 1 or 2 do, but without digit group marks. + * It can be parsed reliably (if needed, the decimal mark can be + changed with -c/-commodity-style). + + +File: hledger.info, Node: Time periods, Next: Depth, Prev: Amount formatting parseability, Up: Top + +15 Time periods +*************** + +* Menu: + +* Report start & end date:: +* Smart dates:: +* Report intervals:: +* Date adjustment:: +* Period expressions:: + + +File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods + +15.1 Report start & end date +============================ + +By default, most hledger reports will show the full span of time +represented by the journal. The report start date will be the earliest +transaction or posting date, and the report end date will be the latest +transaction, posting, or market price date. + + Often you will want to see a shorter time span, such as the current +month. You can specify a start and/or end date using '-b/--begin', +'-e/--end', '-p/--period' or a 'date:' query (described below). All of +these accept the smart date syntax (below). + + Some notes: + + * End dates are exclusive, as in Ledger, so you should write the date + _after_ the last day you want to see in the report. + * As noted in reporting options: among start/end dates specified with + _options_, the last (i.e. right-most) option takes precedence. + * The effective report start and end dates are the intersection of + the start/end dates from options and that from 'date:' queries. + That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January + 2019, the smallest common time span. + * In some cases a report interval will adjust start/end dates to fall + on interval boundaries (see below). + + Examples: + +'-b begin on St. Patrick's day 2016 +2016/3/17' +'-e 12/1' end at the start of december 1st of the current year + (11/30 will be the last date included) +'-b all transactions on or after the 1st of the current month +thismonth' +'-p all transactions in the current month +thismonth' +'date:2016/3/17..'the above written as queries instead ('..' can also be + replaced with '-') +'date:..12/1' +'date:thismonth..' +'date:thismonth' + + +File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods + +15.2 Smart dates +================ + +hledger's user interfaces accept a "smart date" syntax for added +convenience. Smart dates optionally can be relative to today's date, be +written with english words, and have less-significant parts omitted +(missing parts are inferred as 1). Some examples: + +'2004/10/1', exact date, several separators allowed. Year +'2004-01-01', is 4+ digits, month is 1-12, day is 1-31 +'2004.9.1' +'2004' start of year +'2004/10' start of month +'10/1' month and day in current year +'21' day in current month +'october, oct' start of month in current year +'yesterday, today, -1, 0, 1 days from today +tomorrow' +'last/this/next -1, 0, 1 periods from the current period +day/week/month/quarter/year' +'in n n periods from the current period +days/weeks/months/quarters/years' +'n n periods from the current period +days/weeks/months/quarters/years +ahead' +'n -n periods from the current period +days/weeks/months/quarters/years +ago' +'20181201' 8 digit YYYYMMDD with valid year month and + day +'201812' 6 digit YYYYMM with valid year and month + + Some counterexamples - malformed digit sequences might give +surprising results: + +'201813' 6 digits with an invalid month is parsed as start of + 6-digit year +'20181301' 8 digits with an invalid month is parsed as start of + 8-digit year +'20181232' 8 digits with an invalid day gives an error +'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error + + "Today's date" can be overridden with the '--today' option, in case +it's needed for testing or for recreating old reports. (Except for +periodic transaction rules, which are not affected by '--today'.) + + +File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods + +15.3 Report intervals +===================== + +A report interval can be specified so that reports like register, +balance or activity become multi-period, showing each subperiod as a +separate row or column. + + The following standard intervals can be enabled with command-line +flags: + + * '-D/--daily' + * '-W/--weekly' + * '-M/--monthly' + * '-Q/--quarterly' + * '-Y/--yearly' + + More complex intervals can be specified using '-p/--period', +described below. + + +File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods + +15.4 Date adjustment +==================== + +When there is a report interval (other than daily), report start/end +dates which have been inferred, eg from the journal, are automatically +adjusted to natural period boundaries. This is convenient for producing +simple periodic reports. More precisely: + + * an inferred start date will be adjusted earlier if needed to fall + on a natural period boundary + + * an inferred end date will be adjusted later if needed to make the + last period the same length as the others. + + By contrast, start/end dates which have been specified explicitly, +with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger +1.29). This makes it possible to specify non-standard report periods, +but it also means that if you are specifying a start date, you should +pick one that's on a period boundary if you want to see simple report +period headings. + + +File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods + +15.5 Period expressions +======================= + +The '-p/--period' option specifies a period expression, which is a +compact way of expressing a start date, end date, and/or report +interval. + + Here's a period expression with a start and end date (specifying the +first quarter of 2009): + +'-p "from 2009/1/1 to 2009/4/1"' + + Several keywords like "from" and "to" are supported for readability; +these are optional. "to" can also be written as ".." or "-". The +spaces are also optional, as long as you don't run two dates together. +So the following are equivalent to the above: + +'-p "2009/1/1 2009/4/1"' +'-p2009/1/1to2009/4/1' +'-p2009/1/1..2009/4/1' + + Dates are smart dates, so if the current year is 2009, these are also +equivalent to the above: + +'-p "1/1 4/1"' +'-p "jan-apr"' +'-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction date in the journal: + +'-p "from 2009/1/1"' everything after january 1, 2009 +'-p "since 2009/1"' the same, since is a synonym +'-p "from 2009"' the same +'-p "to 2009"' everything before january 1, 2009 + + You can also specify a period by writing a single partial or full +date: + +'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” +'-p "2009/1"' the month of january 2009; equivalent to “2009/1/1 to + 2009/2/1” +'-p the first day of 2009; equivalent to “2009/1/1 to +"2009/1/1"' 2009/1/2” + + or by using the "Q" quarter-year syntax (case insensitive): + +'-p "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to + 2009/4/1” +'-p "q4"' fourth quarter of the current year + +* Menu: + +* Period expressions with a report interval:: +* More complex report intervals:: +* Multiple weekday intervals:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +15.5.1 Period expressions with a report interval +------------------------------------------------ + +A period expression can also begin with a report interval, separated +from the start/end dates (if any) by a space or the word 'in': + +'-p "weekly from 2009/1/1 to 2009/4/1"' +'-p "monthly in 2008"' +'-p "quarterly"' + + +File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions + +15.5.2 More complex report intervals +------------------------------------ + +Some more complex intervals can be specified within period expressions, +such as: + + * 'biweekly' (every two weeks) + * 'fortnightly' + * 'bimonthly' (every two months) + * 'every day|week|month|quarter|year' + * 'every N days|weeks|months|quarters|years' + + Weekly on a custom day: + + * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted + after the number) + * 'every WEEKDAYNAME' (full or three-letter english weekday name, + case insensitive) + + Monthly on a custom day: + + * 'every Nth day [of month]' + * 'every Nth WEEKDAYNAME [of month]' + + Yearly on a custom day: + + * 'every MM/DD [of year]' (month number and day of month number) + * 'every MONTHNAME DDth [of year]' (full or three-letter english + month name, case insensitive, and day of month number) + * 'every DDth MONTHNAME [of year]' (equivalent to the above) + + Examples: + +'-p "bimonthly from +2008"' +'-p "every 2 weeks"' +'-p "every 5 months from +2009/03"' +'-p "every 2nd day of periods will go from Tue to Tue +week"' +'-p "every Tue"' same +'-p "every 15th day"' period boundaries will be on 15th of each + month +'-p "every 2nd Monday"' period boundaries will be on second Monday + of each month +'-p "every 11/05"' yearly periods with boundaries on 5th of + November +'-p "every 5th November"' same +'-p "every Nov 5th"' same + + Show historical balances at end of the 15th day of each month (N is +an end date, exclusive as always): + +$ hledger balance -H -p "every 16th day" + + Group postings from the start of wednesday to end of the following +tuesday (N is both (inclusive) start date and (exclusive) end date): + +$ hledger register checking -p "every 3rd day of week" + + +File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions + +15.5.3 Multiple weekday intervals +--------------------------------- + +This special form is also supported: + + * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english + weekday names, case insensitive) + + Also, 'weekday' and 'weekendday' are shorthand for +'mon,tue,wed,thu,fri' and 'sat,sun'. + + This is mainly intended for use with '--forecast', to generate +periodic transactions on arbitrary days of the week. It may be less +useful with '-p', since it divides each week into subperiods of unequal +length, which is unusual. (Related: #1632) + + Examples: + +'-p "every dates will be Mon, Wed, Fri; periods will be +mon,wed,fri"' Mon-Tue, Wed-Thu, Fri-Sun +'-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will +weekday"' be Mon, Tue, Wed, Thu, Fri-Sun +'-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri +weekendday"' + + +File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top + +16 Depth +******** + +With the '--depth NUM' option (short form: '-NUM'), reports will show +accounts only to the specified depth, hiding deeper subaccounts. Use +this when you want a summary with less detail. This flag has the same +effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are +equivalent. + + +File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top + +17 Queries +********** + +One of hledger's strengths is being able to quickly report on a precise +subset of your data. Most hledger commands accept optional query +arguments to restrict their scope. The syntax is as follows: + + * Zero or more space-separated query terms. These are most often + account name substrings: + + 'utilities food:groceries' + + * Terms with spaces or other special characters should be enclosed in + quotes: + + '"personal care"' + + * Regular expressions are also supported: + + '"^expenses\b"' + '"accounts (payable|receivable)"' + + * Add a query type prefix to match other parts of the data: + + 'date:202312-' + 'status:' + 'desc:amazon' + 'cur:USD' + '"amt:>0"' + + * Add a 'not:' prefix to negate: + + 'not:cur:USD' + + * Multiple unlike terms are AND-ed, multiple like terms are OR-ed + + 'date:2022 desc:amazon desc:amzn' + (all transactions with "amazon" or "amzn" in description during + 2022) + +* Menu: + +* Query types:: +* Combining query terms:: +* Queries and command options:: +* Queries and valuation:: +* Querying with account aliases:: +* Querying with cost or value:: + + +File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries + +17.1 Query types +================ + +Here are the types of query term available. Remember these can also be +prefixed with *'not:'* to convert them into a negative match. + + *'acct:REGEX', 'REGEX'* +Match account names containing this (case insensitive) regular +expression. This is the default query type when there is no prefix, and +regular expression syntax is typically not needed, so usually we just +write an account name substring, like 'expenses' or 'food'. + + *'amt:N, amt:N, amt:>=N'* +Match postings with a single-commodity amount equal to, less than, or +greater than N. (Postings with multi-commodity amounts are not tested +and will always match.) The comparison has two modes: if N is preceded +by a + or - sign (or is 0), the two signed numbers are compared. +Otherwise, the absolute magnitudes are compared, ignoring sign. + + *'code:REGEX'* +Match by transaction code (eg check number). + + *'cur:REGEX'* +Match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. (For a partial +match, use '.*REGEX.*'). Note, to match special characters which are +regex-significant, you need to escape them with '\'. And for characters +which are significant to your shell you may need one more level of +escaping. So eg to match the dollar sign: +'hledger print cur:\\$'. + + *'desc:REGEX'* +Match transaction descriptions. + + *'date:PERIODEXPR'* +Match dates (or with the '--date2' flag, secondary dates) within the +specified period. PERIODEXPR is a period expression with no report +interval. Examples: +'date:2016', 'date:thismonth', 'date:2/1-2/15', +'date:2021-07-27..nextquarter'. + + *'date2:PERIODEXPR'* +Match secondary dates within the specified period (independent of the +'--date2' flag). + + *'depth:N'* +Match (or display, depending on command) accounts at or above this +depth. + + *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg) +Match with a boolean combination of queries (which must be enclosed in +quotes). See Combining query terms below. + + *'note:REGEX'* +Match transaction notes (the part of the description right of '|', or +the whole description if there's no '|'). + + *'payee:REGEX'* +Match transaction payee/payer names (the part of the description left of +'|', or the whole description if there's no '|'). + + *'real:, real:0'* +Match real or virtual postings respectively. + + *'status:, status:!, status:*'* +Match unmarked, pending, or cleared transactions respectively. + + *'type:TYPECODES'* +Match by account type (see Declaring accounts > Account types). +'TYPECODES' is one or more of the single-letter account type codes +'ALERXCV', case insensitive. Note 'type:A' and 'type:E' will also match +their respective subtypes 'C' (Cash) and 'V' (Conversion). Certain +kinds of account alias can disrupt account types, see Rewriting accounts +> Aliases and account types. + + *'tag:REGEX[=REGEX]'* +Match by tag name, and optionally also by tag value. (To match only by +value, use 'tag:.=REGEX'.) + + When querying by tag, note that: + + * Accounts also inherit the tags of their parent accounts + * Postings also inherit the tags of their account and their + transaction + * Transactions also acquire the tags of their postings. + + (*'inacct:ACCTNAME'* +A special query term used automatically in hledger-web only: tells +hledger-web to show the transaction register for an account.) + + +File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries + +17.2 Combining query terms +========================== + +When given multiple space-separated query terms, most commands select +things which match: + + * any of the description terms AND + * any of the account terms AND + * any of the status terms AND + * all the other terms. + + The print command is a little different, showing transactions which: + + * match any of the description terms AND + * have any postings matching any of the positive account terms AND + * have no postings matching any of the negative account terms AND + * match all the other terms. + + We also support more complex boolean queries with the 'expr:' prefix. +This allows one to combine queries using one of three operators: AND, +OR, and NOT, where NOT is different syntax for 'not:'. + + Examples of such queries are: + + * Match transactions with 'cool' in the description AND with the 'A' + tag + + 'expr:"desc:cool AND tag:A"' + + * Match transactions NOT to the 'expenses:food' account OR with the + 'A' tag + + 'expr:"NOT expenses:food OR tag:A"' + + * Match transactions NOT involving the 'expenses:food' account OR + with the 'A' tag AND involving the 'expenses:drink' account. (the + AND is implicitly added by space-separation, following the rules + above) + + 'expr:"expenses:food OR (tag:A expenses:drink)"' + + +File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries + +17.3 Queries and command options +================================ + +Some queries can also be expressed as command-line options: 'depth:2' is +equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. +When you mix command options and query arguments, generally the +resulting query is their intersection. + + +File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries + +17.4 Queries and valuation +========================== + +When amounts are converted to other commodities in cost or value +reports, 'cur:' and 'amt:' match the old commodity symbol and the old +amount quantity, not the new ones (except in hledger 1.22.0 where it's +reversed, see #1625). + + +File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries + +17.5 Querying with account aliases +================================== + +When account names are rewritten with '--alias' or 'alias', note that +'acct:' will match either the old or the new account name. + + +File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries + +17.6 Querying with cost or value +================================ + +When amounts are converted to other commodities in cost or value +reports, note that 'cur:' matches the new commodity symbol, and not the +old one, and 'amt:' matches the new quantity, and not the old one. +Note: this changed in hledger 1.22, previously it was the reverse, see +the discussion at #1625. + + +File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top + +18 Pivoting +*********** + +Normally, hledger groups and sums amounts within each account. The +'--pivot FIELD' option substitutes some other transaction field for +account names, causing amounts to be grouped and summed by that field's +value instead. FIELD can be any of the transaction fields 'acct', +'status', 'code', 'desc', 'payee', 'note', or a tag name. When pivoting +on a tag and a posting has multiple values of that tag, only the first +value is displayed. Values containing 'colon:separated:parts' will be +displayed hierarchically, like account names. Multiple, colon-delimited +fields can be pivoted simultaneously, generating a hierarchical account +name. + + Some examples: + +2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe, kind: Lifetime + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + Hierarchical reports can be generated with multiple pivots: + +$ hledger balance Income:Dues --pivot kind:member + -2 EUR Lifetime:John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top + +19 Generating data +****************** + +hledger has several features for generating data, such as: + + * Periodic transaction rules can generate single or repeating + transactions following a template. These are usually dated in the + future, eg to help with forecasting. They are activated by the + '--forecast' option. + + * The balance command's '--budget' option uses these same periodic + rules to generate goals for the budget report. + + * Auto posting rules can generate extra postings on certain matched + transactions. They are always applied to forecast transactions; + with the '--auto' flag they are applied to transactions recorded in + the journal as well. + + * The '--infer-equity' flag infers missing conversion equity postings + from @/@@ costs. And the inverse '--infer-costs' flag infers + missing @/@@ costs from conversion equity postings. + + Generated data of this kind is temporary, existing only at report +time. But you can see it in the output of 'hledger print', and you can +save that to your journal, in effect converting it from temporary +generated data to permanent recorded data. This could be useful as a +data entry aid. + + If you are wondering what data is being generated and why, add the +'--verbose-tags' flag. In 'hledger print' output you will see extra +tags like 'generated-transaction', 'generated-posting', and 'modified' +on generated/modified data. Also, even without '--verbose-tags', +generated data always has equivalen hidden tags (with an underscore +prefix), so eg you could match generated transactions with +'tag:_generated-transaction'. + + +File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top + +20 Forecasting +************** + +Forecasting, or speculative future reporting, can be useful for +estimating future balances, or for exploring different future scenarios. + + The simplest and most flexible way to do it with hledger is to +manually record a bunch of future-dated transactions. You could keep +these in a separate 'future.journal' and include that with '-f' only +when you want to see them. + +* Menu: + +* --forecast:: +* Inspecting forecast transactions:: +* Forecast reports:: +* Forecast tags:: +* Forecast period in detail:: +* Forecast troubleshooting:: + + +File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting + +20.1 -forecast +============== + +There is another way: with the '--forecast' option, hledger can generate +temporary "forecast transactions" for reporting purposes, according to +periodic transaction rules defined in the journal. Each rule can +generate multiple recurring transactions, so by changing one rule you +can change many forecasted transactions. (These same rules can also +generate budget goals, described in Budgeting.) + + Forecast transactions usually start after ordinary transactions end. +By default, they begin after your latest-dated ordinary transaction, or +today, whichever is later, and they end six months from today. (The +exact rules are a little more complicated, and are given below.) + + This is the "forecast period", which need not be the same as the +report period. You can override it - eg to forecast farther into the +future, or to force forecast transactions to overlap your ordinary +transactions - by giving the -forecast option a period expression +argument, like '--forecast=..2099' or '--forecast=2023-02-15..'. Note +that the '=' is required. + + +File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting + +20.2 Inspecting forecast transactions +===================================== + +'print' is the best command for inspecting and troubleshooting forecast +transactions. Eg: + +~ monthly from 2022-12-20 rent + assets:bank:checking + expenses:rent $1000 + +$ hledger print --forecast --today=2023/4/21 +2023-05-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-06-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-07-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-08-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-09-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + Here there are no ordinary transactions, so the forecasted +transactions begin on the first occurence after today's date. (You +won't normally use '--today'; it's just to make these examples +reproducible.) + + +File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting + +20.3 Forecast reports +===================== + +Forecast transactions affect all reports, as you would expect. Eg: + +$ hledger areg rent --forecast --today=2023/4/21 +Transactions in expenses:rent and subaccounts: +2023-05-20 rent as:ba:checking $1000 $1000 +2023-06-20 rent as:ba:checking $1000 $2000 +2023-07-20 rent as:ba:checking $1000 $3000 +2023-08-20 rent as:ba:checking $1000 $4000 +2023-09-20 rent as:ba:checking $1000 $5000 + +$ hledger bal -M expenses --forecast --today=2023/4/21 +Balance changes in 2023-05-01..2023-09-30: + + || May Jun Jul Aug Sep +===============++=================================== + expenses:rent || $1000 $1000 $1000 $1000 $1000 +---------------++----------------------------------- + || $1000 $1000 $1000 $1000 $1000 + + +File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting + +20.4 Forecast tags +================== + +Forecast transactions generated by -forecast have a hidden tag, +'_generated-transaction'. So if you ever need to match forecast +transactions, you could use 'tag:_generated-transaction' (or just +'tag:generated') in a query. + + For troubleshooting, you can add the '--verbose-tags' flag. Then, +visible 'generated-transaction' tags will be added also, so you can view +them with the 'print' command. Their value indicates which periodic +rule was responsible. + + +File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting + +20.5 Forecast period, in detail +=============================== + +Forecast start/end dates are chosen so as to do something useful by +default in almost all situations, while also being flexible. Here are +(with luck) the exact rules, to help with troubleshooting: + + The forecast period starts on: + + * the later of + * the start date in the periodic transaction rule + * the start date in '--forecast''s argument + + * otherwise (if those are not available): the later of + * the report start date specified with '-b'/'-p'/'date:' + * the day after the latest ordinary transaction in the journal + + * otherwise (if none of these are available): today. + + The forecast period ends on: + + * the earlier of + * the end date in the periodic transaction rule + * the end date in '--forecast''s argument + + * otherwise: the report end date specified with '-e'/'-p'/'date:' + * otherwise: 180 days (~6 months) from today. + + +File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting + +20.6 Forecast troubleshooting +============================= + +When -forecast is not doing what you expect, one of these tips should +help: + + * Remember to use the '--forecast' option. + * Remember to have at least one periodic transaction rule in your + journal. + * Test with 'print --forecast'. + * Check for typos or too-restrictive start/end dates in your periodic + transaction rule. + * Leave at least 2 spaces between the rule's period expression and + description fields. + * Check for future-dated ordinary transactions suppressing forecasted + transactions. + * Try setting explicit report start and/or end dates with '-b', '-e', + '-p' or 'date:' + * Try adding the '-E' flag to encourage display of empty periods/zero + transactions. + * Try setting explicit forecast start and/or end dates with + '--forecast=START..END' + * Consult Forecast period, in detail, above. + * Check inside the engine: add '--debug=2' (eg). + + +File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top + +21 Budgeting +************ + +With the balance command's '--budget' report, each periodic transaction +rule generates recurring budget goals in specified accounts, and goals +and actual performance can be compared. See the balance command's doc +below. + + You can generate budget goals and forecast transactions at the same +time, from the same or different periodic transaction rules: 'hledger +bal -M --budget --forecast ...' + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Budgeting, Up: Top + +22 Cost reporting +***************** + +In some transactions - for example a currency conversion, or a purchase +or sale of stock - one commodity is exchanged for another. In these +transactions there is a conversion rate, also called the cost (when +buying) or selling price (when selling). In hledger docs we just say +"cost", for convenience; feel free to mentally translate to "conversion +rate" or "selling price" if helpful. + +* Menu: + +* Recording costs:: +* Reporting at cost:: +* Equity conversion postings:: +* Inferring equity conversion postings:: +* Combining costs and equity conversion postings:: +* Requirements for detecting equity conversion postings:: +* Infer cost and equity by default ?:: + + +File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting + +22.1 Recording costs +==================== + +We'll explore several ways of recording transactions involving costs. +These are also summarised at hledger Cookbook > Cost notation. + + Costs can be recorded explicitly in the journal, using the '@ +UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs: + + *Variant 1* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 ; $1.35 per euro (unit cost) + + *Variant 2* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 @@ $135 ; $135 total cost + + Typically, writing the unit cost (variant 1) is preferable; it can be +more effort, requiring more attention to decimal digits; but it reveals +the per-unit cost basis, and makes stock sales easier. + + Costs can also be left implicit, and hledger will infer the cost that +is consistent with a balanced transaction: + + *Variant 3* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 + + Here, hledger will attach a '@@ €100' cost to the first amount (you +can see it with 'hledger print -x'). This form looks convenient, but +there are downsides: + + * It sacrifices some error checking. For example, if you + accidentally wrote €10 instead of €100, hledger would not be able + to detect the mistake. + + * It is sensitive to the order of postings - if they were reversed, a + different entry would be inferred and reports would be different. + + * The per-unit cost basis is not easy to read. + + So generally this kind of entry is not recommended. You can make +sure you have none of these by using '-s' (strict mode), or by running +'hledger check balanced'. + + +File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting + +22.2 Reporting at cost +====================== + +Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's +-B/-basis/-cost flag), any amounts which have been annotated with costs +will be converted to their cost's commodity (in the report output). Ie +they will be displayed "at cost" or "at sale price". + + Some things to note: + + * Costs are attached to specific posting amounts in specific + transactions, and once recorded they do not change. This contrasts + with market prices, which are ambient and fluctuating. + + * Conversion to cost is performed before conversion to market value + (described below). + + +File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting + +22.3 Equity conversion postings +=============================== + +There is a problem with the entries above - they are not conventional +Double Entry Bookkeeping (DEB) notation, and because of the "magical" +transformation of one commodity into another, they cause an imbalance in +the Accounting Equation. This shows up as a non-zero grand total in +balance reports like 'hledger bse'. + + For most hledger users, this doesn't matter in practice and can +safely be ignored ! But if you'd like to learn more, keep reading. + + Conventional DEB uses an extra pair of equity postings to balance the +transaction. Of course you can do this in hledger as well: + + *Variant 4* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 + equity:conversion $135 + equity:conversion €-100 + + Now the transaction is perfectly balanced according to standard DEB, +and 'hledger bse''s total will not be disrupted. + + And, hledger can still infer the cost for cost reporting, but it's +not done by default - you must add the '--infer-costs' flag like so: + +$ hledger print --infer-costs +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 @@ €100 + assets:euros €100 + equity:conversion $135 + equity:conversion €-100 + +$ hledger bal --infer-costs -B + €-100 assets:dollars + €100 assets:euros +-------------------- + 0 + + Here are some downsides of this kind of entry: + + * The per-unit cost basis is not easy to read. + + * Instead of '-B' you must remember to type '-B --infer-costs'. + + * '--infer-costs' works only where hledger can identify the two + equity:conversion postings and match them up with the two + non-equity postings. So writing the journal entry in a particular + format becomes more important. More on this below. + + +File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting + +22.4 Inferring equity conversion postings +========================================= + +Can we go in the other direction ? Yes, if you have transactions +written with the @/@@ cost notation, hledger can infer the missing +equity postings, if you add the '--infer-equity' flag. Eg: + +2022-01-01 + assets:dollars -$135 + assets:euros €100 @ $1.35 + +$ hledger print --infer-equity +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 + equity:conversion:$-€:€ €-100 + equity:conversion:$-€:$ $135.00 + + The equity account names will be "equity:conversion:A-B:A" and +"equity:conversion:A-B:B" where A is the alphabetically first commodity +symbol. You can customise the "equity:conversion" part by declaring an +account with the 'V'/'Conversion' account type. + + +File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting + +22.5 Combining costs and equity conversion postings +=================================================== + +Finally, you can use both the @/@@ cost notation and equity postings at +the same time. This in theory gives the best of all worlds - preserving +the accounting equation, revealing the per-unit cost basis, and +providing more flexibility in how you write the entry: + + *Variant 5* + +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 @ $1.35 + + All the other variants above can (usually) be rewritten to this final +form with: + +$ hledger print -x --infer-costs --infer-equity + + Downsides: + + * This was added in hledger-1.29 and is still somewhat experimental. + + * The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it + will give a transaction balancing error. + + * The add command does not yet accept this kind of entry (#2056). + + * This is the most verbose form. + + +File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting + +22.6 Requirements for detecting equity conversion postings +========================================================== + +'--infer-costs' has certain requirements (unlike '--infer-equity', which +always works). It will infer costs only in transactions with: + + * Two non-equity postings, in different commodities. Their order is + significant: the cost will be added to the first of them. + + * Two postings to equity conversion accounts, next to one another, + which balance the two non-equity postings. This balancing is + checked to the same precision (number of decimal places) used in + the conversion posting's amount. Equity conversion accounts are: + + * any accounts declared with account type 'V'/'Conversion', or + their subaccounts + * otherwise, accounts named 'equity:conversion', 'equity:trade', + or 'equity:trading', or their subaccounts. + + And multiple such four-posting groups can coexist within a single +transaction. When '--infer-costs' fails, it does not infer a cost in +that transaction, and does not raise an error (ie, it infers costs where +it can). + + Reading variant 5 journal entries, combining cost notation and equity +postings, has all the same requirements. When reading such an entry +fails, hledger raises an "unbalanced transaction" error. + + +File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting + +22.7 Infer cost and equity by default ? +======================================= + +Should '--infer-costs' and '--infer-equity' be enabled by default ? Try +using them always, eg with a shell alias: + +alias h="hledger --infer-equity --infer-costs" + + and let us know what problems you find. + + +File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top + +23 Value reporting +****************** + +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), and/or to market value (using some market price on a +certain date). This is controlled by the '--value=TYPE[,COMMODITY]' +option, which will be described below. We also provide the simpler '-V' +and '-X COMMODITY' options, and often one of these is all you need: + +* Menu: + +* -V Value:: +* -X Value in specified commodity:: +* Valuation date:: +* Finding market price:: +* --infer-market-prices market prices from transactions:: +* Valuation commodity:: +* Simple valuation examples:: +* --value Flexible valuation:: +* More valuation examples:: +* Interaction of valuation and queries:: +* Effect of valuation on reports:: + + +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Value reporting + +23.1 -V: Value +============== + +The '-V/--market' flag converts amounts to market value in their default +_valuation commodity_, using the market prices in effect on the +_valuation date(s)_, if any. More on these in a minute. + + +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Value reporting + +23.2 -X: Value in specified commodity +===================================== + +The '-X/--exchange=COMM' option is like '-V', except you tell it which +currency you want to convert to, and it tries to convert everything to +that. + + +File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Value reporting + +23.3 Valuation date +=================== + +Market prices can change from day to day. hledger will use the prices +on a particular valuation date (or on more than one date). By default +hledger uses "end" dates for valuation. More specifically: + + * For single period reports (including normal print and register + reports): + * If an explicit report end date is specified, that is used + * Otherwise the latest transaction date or P directive date is + used (even if it's in the future) + + * For multiperiod reports, each period is valued on its last day. + + This can be customised with the -value option described below, which +can select either "then", "end", "now", or "custom" dates. (Note, this +has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key +always resets it to "end".) + + +File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting + +23.4 Finding market price +========================= + +To convert a commodity A to its market value in another commodity B, +hledger looks for a suitable market price (exchange rate) as follows, in +this order of preference: + + 1. A _declared market price_ or _inferred market price_: A's latest + market price in B on or before the valuation date as declared by a + P directive, or (with the '--infer-market-prices' flag) inferred + from costs. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 3. A _forward chain of market prices_: a synthetic price formed by + combining the shortest chain of "forward" (only 1 above) market + prices, leading from A to B. + + 4. _Any chain of market prices_: a chain of any market prices, + including both forward and reverse prices (1 and 2 above), leading + from A to B. + + There is a limit to the length of these price chains; if hledger +reaches that length without finding a complete chain or exhausting all +possibilities, it will give up (with a "gave up" message visible in +'--debug=2' output). That limit is currently 1000. + + Amounts for which no suitable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting + +23.5 -infer-market-prices: market prices from transactions +========================================================== + +Normally, market value in hledger is fully controlled by, and requires, +P directives in your journal. Since adding and updating those can be a +chore, and since transactions usually take place at close to market +value, why not use the recorded costs as additional market prices (as +Ledger does) ? Adding the '--infer-market-prices' flag to '-V', '-X' or +'--value' enables this. + + So for example, 'hledger bs -V --infer-market-prices' will get market +prices both from P directives and from transactions. If both occur on +the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Value reporting section carefully, and try adding +'--debug' or '--debug=2' to troubleshoot. + + '--infer-market-prices' can infer market prices from: + + * multicommodity transactions with explicit prices ('@'/'@@') + + * multicommodity transactions with implicit prices (no '@', two + commodities, unbalanced). (With these, the order of postings + matters. 'hledger print -x' can be useful for troubleshooting.) + + * multicommodity transactions with equity postings, if cost is + inferred with '--infer-costs'. + + There is a limitation (bug) currently: when a valuation commodity is +not specified, prices inferred with '--infer-market-prices' do not help +select a default valuation commodity, as 'P' prices would. So +conversion might not happen because no valuation commodity was detected +('--debug=2' will show this). To be safe, specify the valuation +commmodity, eg: + + * '-X EUR --infer-market-prices', not '-V --infer-market-prices' + * '--value=then,EUR --infer-market-prices', not '--value=then + --infer-market-prices' + + Signed costs and market prices can be confusing. For reference, here +is the current behaviour, since hledger 1.25. (If you think it should +work differently, see #1870.) + +2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + +2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + +2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + +2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + +2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + +2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each +day, the two transactions are considered equivalent). Here are the +market prices inferred for B: + +$ hledger -f- --infer-market-prices prices +P 2022-01-01 B A 1 +P 2022-01-01 B A 1.0 +P 2022-01-02 B A -1 +P 2022-01-02 B A -1.0 +P 2022-01-03 B A -1 +P 2022-01-03 B A -1.0 + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Value reporting + +23.6 Valuation commodity +======================== + +*When you specify a valuation commodity ('-X COMM' or '--value +TYPE,COMM'):* +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). + + *When you leave the valuation commodity unspecified ('-V' or '--value +TYPE'):* +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: + + 1. The price commodity from the latest P-declared market price for A + on or before valuation date. + + 2. The price commodity from the latest P-declared market price for A + on any date. (Allows conversion to proceed when there are inferred + prices before the valuation date.) + + 3. If there are no P directives at all (any commodity or date) and the + '--infer-market-prices' flag is used: the price commodity from the + latest transaction-inferred price for A on or before valuation + date. + + This means: + + * If you have P directives, they determine which commodities '-V' + will convert, and to what. + + * If you have no P directives, and use the '--infer-market-prices' + flag, costs determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Value reporting + +23.7 Simple valuation examples +============================== + +Here are some quick examples of '-V': + +; one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +; purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +; the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 + + How many euros do I have ? + +$ hledger -f t.j bal -N euros + €100 assets:euros + + What are they worth at end of nov 3 ? + +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date +specified, defaults to today) + +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Value reporting + +23.8 -value: Flexible valuation +=============================== + +'-V' and '-X' are special cases of the more general '--value' option: + + --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. + COMM is an optional commodity symbol. + Shows amounts converted to: + - default valuation commodity (or COMM) using market prices at posting dates + - default valuation commodity (or COMM) using market prices at period end(s) + - default valuation commodity (or COMM) using current market prices + - default valuation commodity (or COMM) using market prices at some date + + The TYPE part selects cost or value and valuation date: + +'--value=then' + + Convert amounts to their value in the default valuation commodity, + using market prices on each posting's date. +'--value=end' + + Convert amounts to their value in the default valuation commodity, + using market prices on the last day of the report period (or if + unspecified, the journal's end date); or in multiperiod reports, + market prices on the last day of each subperiod. +'--value=now' + + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). +'--value=YYYY-MM-DD' + + Convert amounts to their value in the default valuation commodity + using market prices on this date. + + To select a different valuation commodity, add the optional ',COMM' +part: a comma, then the target commodity's symbol. Eg: +*'--value=now,EUR'*. hledger will do its best to convert amounts to +this commodity, deducing market prices as described above. + + +File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting + +23.9 More valuation examples +============================ + +Here are some examples showing the effect of '--value', as seen with +'print': + +P 2000-01-01 A 1 B +P 2000-02-01 A 2 B +P 2000-03-01 A 3 B +P 2000-04-01 A 4 B + +2000-01-01 + (a) 1 A @ 5 B + +2000-02-01 + (a) 1 A @ 6 B + +2000-03-01 + (a) 1 A @ 7 B + + Show the cost of each posting: + +$ hledger -f- print --cost +2000-01-01 + (a) 5 B + +2000-02-01 + (a) 6 B + +2000-03-01 + (a) 7 B + + Show the value as of the last day of the report period (2000-02-29): + +$ hledger -f- print --value=end date:2000/01-2000/03 +2000-01-01 + (a) 2 B + +2000-02-01 + (a) 2 B + + With no report period specified, that shows the value as of the last +day of the journal (2000-03-01): + +$ hledger -f- print --value=end +2000-01-01 + (a) 3 B + +2000-02-01 + (a) 3 B + +2000-03-01 + (a) 3 B + + Show the current value (the 2000-04-01 price is still in effect +today): + +$ hledger -f- print --value=now +2000-01-01 + (a) 4 B + +2000-02-01 + (a) 4 B + +2000-03-01 + (a) 4 B + + Show the value on 2000/01/15: + +$ hledger -f- print --value=2000-01-15 +2000-01-01 + (a) 1 B + +2000-02-01 + (a) 1 B + +2000-03-01 + (a) 1 B + + +File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Value reporting + +23.10 Interaction of valuation and queries +========================================== + +When matching postings based on queries in the presence of valuation, +the following happens. + + 1. The query is separated into two parts: + 1. the currency ('cur:') or amount ('amt:'). + 2. all other parts. + + 2. The postings are matched to the currency and amount queries based + on pre-valued amounts. + 3. Valuation is applied to the postings. + 4. The postings are matched to the other parts of the query based on + post-valued amounts. + + See: 1625 + + +File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting + +23.11 Effect of valuation on reports +==================================== + +Here is a reference for how valuation is supposed to affect each part of +hledger's reports (and a glossary). (It's wide, you'll have to scroll +sideways.) It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. + +Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', +type '--cost' '--value=now' +------------------------------------------------------------------------------ +*print* +posting cost value at value at posting value at value +amounts report end date report or at + or today journal DATE/today + end +balance unchanged unchanged unchanged unchanged unchanged +assertions/assignments +*register* +starting cost value at valued at day value at value +balance report or each historical report or at +(-H) journal posting was made journal DATE/today + end end +starting cost value at valued at day value at value +balance day before each historical day before at +(-H) report or posting was made report or DATE/today +with journal journal +report start start +interval +posting cost value at value at posting value at value +amounts report or date report or at + journal journal DATE/today + end end +summary summarised value at sum of postings value at value +posting cost period in interval, period at +amounts ends valued at ends DATE/today +with interval start +report +interval +running sum/average sum/average sum/average of sum/average sum/average +total/averageof of displayed values of of + displayed displayed displayed displayed + values values values values +*balance +(bs, +bse, cf, +is)* +balance sums of value at value at posting value at value +changes costs report end date report or at + or today journal DATE/today + of sums of end of of + postings sums of sums + postings of + postings +budget like like like balance like like +amounts balance balance changes balances balance +(-budget) changes changes changes +grand sum of sum of sum of displayed sum of sum of +total displayed displayed valued displayed displayed + values values values values +*balance +(bs, +bse, cf, +is) with +report +interval* +starting sums of value at sums of values value at sums +balances costs of report of postings report of +(-H) postings start of before report start of postings + before sums of start at sums of before + report all respective all report + start postings posting dates postings start + before before + report report + start start +balance sums of same as sums of values balance value +changes costs of -value=end of postings in change in at +(bal, postings period at each DATE/today +is, bs in period respective period, of +-change, posting dates valued at sums +cf period of +-change) ends postings +end sums of same as sums of values period end value +balances costs of -value=end of postings from balances, at +(bal -H, postings before period valued at DATE/today +is -H, from start to period period of +bs, cf) before end at ends sums + report respective of + start to posting dates postings + period end +budget like like like balance like like +amounts balance balance changes/end balances balance +(-budget) changes/end changes/end balances changes/end + balances balances balances +row sums, sums, sums, averages sums, sums, +totals, averages averages of displayed averages averages +row of of values of of +averages displayed displayed displayed displayed +(-T, -A) values values values values +column sums of sums of sums of sums of sums +totals displayed displayed displayed values displayed of + values values values displayed + values +grand sum, sum, sum, average of sum, sum, +total, average of average of column totals average of average +grand column column column of +average totals totals totals column + totals + + '--cumulative' is omitted to save space, it works like '-H' but with +a zero starting balance. + + *Glossary:* + +_cost_ + + calculated using price(s) recorded in the transaction(s). +_value_ + + market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. +_report start_ + + the first day of the report period specified with -b or -p or + date:, otherwise today. +_report or journal start_ + + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. +_report end_ + + the last day of the report period specified with -e or -p or date:, + otherwise today. +_report or journal end_ + + the last day of the report period specified with -e or -p or date:, + otherwise the latest transaction date in the journal, otherwise + today. +_report interval_ + + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report's multi-period mode (whether showing one or many + subperiods). + + +File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Value reporting, Up: Top + +24 PART 4: COMMANDS +******************* + +* Menu: + +* Commands overview:: +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* demo:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* payees:: +* prices:: +* print:: +* register:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS + +24.1 Commands overview +====================== + +Here are the built-in commands: + +* Menu: + +* DATA ENTRY:: +* DATA CREATION:: +* DATA MANAGEMENT:: +* REPORTS FINANCIAL:: +* REPORTS VERSATILE:: +* REPORTS BASIC:: +* HELP:: +* ADD-ONS:: + + +File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview + +24.1.1 DATA ENTRY +----------------- + +These data entry commands are the only ones which can modify your +journal file. + + * add - add transactions using terminal prompts + * import - add new transactions from other files, eg CSV files + + +File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview + +24.1.2 DATA CREATION +-------------------- + + * close - generate balance-zeroing/restoring transactions + * rewrite - generate auto postings, like print -auto + + +File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview + +24.1.3 DATA MANAGEMENT +---------------------- + + * check - check for various kinds of error in the data + * diff - compare account transactions in two journal files + + +File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview + +24.1.4 REPORTS, FINANCIAL +------------------------- + + * aregister (areg) - show transactions in a particular account + * balancesheet (bs) - show assets, liabilities and net worth + * balancesheetequity (bse) - show assets, liabilities and equity + * cashflow (cf) - show changes in liquid assets + * incomestatement (is) - show revenues and expenses + + +File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview + +24.1.5 REPORTS, VERSATILE +------------------------- + + * balance (bal) - show balance changes, end balances, budgets, + gains.. + * print - show transactions or export journal data + * register (reg) - show postings in one or more accounts & running + total + * roi - show return on investments + + +File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview + +24.1.6 REPORTS, BASIC +--------------------- + + * accounts - show account names + * activity - show bar charts of posting counts per period + * codes - show transaction codes + * commodities - show commodity/currency symbols + * descriptions - show transaction descriptions + * files - show input file paths + * notes - show note parts of transaction descriptions + * payees - show payee parts of transaction descriptions + * prices - show market prices + * stats - show journal statistics + * tags - show tag names + * test - run self tests + + +File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview + +24.1.7 HELP +----------- + + * help - show the hledger manual with info/man/pager + * demo - show small hledger demos in the terminal + + +File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview + +24.1.8 ADD-ONS +-------------- + +And here are some typical add-on commands. Some of these are installed +by the hledger-install script. If installed, they will appear in +hledger's commands list: + + * ui - run hledger's terminal UI + * web - run hledger's web UI + * iadd - add transactions using a TUI (currently hard to build) + * interest - generate interest transactions + * stockquotes - download market prices from AlphaVantage + * Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + pijul, plot, and more.. + + Next, each command is described in detail, in alphabetical order. + + +File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS + +24.2 accounts +============= + +Show account names. + + This command lists account names. By default it shows all known +accounts, either used in transactions or declared with account +directives. + + With query arguments, only matched account names and account names +referenced by matched postings are shown. + + Or it can show just the used accounts ('--used'/'-u'), the declared +accounts ('--declared'/'-d'), the accounts declared but not used +('--unused'), the accounts used but not declared ('--undeclared'), or +the first account matched by an account name pattern, if any ('--find'). + + It shows a flat list by default. With '--tree', it uses indentation +to show the account hierarchy. In flat mode you can add '--drop N' to +omit the first few account name components. Account names can be +depth-clipped with 'depth:N' or '--depth N' or '-N'. + + With '--types', it also shows each account's type, if it's known. +(See Declaring accounts > Account types.) + + With '--positions', it also shows the file and line number of each +account's declaration, if any, and the account's overall declaration +order; these may be useful when troubleshooting account display order. + + With '--directives', it adds the 'account' keyword, showing valid +account directives which can be pasted into a journal file. This is +useful together with '--undeclared' when updating your account +declarations to satisfy 'hledger check accounts'. + + The '--find' flag can be used to look up a single account name, in +the same way that the 'aregister' command does. It returns the +alphanumerically-first matched account name, or if none can be found, it +fails with a non-zero exit code. + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + +$ hledger accounts --undeclared --directives >> $LEDGER_FILE +$ hledger check accounts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS + +24.3 activity +============= + +Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). With query arguments, it counts only matched transactions. + + Examples: + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** + + +File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS + +24.4 add +======== + +Prompt for transactions and add them to the journal. Any arguments will +be used as default inputs for the first N prompts. + + Many hledger users edit their journals directly with a text editor, +or generate them from CSV. For more interactive data entry, there is the +'add' command, which prompts interactively on the console for new +transactions, and appends them to the main journal file (which should be +in journal format). Existing transactions are not changed. This is one +of the few hledger commands that writes to the journal file (see also +'import'). + + To use it, just run 'hledger add' and follow the prompts. You can +add as many transactions as you like; when you are finished, enter '.' +or press control-d or control-c to exit. + + Features: + + * add tries to provide useful defaults, using the most similar (by + description) recent transaction (filtered by the query, if any) as + a template. + * You can also set the initial defaults with command line arguments. + * Readline-style edit keys can be used during data entry. + * The tab key will auto-complete whenever possible - accounts, + payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If + the input area is empty, it will insert the default value. + * If the journal defines a default commodity, it will be added to any + bare numbers entered. + * A parenthesised transaction code may be entered following a date. + * Comments and tags may be entered following a description or amount. + * If you make a mistake, enter '<' at any prompt to go one step + backward. + * Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see https://hledger.org/add.html for a detailed tutorial): + +$ hledger add +Adding transactions to journal file /src/hledger/examples/sample.journal +Any command line arguments will be used as defaults. +Use tab key to complete, readline keys to edit, enter to accept defaults. +An optional (CODE) may follow transaction dates. +An optional ; COMMENT may follow descriptions or amounts. +If you make a mistake, enter < at any prompt to go one step backward. +To end a transaction, enter . when prompted. +To quit, enter . at a date prompt or press control-d or control-c. +Date [2015/05/22]: +Description: supermarket +Account 1: expenses:food +Amount 1: $10 +Account 2: assets:checking +Amount 2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): . +2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + +Save this transaction to the journal ? [y]: +Saved. +Starting the next transaction (. or ctrl-D/ctrl-C to quit) +Date [2015/05/22]: $ + + On Microsoft Windows, the add command makes sure that no part of the +file path ends with a period, as that would cause problems (#1056). + + +File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS + +24.5 aregister +============== + +(areg) + + Show the transactions and running historical balance of a single +account, with each transaction displayed as one line. + + 'aregister' shows the overall transactions affecting a particular +account (and any subaccounts). Each report line represents one +transaction in this account. Transactions before the report start date +are always included in the running balance ('--historical' mode is +always on). + + This is a more "real world", bank-like view than the 'register' +command (which shows individual postings, possibly from multiple +accounts, not necessarily in historical mode). As a quick rule of +thumb: - use 'aregister' for reviewing and reconciling real-world +asset/liability accounts - use 'register' for reviewing detailed +revenues/expenses. + + 'aregister' requires one argument: the account to report on. You can +write either the full account name, or a case-insensitive regular +expression which will select the alphabetically first matched account. + + When there are multiple matches, the alphabetically-first choice can +be surprising; eg if you have 'assets:per:checking 1' and +'assets:biz:checking 2' accounts, 'hledger areg checking' would select +'assets:biz:checking 2'. It's just a convenience to save typing, so if +in doubt, write the full account name, or a distinctive substring that +matches uniquely. + + Transactions involving subaccounts of this account will also be +shown. 'aregister' ignores depth limits, so its final total will always +match a balance report with similar arguments. + + Any additional arguments form a query which will filter the +transactions shown. Note some queries will disturb the running balance, +causing it to be different from the account's real-world running +balance. + + An example: this shows the transactions and historical running +balance during july, in the first account whose name contains +"checking": + +$ hledger areg checking date:jul + + Each 'aregister' line item shows: + + * the transaction's date (or the relevant posting's date if + different, see below) + * the names of all the other account(s) involved in this transaction + (probably abbreviated) + * the total change to this account's balance from this transaction + * the account's historical running balance after this transaction. + + Transactions making a net change of zero are not shown by default; +add the '-E/--empty' flag to show them. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +'--align-all' flag. + + This command also supports the output destination and output format +options. The output formats supported are 'txt', 'csv', 'tsv', and +'json'. + +* Menu: + +* aregister and posting dates:: + + +File: hledger.info, Node: aregister and posting dates, Up: aregister + +24.5.1 aregister and posting dates +---------------------------------- + +aregister always shows one line (and date and amount) per transaction. +But sometimes transactions have postings with different dates. Also, +not all of a transaction's postings may be within the report period. To +resolve this, aregister shows the earliest of the transaction's date and +posting dates that is in-period, and the sum of the in-period postings. +In other words it will show a combined line item with just the earliest +date, and the running balance will (temporarily, until the transaction's +last posting) be inaccurate. Use 'register -H' if you need to see the +individual postings. + + There is also a '--txn-dates' flag, which filters strictly by +transaction date, ignoring posting dates. This too can cause an +inaccurate running balance. + + +File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS + +24.6 balance +============ + +(bal) + + Show accounts and their balances. + + 'balance' is one of hledger's oldest and most versatile commands, for +listing account balances, balance changes, values, value changes and +more, during one time period or many. Generally it shows a table, with +rows representing accounts, and columns representing periods. + + Note there are some higher-level variants of the 'balance' command +with convenient defaults, which can be simpler to use: 'balancesheet', +'balancesheetequity', 'cashflow' and 'incomestatement'. When you need +more control, then use 'balance'. + +* Menu: + +* balance features:: +* Simple balance report:: +* Balance report line format:: +* Filtered balance report:: +* List or tree mode:: +* Depth limiting:: +* Dropping top-level accounts:: +* Showing declared accounts:: +* Sorting by amount:: +* Percentages:: +* Multi-period balance report:: +* Balance change end balance:: +* Balance report types:: +* Budget report:: +* Balance report layout:: +* Useful balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +24.6.1 balance features +----------------------- + +Here's a quick overview of the 'balance' command's features, followed by +more detailed descriptions and examples. Many of these work with the +higher-level commands as well. + + 'balance' can show.. + + * accounts as a list ('-l') or a tree ('-t') + * optionally depth-limited ('-[1-9]') + * sorted by declaration order and name, or by amount + + ..and their.. + + * balance changes (the default) + * or actual and planned balance changes ('--budget') + * or value of balance changes ('-V') + * or change of balance values ('--valuechange') + * or unrealised capital gain/loss ('--gain') + * or postings count ('--count') + + ..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', 'tsv', 'json', and +(multi-period reports only:) 'html'. In 'txt' output in a +colour-supporting terminal, negative amounts are shown in red. + + The '--related'/'-r' flag shows the balance of the _other_ postings +in the transactions of the postings which would normally be shown. + + +File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance + +24.6.2 Simple balance report +---------------------------- + +With no arguments, 'balance' shows a list of all accounts and their +change of balance - ie, the sum of posting amounts, both inflows and +outflows - during the entire period of the journal. ("Simple" here +means just one column of numbers, covering a single period. You can +also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end +balance at the end of the journal period; more on this below. + + Accounts are sorted by declaration order if any, and then +alphabetically by account name. For instance (using +examples/sample.journal): + +$ hledger -f examples/sample.journal bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + Accounts with a zero balance (and no non-zero subaccounts, in tree +mode - see below) are hidden by default. Use '-E/--empty' to show them +(revealing 'assets:bank:checking' here): + +$ hledger -f examples/sample.journal bal -E + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + The total of the amounts displayed is shown as the last line, unless +'-N'/'--no-total' is used. + + +File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance + +24.6.3 Balance report line format +--------------------------------- + +For single-period balance reports displayed in the terminal (only), you +can use '--format FMT' to customise the format and content of each line. +Eg: + +$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string specifies the formatting applied to each +account/balance pair. It may contain any suitable text, with data +fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance + +24.6.4 Filtered balance report +------------------------------ + +You can show fewer accounts, a different time period, totals from +cleared transactions only, etc. by using query arguments or options to +limit the postings being matched. Eg: + +$ hledger -f examples/sample.journal bal --cleared assets date:200806 + $-2 assets:cash +-------------------- + $-2 + + +File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance + +24.6.5 List or tree mode +------------------------ + +By default, or with '-l/--flat', accounts are shown as a flat list with +their full names visible, as in the examples above. + + With '-t/--tree', the account hierarchy is shown, with subaccounts' +"leaf" names indented below their parent: + +$ hledger -f examples/sample.journal balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts +-------------------- + 0 + + Notes: + + * "Boring" accounts are combined with their subaccount for more + compact output, unless '--no-elide' is used. Boring accounts have + no balance of their own and just one subaccount (eg 'assets:bank' + and 'liabilities' above). + + * All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, + which requires explanation when sharing reports with + non-plaintextaccounting-users. A tree mode report's final total is + the sum of the top-level balances shown, not of all the balances + shown. + + * Each group of sibling accounts (ie, under a common parent) is + sorted separately. + + +File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance + +24.6.6 Depth limiting +--------------------- + +With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: +'-3') balance reports will show accounts only to the specified depth, +hiding the deeper subaccounts. This can be useful for getting an +overview without too much detail. + + Account balances at the depth limit always include the balances from +any deeper subaccounts (even in list mode). Eg, limiting to depth 1: + +$ hledger -f examples/sample.journal balance -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities +-------------------- + 0 + + +File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance + +24.6.7 Dropping top-level accounts +---------------------------------- + +You can also hide one or more top-level account name parts, using +'--drop NUM'. This can be useful for hiding repetitive top-level +account names: + +$ hledger -f examples/sample.journal bal expenses --drop 1 + $1 food + $1 supplies +-------------------- + $2 + + +File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance + +24.6.8 Showing declared accounts +-------------------------------- + +With '--declared', accounts which have been declared with an account +directive will be included in the balance report, even if they have no +transactions. (Since they will have a zero balance, you will also need +'-E/--empty' to see them.) + + More precisely, _leaf_ declared accounts (with no subaccounts) will +be included, since those are usually the more useful in reports. + + The idea of this is to be able to see a useful "complete" balance +report, even when you don't have transactions in all of your declared +accounts yet. + + +File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance + +24.6.9 Sorting by amount +------------------------ + +With '-S/--sort-amount', accounts with the largest (most positive) +balances are shown first. Eg: 'hledger bal expenses -MAS' shows your +biggest averaged monthly expenses first. When more than one commodity +is present, they will be sorted by the alphabetically earliest commodity +first, and then by subsequent commodities (if an amount is missing a +commodity, it is treated as 0). + + Revenues and liability balances are typically negative, however, so +'-S' shows these in reverse order. To work around this, you can add +'--invert' to flip the signs. (Or, use one of the higher-level reports, +which flip the sign automatically. Eg: 'hledger incomestatement -MAS'). + + +File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance + +24.6.10 Percentages +------------------- + +With '-%/--percent', balance reports show each account's value expressed +as a percentage of the (column) total. + + Note it is not useful to calculate percentages if the amounts in a +column have mixed signs. In this case, make a separate report for each +sign, eg: + +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` + + Similarly, if the amounts in a column have mixed commodities, convert +them to one commodity with '-B', '-V', '-X' or '--value', or make a +separate report for each commodity: + +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ + + +File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance + +24.6.11 Multi-period balance report +----------------------------------- + +With a report interval (set by the '-D/--daily', '-W/--weekly', +'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag), +'balance' shows a tabular report, with columns representing successive +time periods (and a title): + +$ hledger -f examples/sample.journal bal --quarterly income expenses -E +Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 +===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++--------------------------------- + || $-1 $1 0 0 + + Notes: + + * The report's start/end dates will be expanded, if necessary, to + fully encompass the displayed subperiods (so that the first and + last subperiods have the same duration as the others). + * Leading and trailing periods (columns) containing all zeroes are + not shown, unless '-E/--empty' is used. + * Accounts (rows) containing all zeroes are not shown, unless + '-E/--empty' is used. + * Amounts with many commodities are shown in abbreviated form, unless + '--no-elide' is used. _(experimental)_ + * Average and/or total columns can be added with the '-A/--average' + and '-T/--row-total' flags. + * The '--transpose' flag can be used to exchange rows and columns. + * The '--pivot FIELD' option causes a different transaction field to + be used as "account name". See PIVOTING. + + Multi-period reports with many periods can be too wide for easy +viewing in the terminal. Here are some ways to handle that: + + * Hide the totals row with '-N/--no-total' + * Convert to a single currency with '-V' + * Maximize the terminal window + * Reduce the terminal's font size + * View with a pager like less, eg: 'hledger bal -D --color=yes | less + -RS' + * Output as CSV and use a CSV viewer like visidata ('hledger bal -D + -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or + a spreadsheet ('hledger bal -D -o a.csv && open a.csv') + * Output as HTML and view with a browser: 'hledger bal -D -o a.html + && open a.html' + + +File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance + +24.6.12 Balance change, end balance +----------------------------------- + +It's important to be clear on the meaning of the numbers shown in +balance reports. Here is some terminology we use: + + A *_balance change_* is the net amount added to, or removed from, an +account during some period. + + An *_end balance_* is the amount accumulated in an account as of some +date (and some time, but hledger doesn't store that; assume end of day +in your timezone). It is the sum of previous balance changes. + + We call it a *_historical end balance_* if it includes all balance +changes since the account was created. For a real world account, this +means it will match the "historical record", eg the balances reported in +your bank statements or bank web UI. (If they are correct!) + + In general, balance changes are what you want to see when reviewing +revenues and expenses, and historical end balances are what you want to +see when reviewing or reconciling asset, liability and equity accounts. + + 'balance' shows balance changes by default. To see accurate +historical end balances: + + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the + journal covers the account's full lifetime. + + 2. Include all of of the account's prior postings in the report, by + not specifying a report start date, or by using the + '-H/--historical' flag. ('-H' causes report start date to be + ignored when summing postings.) + + +File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance + +24.6.13 Balance report types +---------------------------- + +The balance command is quite flexible; here is the full detail on how to +control what it reports. If the following seems complicated, don't +worry - this is for advanced reporting, and it does take time and +experimentation to get familiar with all the report modes. + + There are three important option groups: + + 'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] +...' + +* Menu: + +* Calculation type:: +* Accumulation type:: +* Valuation type:: +* Combining balance report types:: + + +File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types + +24.6.13.1 Calculation type +.......................... + +The basic calculation to perform for each table cell. It is one of: + + * '--sum' : sum the posting amounts (*default*) + * '--budget' : sum the amounts, but also show the budget goal amount + (for each account/period) + * '--valuechange' : show the change in period-end historical balance + values (caused by deposits, withdrawals, and/or market price + fluctuations) + * '--gain' : show the unrealised capital gain/loss, (the current + valued balance minus each amount's original cost) + * '--count' : show the count of postings + + +File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types + +24.6.13.2 Accumulation type +........................... + +How amounts should accumulate across report periods. Another way to say +it: which time period's postings should contribute to each cell's +calculation. It is one of: + + * '--change' : calculate with postings from column start to column + end, ie "just this column". Typically used to see + revenues/expenses. (*default for balance, incomestatement*) + + * '--cumulative' : calculate with postings from report start to + column end, ie "previous columns plus this column". Typically used + to show changes accumulated since the report's start date. Not + often used. + + * '--historical/-H' : calculate with postings from journal start to + column end, ie "all postings from before report start date until + this column's end". Typically used to see historical end balances + of assets/liabilities/equity. (*default for balancesheet, + balancesheetequity, cashflow*) + + +File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types + +24.6.13.3 Valuation type +........................ + +Which kind of value or cost conversion should be applied, if any, before +displaying the report. It is one of: + + * no valuation type : don't convert to cost or value (*default*) + * '--value=cost[,COMM]' : convert amounts to cost (then optionally to + some other commodity) + * '--value=then[,COMM]' : convert amounts to market value on + transaction dates + * '--value=end[,COMM]' : convert amounts to market value on period + end date(s) + (*default with '--valuechange', '--gain'*) + * '--value=now[,COMM]' : convert amounts to market value on today's + date + * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on + another date + + or one of the equivalent simpler flags: + + * '-B/--cost' : like -value=cost (though, note -cost and -value are + independent options which can both be used at once) + * '-V/--market' : like -value=end + * '-X COMM/--exchange COMM' : like -value=end,COMM + + See Cost reporting and Value reporting for more about these. + + +File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types + +24.6.13.4 Combining balance report types +........................................ + +Most combinations of these options should produce reasonable reports, +but if you find any that seem wrong or misleading, let us know. The +following restrictions are applied: + + * '--valuechange' implies '--value=end' + * '--valuechange' makes '--change' the default when used with the + 'balancesheet'/'balancesheetequity' commands + * '--cumulative' or '--historical' disables '--row-total/-T' + + For reference, here is what the combinations of accumulation and +valuation show: + +Valuation:>no valuation '--value= then' '--value= end' '--value= +Accumulation:v YYYY-MM-DD + /now' +----------------------------------------------------------------------------- +'--change'change in sum of period-end DATE-value + period posting-date value of of change in + market values change in period + in period period +'--cumulative'change from sum of period-end DATE-value + report start to posting-date value of of change + period end market values change from from report + from report report start start to + start to period to period end period end + end +'--historicalchange from sum of period-end DATE-value +/-H' journal start posting-date value of of change + to period end market values change from from journal + (historical end from journal journal start start to + balance) start to period to period end period end + end + + +File: hledger.info, Node: Budget report, Next: Balance report layout, Prev: Balance report types, Up: balance + +24.6.14 Budget report +--------------------- + +The '--budget' report type activates extra columns showing any budget +goals for each account and period. The budget goals are defined by +periodic transactions. This is useful for comparing planned and actual +income, expenses, time usage, etc. + + For example, you can take average monthly expenses in the common +expense categories to construct a minimal monthly budget: + +;; Budget +~ monthly + income $2000 + expenses:food $400 + expenses:bus $50 + expenses:movies $30 + assets:bank:checking + +;; Two months worth of expenses +2017-11-01 + income $1950 + expenses:food $396 + expenses:bus $49 + expenses:movies $30 + expenses:supplies $20 + assets:bank:checking + +2017-12-01 + income $2100 + expenses:food $412 + expenses:bus $53 + expenses:gifts $100 + assets:bank:checking + + You can now see a monthly budget report: + +$ hledger balance -M --budget +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + This is different from a normal balance report in several ways. +Currently: + + * Accounts with budget goals during the report period, and their + parents, are shown. + * Their subaccounts are not shown (regardless of the depth setting). + * Accounts without budget goals, if any, are aggregated and shown as + "". + * Amounts are always inclusive (subaccount-including), even in list + mode. + * After each actual amount, the corresponding goal amount and + percentage of goal reached are also shown, in square brackets. + + This means that the numbers displayed will not always add up! Eg +above, the 'expenses' actual amount includes the gifts and supplies +transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts +are not shown, as they have no budget amounts declared. + + This can be confusing. When you need to make things clearer, use the +'-E/--empty' flag, which will reveal all accounts including unbudgeted +ones, giving the full picture. Eg: + +$ hledger balance -M --budget --empty +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with '--cumulative': + +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + It's common to limit budgets/budget reports to just expenses + +hledger bal -M --budget expenses + + or just revenues and expenses (eg, using account types): + +hledger bal -M --budget type:rx + + It's also common to limit or convert them to a single currency +('cur:COMM' or '-X COMM [--infer-market-prices]'). If showing multiple +currencies, '--layout bare' or '--layout tall' can help. + + For more examples and notes, see Budgeting. + +* Menu: + +* Budget report start date:: +* Budgets and subaccounts:: +* Selecting budget goals:: +* Budget vs forecast:: + + +File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report + +24.6.14.1 Budget report start date +.................................. + +This might be a bug, but for now: when making budget reports, it's a +good idea to explicitly set the report's start date to the first day of +a reporting period, because a periodic rule like '~ monthly' generates +its transactions on the 1st of each month, and if your journal has no +regular transactions on the 1st, the default report start date could +exclude that budget goal, which can be a little surprising. Eg here the +default report period is just the day of 2020-01-15: + +~ monthly in 2020 + (expenses:food) $500 + +2020-01-15 + expenses:food $400 + assets:checking + +$ hledger bal expenses --budget +Budget performance in 2020-01-15: + + || 2020-01-15 +==============++============ + || $400 +--------------++------------ + || $400 + + To avoid this, specify the budget report's period, or at least the +start date, with '-b'/'-e'/'-p'/'date:', to ensure it includes the +budget goal transactions (periodic transactions) that you want. Eg, +adding '-b 2020/1/1' to the above: + +$ hledger bal expenses --budget -b 2020/1/1 +Budget performance in 2020-01-01..2020-01-15: + + || 2020-01-01..2020-01-15 +===============++======================== + expenses:food || $400 [80% of $500] +---------------++------------------------ + || $400 [80% of $500] + + +File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report + +24.6.14.2 Budgets and subaccounts +................................. + +You can add budgets to any account in your account hierarchy. If you +have budgets on both parent account and some of its children, then +budget(s) of the child account(s) would be added to the budget of their +parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicitly +means that budget for both 'expenses:personal' and 'expenses' is $1100. + + Transactions in 'expenses:personal:electronics' will be counted both +towards its $100 budget and $1100 of 'expenses:personal' , and +transactions in any other subaccount of 'expenses:personal' would be +counted towards only towards the budget of 'expenses:personal'. + + For example, let's consider these transactions: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + +2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + +2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + +2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in +'expenses:personal:electronics:upgrades' and 'expenses:personal:train +tickets', and since both of these accounts are without explicitly +defined budget, these transactions would be counted towards budgets of +'expenses:personal:electronics' and 'expenses:personal' accordingly: + +$ hledger balance --budget -M +Budget performance in 2019/01: + + || Jan +===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++------------------------------- + || 0 [ 0] + + And with '--empty', we can get a better picture of budget allocation +and consumption: + +$ hledger balance --budget -M --empty +Budget performance in 2019/01: + + || Jan +========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++------------------------------- + || 0 [ 0] + + +File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report + +24.6.14.3 Selecting budget goals +................................ + +The budget report evaluates periodic transaction rules to generate +special "goal transactions", which generate the goal amounts for each +account in each report subperiod. When troubleshooting, you can use +'print --forecast' to show these as forecasted transactions: + +$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated + + By default, the budget report uses all available periodic transaction +rules to generate goals. This includes rules with a different report +interval from your report. Eg if you have daily, weekly and monthly +periodic rules, all of these will contribute to the goals in a monthly +budget report. + + You can select a subset of periodic rules by providing an argument to +the '--budget' flag. '--budget=DESCPAT' will match all periodic rules +whose description contains DESCPAT, a case-insensitive substring (not a +regular expression or query). This means you can give your periodic +rules descriptions (remember that two spaces are needed), and then +select from multiple budgets defined in your journal. + + +File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report + +24.6.14.4 Budget vs forecast +............................ + +'hledger --forecast ...' and 'hledger balance --budget ...' are separate +features, though both of them use the periodic transaction rules defined +in the journal, and both of them generate temporary transactions for +reporting purposes ("forecast transactions" and "budget goal +transactions", respectively). You can use both features at the same +time if you want. Here are some differences between them, as of hledger +1.29: + + CLI: + + * -forecast is a general hledger option, usable with any command + * -budget is a 'balance' command option, usable only with that + command. + + Visibility of generated transactions: + + * forecast transactions are visible in any report, like ordinary + transactions + * budget goal transactions are invisible except for the goal amounts + they produce in -budget reports. + + Periodic transaction rules: + + * -forecast uses all available periodic transaction rules + * -budget uses all periodic rules ('--budget') or a selected subset + ('--budget=DESCPAT') + + Period of generated transactions: + + * -forecast generates forecast transactions + * from after the last regular transaction to the end of the + report period ('--forecast') + * or, during a specified period ('--forecast=PERIODEXPR') + * possibly further restricted by a period specified in the + periodic transaction rule + * and always restricted within the bounds of the report period + + * -budget generates budget goal transactions + * throughout the report period + * possibly restricted by a period specified in the periodic + transaction rule. + + +File: hledger.info, Node: Balance report layout, Next: Useful balance reports, Prev: Budget report, Up: balance + +24.6.15 Balance report layout +----------------------------- + +The '--layout' option affects how balance reports show multi-commodity +amounts and commodity symbols, which can improve readability. It can +also normalise the data for easy consumption by other programs. It has +four possible values: + + * '--layout=wide[,WIDTH]': commodities are shown on a single line, + optionally elided to WIDTH + * '--layout=tall': each commodity is shown on a separate line + * '--layout=bare': commodity symbols are in their own column, amounts + are bare numbers + * '--layout=tidy': data is normalised to easily-consumed "tidy" form, + with one row per data value + + Here are the '--layout' modes supported by each output format; note +only CSV output supports all of them: + +- txt csv html json sql +--------------------------------------- +wide Y Y Y +tall Y Y Y +bare Y Y Y +tidy Y + + Examples: + + * Wide layout. With many commodities, reports can be very wide: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + * Limited wide layout. A width limit reduces the width, but some + commodities will be hidden: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + * Tall layout. Each commodity gets a new line (may be different in + each column), and account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + * Bare layout. Commodity symbols are kept in one column, each + commodity gets its own report row, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + * Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + * Note: bare layout will sometimes display an extra row for the + no-symbol commodity, because of zero amounts (hledger treats zeroes + as commodity-less, usually). This can break 'hledger-bar' + confusingly (workaround: add a 'cur:' query to exclude the + no-symbol row). + + * Tidy layout produces normalised "tidy data", where every variable + has its own column and each row represents a single data point. + See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html + for more. This is the easiest kind of data for other software to + consume. Here's how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + +File: hledger.info, Node: Useful balance reports, Prev: Balance report layout, Up: balance + +24.6.16 Useful balance reports +------------------------------ + +Some frequently used 'balance' options/reports are: + + * 'bal -M revenues expenses' + Show revenues/expenses in each month. Also available as the + 'incomestatement' command. + + * 'bal -M -H assets liabilities' + Show historical asset/liability balances at each month end. Also + available as the 'balancesheet' command. + + * 'bal -M -H assets liabilities equity' + Show historical asset/liability/equity balances at each month end. + Also available as the 'balancesheetequity' command. + + * 'bal -M assets not:receivable' + Show changes to liquid assets in each month. Also available as the + 'cashflow' command. + + Also: + + * 'bal -M expenses -2 -SA' + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + * 'bal -M --budget expenses' + Show monthly expenses and budget goals. + + * 'bal -M --valuechange investments' + Show monthly change in market value of investment assets. + + * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert]' + Show top gainers [or losers] last week + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS + +24.7 balancesheet +================= + +(bs) + + This command displays a balance sheet, showing historical ending +balances of asset and liability accounts. (To see equity as well, use +the balancesheetequity command.) Amounts are shown with normal positive +sign, as in conventional financial statements. + + This report shows accounts declared with the 'Asset', 'Cash' or +'Liability' type (see account types). Or if no such accounts are +declared, it shows top-level accounts named 'asset' or 'liability' (case +insensitive, plurals allowed) and their subaccounts. + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance -H assets liabilities', but with +smarter account detection, and liabilities displayed with their sign +flipped. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS + +24.8 balancesheetequity +======================= + +(bse) + + This command displays a balance sheet, showing historical ending +balances of asset, liability and equity accounts. Amounts are shown +with normal positive sign, as in conventional financial statements. + + This report shows accounts declared with the 'Asset', 'Cash', +'Liability' or 'Equity' type (see account types). Or if no such +accounts are declared, it shows top-level accounts named 'asset', +'liability' or 'equity' (case insensitive, plurals allowed) and their +subaccounts. + + Example: + +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance -H assets liabilities equity', but +with smarter account detection, and liabilities/equity displayed with +their sign flipped. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS + +24.9 cashflow +============= + +(cf) + + This command displays a cashflow statement, showing the inflows and +outflows affecting "cash" (ie, liquid, easily convertible) assets. +Amounts are shown with normal positive sign, as in conventional +financial statements. + + This report shows accounts declared with the 'Cash' type (see account +types). Or if no such accounts are declared, it shows accounts + + * under a top-level account named 'asset' (case insensitive, plural + allowed) + * whose name contains some variation of 'cash', 'bank', 'checking' or + 'saving'. + + More precisely: all accounts matching this case insensitive regular +expression: + + '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)' + + and their subaccounts. + + An example cashflow report: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance assets not:fixed not:investment +not:receivable', but with smarter account detection. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS + +24.10 check +=========== + +Check for various kinds of errors in your data. + + hledger provides a number of built-in error checks to help prevent +problems in your data. Some of these are run automatically; or, you can +use this 'check' command to run them on demand, with no output and a +zero exit code if all is well. Specify their names (or a prefix) as +argument(s). + + Some examples: + +hledger check # basic checks +hledger check -s # basic + strict checks +hledger check ordereddates payees # basic + two other checks + + If you are an Emacs user, you can also configure flycheck-hledger to +run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available: + +* Menu: + +* Default checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: +* More about specific checks:: + + +File: hledger.info, Node: Default checks, Next: Strict checks, Up: check + +24.10.1 Default checks +---------------------- + +These checks are run automatically by (almost) all hledger commands: + + * *parseable* - data files are in a supported format, with no syntax + errors and no invalid include directives. + + * *autobalanced* - all transactions are balanced, after converting to + cost. Missing amounts and missing costs are inferred automatically + where possible. + + * *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: Default checks, Up: check + +24.10.2 Strict checks +--------------------- + +These additional checks are run when the '-s'/'--strict' (strict mode) +flag is used. Or, they can be run by giving their names as arguments to +'check': + + * *balanced* - all transactions are balanced after converting to + cost, without inferring missing costs. If conversion costs are + required, they must be explicit. + + * *accounts* - all account names used by transactions have been + declared + + * *commodities* - all commodity symbols used have been declared + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +24.10.3 Other checks +-------------------- + +These checks can be run only by giving their names as arguments to +'check'. They are more specialised and not desirable for everyone: + + * *ordereddates* - transactions are ordered by date within each file + + * *payees* - all payees used by transactions have been declared + + * *recentassertions* - all accounts with balance assertions have a + balance assertion within 7 days of their latest posting + + * *tags* - all tags used by transactions have been declared + + * *uniqueleafnames* - all account leaf names are unique + + +File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check + +24.10.4 Custom checks +--------------------- + +A few more checks are are available as separate add-on commands, in +https://github.com/simonmichael/hledger/tree/master/bin: + + * *hledger-check-tagfiles* - all tag values containing / (a forward + slash) exist as file paths + + * *hledger-check-fancyassertions* - more complex balance assertions + are passing + + You could make similar scripts to perform your own custom checks. +See: Cookbook -> Scripting. + + +File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check + +24.10.5 More about specific checks +---------------------------------- + +'hledger check recentassertions' will complain if any balance-asserted +account has postings more than 7 days after its latest balance +assertion. This aims to prevent the situation where you are regularly +updating your journal, but forgetting to check your balances against the +real world, then one day must dig back through months of data to find an +error. It assumes that adding a balance assertion requires/reminds you +to check the real-world balance. (That may not be true if you +auto-generate balance assertions from bank data; in that case, I +recommend to import transactions uncleared, and when you manually review +and clear them, also check the latest assertion against the real-world +balance.) + + +File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS + +24.11 close +=========== + +(equity) + + Generate transactions which transfer account balances to and/or from +another account (typically equity). This can be useful for migrating +balances to a new journal file, or for merging earnings into equity at +end of accounting period. + + By default, it prints a transaction that zeroes out ALE accounts +(asset, liability, equity accounts; this requires account types to be +configured); or if ACCTQUERY is provided, the accounts matched by that. + + _(experimental)_ + + This command has four main modes, corresponding to the most common +use cases: + + 1. With '--close' (default), it prints a "closing balances" + transaction that zeroes out ALE (asset, liability, equity) accounts + by default (this requires account types to be inferred or + declared); or, the accounts matched by the provided ACCTQUERY + arguments. + + 2. With '--open', it prints an opposite "opening balances" transaction + that restores those balances from zero. This is similar to + Ledger's equity command. + + 3. With '--migrate', it prints both the closing and opening + transactions. This is the preferred way to migrate balances to a + new file: run 'hledger close --migrate', add the closing + transaction at the end of the old file, and add the opening + transaction at the start of the new file. The matching + closing/opening transactions cancel each other out, preserving + correct balances during multi-file reporting. + + 4. With '--retain', it prints a "retain earnings" transaction that + transfers RX (revenue and expense) balances to 'equity:retained + earnings'. Businesses traditionally do this at the end of each + accounting period; it is less necessary with computer-based + accounting, but it could still be useful if you want to see the + accounting equation (A=L+E) satisfied. + + In all modes, the defaults can be overridden: + + * the transaction descriptions can be changed with + '--close-desc=DESC' and '--open-desc=DESC' + * the account to transfer to/from can be changed with + '--close-acct=ACCT' and '--open-acct=ACCT' + * the accounts to be closed/opened can be changed with 'ACCTQUERY' + (account query arguments). + * the closing/opening dates can be changed with '-e DATE' (a report + end date) + + By default just one destination/source posting will be used, with its +amount left implicit. With '--x/--explicit', the amount will be shown +explicitly, and if it involves multiple commodities, a separate posting +will be generated for each of them (similar to 'print -x'). + + With '--show-costs', any amount costs are shown, with separate +postings for each cost. This is currently the best way to view +investment lots. If you have many currency conversion or investment +transactions, it can generate very large journal entries. + + With '--interleaved', each individual transfer is shown with source +and destination postings next to each other. This could be useful for +troubleshooting. + + The default closing date is yesterday, or the journal's end date, +whichever is later. You can change this by specifying a report end date +with '-e'. The last day of the report period will be the closing date, +eg '-e 2024' means "close on 2023-12-31". The opening date is always +the day after the closing date. + +* Menu: + +* close and balance assertions:: +* Example retain earnings:: +* Example migrate balances to a new file:: +* Example excluding closing/opening transactions:: + + +File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Up: close + +24.11.1 close and balance assertions +------------------------------------ + +Balance assertions will be generated, verifying that the accounts have +been reset to zero (and then restored to their previous balances, if +there is an opening transaction). + + These provide useful error checking, but you can ignore them +temporarily with '-I', or remove them if you prefer. + + You probably should avoid filtering transactions by status or +realness ('-C', '-R', 'status:'), or generating postings ('--auto'), +with this command, since the balance assertions would depend on these. + + Note custom posting dates spanning the file boundary will disrupt the +balance assertions: + +2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve that you can transfer the money to and from a temporary +account, in effect splitting the multi-day transaction into two +single-day transactions: + +; in 2022.journal: +2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + +; in 2023.journal: +2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + +File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close + +24.11.2 Example: retain earnings +-------------------------------- + +Record 2022's revenues/expenses as retained earnings on 2022-12-31, +appending the generated transaction to the journal: + +$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + Note 2022's income statement will now show only zeroes, because +revenues and expenses have been moved entirely to equity. To see them +again, you could exclude the retain transaction: + +$ hledger -f 2022.journal is not:desc:'retain earnings' + + +File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close + +24.11.3 Example: migrate balances to a new file +----------------------------------------------- + +Close assets/liabilities/equity on 2022-12-31 and re-open them on +2023-01-01: + +$ hledger close --migrate -f 2022.journal -p 2022 +# copy/paste the closing transaction to the end of 2022.journal +# copy/paste the opening transaction to the start of 2023.journal + + Now 2022's balance sheet will show only zeroes, indicating a balanced +accounting equation. (Unless you are using @/@@ notation - in that +case, try adding -infer-equity.) To see the end-of-year balances again, +you could exclude the closing transaction: + +$ hledger -f 2022.journal bs not:desc:'closing balances' + + +File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close + +24.11.4 Example: excluding closing/opening transactions +------------------------------------------------------- + +When combining many files for multi-year reports, the closing/opening +transactions cause some noise in transaction-oriented reports like +'print' and 'register'. You can exclude them as shown above, but +'not:desc:...' is not ideal as it depends on consistent descriptions; +also you will want to avoid excluding the very first opening +transaction, which could be awkward. Here is one alternative, using +tags: + + Add 'clopen:' tags to all opening/closing balances transactions +except the first, like this: + +; 2021.journal +2021-06-01 first opening balances +... +2021-12-31 closing balances ; clopen:2022 +... + +; 2022.journal +2022-01-01 opening balances ; clopen:2022 +... +2022-12-31 closing balances ; clopen:2023 +... + +; 2023.journal +2023-01-01 opening balances ; clopen:2023 +... + + Now, assuming a combined journal like: + +; all.journal +include 2021.journal +include 2022.journal +include 2023.journal + + The 'clopen:' tag can exclude all but the first opening transaction. +To show a clean multi-year checking register: + +$ hledger -f all.journal areg checking not:tag:clopen + + And the year values allow more precision. To show 2022's year-end +balance sheet: + +$ hledger -f all.journal bs -e2023 not:tag:clopen=2023 + + +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS + +24.12 codes +=========== + +List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction's code field, in +the order transactions were parsed. The transaction code is an optional +value written in parentheses between the date and description, often +used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty +codes will not be shown by default. With the '-E'/'--empty' flag, they +will be printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + +2022/1/1 (123) Supermarket + Food $5.00 + Checking + +2022/1/2 (124) Post Office + Postage $8.32 + Checking + +2022/1/3 Supermarket + Food $11.23 + Checking + +2022/1/4 (126) Post Office + Postage $3.21 + Checking + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + +126 + + +File: hledger.info, Node: commodities, Next: demo, Prev: codes, Up: PART 4 COMMANDS + +24.13 commodities +================= + +List all commodity/currency symbols used or declared in the journal. + + +File: hledger.info, Node: demo, Next: descriptions, Prev: commodities, Up: PART 4 COMMANDS + +24.14 demo +========== + +Play demos of hledger usage in the terminal, if asciinema is installed. + + Run this command with no argument to list the demos. To play a demo, +write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/-speed SPEED option to set your preferred playback speed, +eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. +The default speed is 2x. + + Other asciinema options can be added following a double dash, eg '-- +-i.1' to limit pauses or '-- -h' to list asciinema's other options. + + During playback, several keys are available: SPACE to pause/unpause, +. to step forward (while paused), CTRL-c quit. + + Examples: + +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo at default speed (2x) +$ hledger demo install -s4 # play the "install" demo at 4x speed + + +File: hledger.info, Node: descriptions, Next: diff, Prev: demo, Up: PART 4 COMMANDS + +24.15 descriptions +================== + +List the unique descriptions that appear in transactions. + + This command lists the unique descriptions that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. + + Example: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS + +24.16 diff +========== + +Compares a particular account's transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + + More precisely, for each posting affecting this account in either +file, it looks for a corresponding posting in the other file which posts +the same amount to the same account (ignoring date, description, etc.) +Since postings not transactions are compared, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This is useful eg if you have downloaded an account's transactions +from your bank (eg as CSV data). When hledger and your bank disagree +about the account balance, you can compare the bank data with your +journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS + +24.17 files +=========== + +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + + +File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS + +24.18 help +========== + +Show the hledger user manual in the terminal, with 'info', 'man', or a +pager. With a TOPIC argument, open it at that topic if possible. TOPIC +can be any heading in the manual, or a heading prefix, case insensitive. +Eg: 'commands', 'print', 'forecast', 'journal', 'amount', '"auto +postings"'. + + This command shows the hledger manual built in to your hledger +version. It can be useful when offline, or when you prefer the terminal +to a web browser, or when the appropriate hledger manual or viewing +tools are not installed on your system. + + By default it chooses the best viewer found in $PATH, trying (in this +order): 'info', 'man', '$PAGER', 'less', 'more'. You can force the use +of info, man, or a pager with the '-i', '-m', or '-p' flags, If no +viewer can be found, or the command is run non-interactively, it just +prints the manual to stdout. + + If using 'info', note that version 6 or greater is needed for TOPIC +lookup. If you are on mac you will likely have info 4.8, and should +consider installing a newer version, eg with 'brew install texinfo' +(#1770). + + Examples + +$ hledger help --help # show how the help command works +$ hledger help # show the hledger manual with info, man or $PAGER +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help -m journal # show it with man, even if info is installed + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS + +24.19 import +============ + +Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. + + This command may append new transactions to the main journal file +(which should be in journal format). Existing transactions are not +changed. This is one of the few hledger commands that writes to the +journal file (see also 'add'). + + Unlike other hledger commands, with 'import' the journal file is an +output file, and will be modified, though only by appending (existing +data will not be changed). The input files are specified as arguments, +so to import one or more CSV files to your main journal, you will run +'hledger import bank.csv' or perhaps 'hledger import *.csv'. + + Note you can import from any file format, though CSV files are the +most common import source, and these docs focus on that case. + +* Menu: + +* Deduplication:: +* Import testing:: +* Importing balance assignments:: +* Commodity display styles:: + + +File: hledger.info, Node: Deduplication, Next: Import testing, Up: import + +24.19.1 Deduplication +--------------------- + +'import' does _time-based deduplication_, to detect only the new +transactions since the last successful import. (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 downloaded data, which may overlap with +previous downloads. Eg if every week (or every day) you download a +bank's last three months of CSV data, you can safely run 'hledger import +thebank.csv' each time and only new transactions will be imported. + + 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.FILE" file in FILE's directory (after a +succesful import). + + 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. + + Related: CSV > Working with CSV > Deduplicating, importing. + + +File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import + +24.19.2 Import testing +---------------------- + +With '--dry-run', the transactions that will be imported are printed to +the terminal, without updating your journal or state files. The output +is valid journal format, like the print command, so you can re-parse it. +Eg, to see any importable transactions which CSV rules have not +categorised: + +$ hledger import --dry bank.csv | hledger -f- -I print unknown + + or (live updating): + +$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' + + Note: when importing from multiple files at once, it's currently +possible for some .latest files to be updated successfully, while the +actual import fails because of a problem in one of the files, leaving +them out of sync (and causing some transactions to be missed). To +prevent this, do a -dry-run first and fix any problems before the real +import. + + +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import + +24.19.3 Importing balance assignments +------------------------------------- + +Entries added by import will have their posting amounts made explicit +(like 'hledger print -x'). This means that any balance assignments in +imported files must be evaluated; but, imported files don't get to see +the main file's account balances. As a result, importing entries with +balance assignments (eg from an institution that provides only balances +and not posting amounts) will probably generate incorrect posting +amounts. To avoid this problem, use print instead of import: + +$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE + + (If you think import should leave amounts implicit like print does, +please test it and send a pull request.) + + +File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import + +24.19.4 Commodity display styles +-------------------------------- + +Imported amounts will be formatted according to the canonical commodity +styles (declared or inferred) in the main journal file. + + +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS + +24.20 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', 'tsv', 'html', +and (experimental) 'json'. + + +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS + +24.21 notes +=========== + +List the unique notes that appear in transactions. + + This command lists the unique notes that appear in transactions, in +alphabetic order. You can add a query to select a subset of +transactions. The note is the part of the transaction description after +a | character (or if there is no |, the whole description). + + Example: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS + +24.22 payees +============ + +List the unique payee/payer names that appear in transactions. + + This command lists unique payee/payer names which have been declared +with payee directives (-declared), used in transaction descriptions +(-used), or both (the default). + + The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). + + You can add query arguments to select a subset of transactions. This +implies -used. + + Example: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS + +24.23 prices +============ + +Print the market prices declared with P directives. With +-infer-market-prices, also show any additional prices inferred from +costs. With -show-reverse, also show additional prices inferred by +reversing known prices. + + Price amounts are always displayed with their full precision, except +for reverse prices which are limited to 8 decimal digits. + + Prices can be filtered by a date:, cur: or amt: query. + + Generally if you run this command with -infer-market-prices +-show-reverse, it will show the same prices used internally to calculate +value reports. But if in doubt, you can inspect those directly by +running the value report with -debug=2. + + +File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS + +24.24 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). + + 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/regenerate your journal you should take care to also copy +over the directives and inter-transaction comments. + + Eg: + +$ hledger print -f examples/sample.journal date:200806 +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 + +* Menu: + +* print explicitness:: +* print amount style:: +* print parseability:: +* print other features:: +* print output format:: + + +File: hledger.info, Node: print explicitness, Next: print amount style, Up: print + +24.24.1 print explicitness +-------------------------- + +Normally, whether posting amounts are implicit or explicit is preserved. +For example, when an amount is omitted in the journal, it will not +appear in the output. Similarly, if a conversion cost is implied but +not written, it will not appear in the output. + + You can use the '-x'/'--explicit' flag to force explicit display of +all amounts and costs. This 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'. + + The '-x'/'--explicit' flag will cause any postings with a +multi-commodity amount (which can arise when a multi-commodity +transaction has an implicit amount) to be split into multiple +single-commodity postings, keeping the output parseable. + + +File: hledger.info, Node: print amount style, Next: print parseability, Prev: print explicitness, Up: print + +24.24.2 print amount style +-------------------------- + +Amounts are shown right-aligned within each transaction (but not aligned +across all transactions; you can do that with ledger-mode in Emacs). + + Amounts will be (mostly) normalised to their commodity display style: +their symbol placement, decimal mark, and digit group marks will be made +consistent. By default, decimal digits are shown as they are written in +the journal. + + With the '--round' option, 'print' will try increasingly hard to +display decimal digits according to the commodity display styles: + + * '--round=none' show amounts with original precisions (default) + * '--round=soft' add/remove decimal zeros in amounts (except costs) + * '--round=hard' round amounts (except costs), possibly hiding + significant digits + * '--round=all' round all amounts and costs + + 'soft' is good for non-lossy cleanup, formatting amounts more +consistently where it's safe to do so. + + 'hard' and 'all' can cause 'print' to show invalid unbalanced journal +entries; they may be useful eg for stronger cleanup, with manual fixups +when needed. + + +File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print + +24.24.3 print parseability +-------------------------- + +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 (though the same can be achieved with 'expr:' queries +now): + +# 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: + + * Value reporting 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. + + +File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print + +24.24.4 print, other features +----------------------------- + +With '-B'/'--cost', amounts with costs are shown converted to cost. + + With '--new', print shows 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.) + + With '-m DESC'/'--match=DESC', print shows one recent transaction +whose description is most similar to DESC. DESC should contain at least +two characters. If there is no similar-enough match, no transaction +will be shown and the program exit code will be non-zero. + + +File: hledger.info, Node: print output format, Prev: print other features, Up: print + +24.24.5 print output format +--------------------------- + +This command also supports the output destination and output format +options The output formats supported are 'txt', 'beancount', 'csv', +'tsv', 'json' and 'sql'. + + _Experimental:_ The 'beancount' format tries to produce +Beancount-compatible output, as follows: + + * Transaction and postings with unmarked status are converted to + cleared ('*') status. + * Transactions' payee and note are backslash-escaped and + double-quote-escaped and wrapped in double quotes. + * Transaction tags are copied to Beancount #tag format. + * Commodity symbols are converted to upper case, and a small number + of currency symbols like '$' are converted to the corresponding + currency names. + * Account name parts are capitalised and unsupported characters are + replaced with '-'. If an account name part does not begin with a + letter, or if the first part is not Assets, Liabilities, Equity, + Income, or Expenses, an error is raised. (Use '--alias' options to + bring your accounts into compliance.) + * An 'open' directive is generated for each account used, on the + earliest transaction date. + + Some limitations: + + * Balance assertions are removed. + * Balance assignments become missing amounts. + * Virtual and balanced virtual postings become regular postings. + * Directives are not converted. + + Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS + +24.25 register +============== + +(reg) + + Show postings and their running total. + + The register command displays matched postings, across all accounts, +in date order, with their running total or running historical balance. +(See also the 'aregister' command, which shows matched transactions in a +specific account.) + + register normally shows line per posting, but note that +multi-commodity amounts will occupy multiple lines (one line per +commodity). + + It is typically used with a query selecting a particular account, to +see that account's activity: + +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + With '--date2', it shows and sorts by secondary date instead. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +'--align-all' flag. + + The '--historical'/'-H' flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + The '--depth' option limits the amount of sub-account detail +displayed. + + The '--average'/'-A' flag shows the running average posting amount +instead of the running total (so, the final number displayed is the +average for the whole report period). This flag implies '--empty' (see +below). It is affected by '--historical'. It works best when showing +just one account and one commodity. + + The '--related'/'-r' flag shows the _other_ postings in the +transactions of the postings which would normally be shown. + + The '--invert' flag negates all amounts. For example, it can be used +on an income account where amounts are normally displayed as negative +numbers. It's also useful to show postings on the checking account +together with the related account: + +$ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: + +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, +are not shown by default; use the '--empty'/'-E' flag to see them: + +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The '--depth' +option helps with this, causing subaccounts to be aggregated: + +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates +these will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. + + With '-m DESC'/'--match=DESC', register does a fuzzy search for one +recent posting whose description is most similar to DESC. DESC should +contain at least two characters. If there is no similar-enough match, +no posting will be shown and the program exit code will be non-zero. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +24.25.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', 'tsv', and +(experimental) 'json'. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS + +24.26 rewrite +============= + +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +$ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +24.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 + +24.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 + +24.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: PART 4 COMMANDS + +24.27 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, also known as money-weighted rate of return) and time-weighted +rate of return (TWR) for your investments for the time period requested. +IRR is always annualized due to the way it is computed, but TWR is +reported both as a rate over the chosen reporting period and as an +annual rate. + + Price directives will be taken into account if you supply appropriate +'--cost' or '--value' flags (see VALUATION). + + Note, in some cases this report can fail, for these reasons: + + * Error (NotBracketed): No solution for Internal Rate of Return + (IRR). Possible causes: IRR is huge (>1000000%), balance of + investment becomes negative at some point in time. + * Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or + converges too slowly. + + Examples: + + * Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger + + * Cookbook > Return on Investment: https://hledger.org/roi.html + +* Menu: + +* Spaces and special characters in --inv and --pnl:: +* Semantics of --inv and --pnl:: +* IRR and TWR explained:: + + +File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi + +24.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 + +24.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 + +24.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, and +the time between them. Investment at a particular fixed interest rate +is going to give you more interest than the same amount invested at the +same interest rate, but made later in time. 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, +so your IRR will be smaller. And if you are adding to your investment, +you will receive bigger absolute gains, which will be a bigger +percentage of your initial investment, so your IRR will be larger. + + 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 +account for the effect of your in-flows and out-flows, but unlike IRR it +will try to compute the true rate of return of the underlying asset, +compensating for the effect that deposits and withdrawas have on the +apparent rate of growth of your investment. + + 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, and make TWR less sensitive than IRR to the effects of +cash in-flows and out-flows. + + References: + + * Explanation of rate of return + * Explanation of IRR + * Explanation of TWR + * IRR vs TWR + * Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS + +24.28 stats +=========== + +Show journal and performance statistics. + + The stats command displays summary information for the whole journal, +or a matched part of it. With a reporting interval, it shows a report +for each report period. + + At the end, it shows (in the terminal) the overall run time and +number of transactions processed per second. Note these are approximate +and will vary based on machine, current load, data size, hledger +version, haskell lib versions, GHC version.. but they may be of +interest. The 'stats' command's run time is similar to that of a +single-column balance report. + + Example: + +$ hledger stats -f examples/1000x1000x10.journal +Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal +Included files : +Transactions span : 2000-01-01 to 2002-09-27 (1000 days) +Last transaction : 2002-09-26 (6995 days ago) +Transactions : 1000 (1.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) +Market prices : 1000 (A) + +Run time : 0.12 s +Throughput : 8342 txns/s + + This command supports the -o/-output-file option (but not +-O/-output-format selection). + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS + +24.29 tags +========== + +List the tags used in the journal, or their values. + + This command lists the tag names used in the journal, whether on +transactions, postings, or account declarations. + + With a TAGREGEX argument, only tag names matching this regular +expression (case insensitive, infix matched) are shown. + + With QUERY arguments, only transactions and accounts matching this +query are considered. If the query involves transaction fields (date:, +desc:, amt:, ...), the search is restricted to the matched transactions +and their accounts. + + With the -values flag, the tags' unique non-empty values are listed +instead. With -E/-empty, blank/empty values are also shown. + + With -parsed, tags or values are shown in the order they were parsed, +with duplicates included. (Except, tags from account declarations are +always shown first.) + + Tip: remember, accounts also acquire tags from their parents, +postings also acquire tags from their account and transaction, +transactions also acquire tags from their postings. + + +File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS + +24.30 test +========== + +Run built-in unit tests. + + This command runs the unit tests built in to hledger and hledger-lib, +printing the results on stdout. If any test fails, the exit code will +be non-zero. + + This is mainly used by hledger developers, but you can also use it to +sanity-check the installed hledger executable on your platform. All +tests are expected to pass - if you ever see a failure, please report as +a bug! + + This command also accepts tasty test runner options, written after a +- (double hyphen). Eg to run only the tests in Hledger.Data.Amount, +with ANSI colour codes disabled: + +$ hledger test -- -pData.Amount --color=never + + For help on these, see https://github.com/feuerbach/tasty#options +('-- --help' currently doesn't show them). + + +File: hledger.info, Node: PART 5 COMMON TASKS, Next: BUGS, Prev: PART 4 COMMANDS, Up: Top + +25 PART 5: COMMON TASKS +*********************** + +Here are some quick examples of how to do some basic tasks with hledger. + +* Menu: + +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting LEDGER_FILE:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file:: + + +File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS + +25.1 Getting help +================= + +Here's how to list commands and view options and command docs: + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version's manual in several formats by +using the help command. Eg: + +$ hledger help # show the hledger manual with info, man or $PAGER (best available) +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit +https://hledger.org. Chat and mail list support and discussion archives +can be found at https://hledger.org/support. + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS + +25.2 Constructing command lines +=============================== + +hledger has a flexible command line interface. We strive to keep it +simple and ergonomic, but if you run into one of the sharp edges +described in OPTIONS, here are some tips that might help: + + * command-specific options must go after the command (it's fine to + put common options there too: 'hledger CMD OPTS ARGS') + * running add-on executables directly simplifies command line parsing + ('hledger-ui OPTS ARGS') + * enclose "problematic" args in single quotes + * if needed, also add a backslash to hide regular expression + metacharacters from the shell + * to see how a misbehaving command line is being parsed, add + '--debug=2'. + + +File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: PART 5 COMMON TASKS + +25.3 Starting a journal file +============================ + +hledger looks for your accounting data in a journal file, +'$HOME/.hledger.journal' by default: + +$ hledger stats +The hledger journal file "/Users/simon/.hledger.journal" was not found. +Please create it first, eg with "hledger add" or a text editor. +Or, specify an existing journal file with -f or LEDGER_FILE. + + You can override this by setting the 'LEDGER_FILE' environment +variable (see below). 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 2023.journal +$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile +$ source ~/.profile +$ hledger stats +Main file : /Users/simon/finance/2023.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 LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: PART 5 COMMON TASKS + +25.4 Setting LEDGER_FILE +======================== + +How to set 'LEDGER_FILE' permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for +many people; adapt as needed: + +$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile +$ source ~/.profile + + When correctly configured, in a new terminal window 'env | grep +LEDGER_FILE' will show your file, and so will 'hledger files'. + + On mac, this additional step might be helpful for GUI applications +(like Emacs started from the dock): add an entry to +'~/.MacOSX/environment.plist' like + +{ + "LEDGER_FILE" : "~/finance/2023.journal" +} + + and then run 'killall Dock' in a terminal window (or restart the +machine). + + On Windows, see https://www.java.com/en/download/help/path.html, or +try running these commands in a powershell window (let us know if it +persists across a reboot, and if you need to be an Administrator): + +> CD +> MKDIR finance +> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: PART 5 COMMON TASKS + +25.5 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: + + 2023-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/2023.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 [2023-02-07]: 2023-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): . + 2023-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 [2023-01-01]: . + + If you're using version control, this could be a good time to commit +the journal. Eg: + +$ git commit -m 'initial balances' 2023.journal + + +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS + +25.6 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: + +2023/1/10 * gift received + assets:cash $20 + income:gifts + +2023.1.12 * farmers market + expenses:food $13 + assets:cash + +2023-01-15 paycheck + income:salary + assets:bank:checking $1000 + + +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS + +25.7 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: + + 2023-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 '2023-01-15' and 'paycheck' + + If you're using version control, this can be another good time to +commit: + +$ git commit -m 'txns' 2023.journal + + +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS + +25.8 Reporting +============== + +Here are some basic reports. + + Show all transactions: + +$ hledger print +2023-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +2023-01-10 * gift received + assets:cash $20 + income:gifts + +2023-01-12 * farmers market + expenses:food $13 + assets:cash + +2023-01-15 * paycheck + income:salary + assets:bank:checking $1000 + +2023-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + +$ hledger accounts --tree +assets + bank + checking + savings + cash +equity + opening/closing balances +expenses + food + misc +income + gifts + salary +liabilities + creditcard + + Show all account totals: + +$ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard +-------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to +depth 2: + +$ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard +-------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple +balance sheet: + +$ hledger bs -2 +Balance Sheet 2023-01-16 + + || 2023-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 2023-01-01-2023-01-16 + + || 2023-01-01-2023-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 +2023-01-01 opening balances assets:cash $100 $100 +2023-01-10 gift received assets:cash $20 $120 +2023-01-12 farmers market assets:cash $-13 $107 +2023-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + +$ hledger activity -W +2019-12-30 ***** +2023-01-06 **** +2023-01-13 **** + + +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS + +25.9 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: BUGS, Prev: PART 5 COMMON TASKS, Up: Top + +26 BUGS +******* + +We welcome bug reports in the hledger issue tracker (shortcut: +http://bugs.hledger.org), or on the #hledger chat or hledger mail list +(https://hledger.org/support). + + Some known issues and limitations: + + The need to precede add-on command options with '--' when invoked +from hledger is awkward. (See Command options, Constructing command +lines.) + + A UTF-8-aware system locale must be configured to work with non-ascii +data. (See Unicode characters, Troubleshooting.) + + On Microsoft Windows, depending whether you are running in a CMD +window or a Cygwin/MSYS/Mintty window and how you installed hledger, +non-ascii characters and colours may not be supported, and the tab key +may not be supported by 'hledger add'. (Running in a WSL window should +resolve these.) + + When processing large data files, hledger uses more memory than +Ledger. + +* Menu: + +* Troubleshooting:: + + +File: hledger.info, Node: Troubleshooting, Up: BUGS + +26.1 Troubleshooting +==================== + +Here are some common issues you might encounter when you run hledger, +and how to resolve them (and remember also you can usually get quick +Support): + + *PATH issues: I get an error like "No command 'hledger' found"* +Depending how you installed hledger, the executables may not be in your +shell's PATH. Eg on unix systems, stack installs hledger in +'~/.local/bin' and cabal installs it in '~/.cabal/bin'. You may need to +add one of these directories to your shell's PATH, and/or open a new +terminal window. + + *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not +using it* + + * 'LEDGER_FILE' should be a real environment variable, not just a + shell variable. Eg on unix, the command 'env | grep LEDGER_FILE' + should show it. You may need to use 'export' (see + https://stackoverflow.com/a/7411509). + * You may need to force your shell to see the new configuration. A + simple way is to close your terminal window and open a new one. + + *LANG issues: I get 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 +the system locale to be UTF-8-aware, or they will fail when they +encounter non-ascii characters. To fix it, set the LANG environment +variable to a locale which supports UTF-8 and which is installed on your +system. + + On unix, 'locale -a' lists the installed locales. Look for one which +mentions 'utf8', 'UTF-8' or similar. Some examples: 'C.UTF-8', +'en_US.utf-8', 'fr_FR.utf8'. If necessary, use your system package +manager to install one. Then select it by setting the 'LANG' +environment variable. Note, exact spelling and capitalisation of the +locale name may be important: Here's one common way to configure this +permanently for your shell: + +$ echo "export LANG=en_US.utf8" >>~/.profile +# close and re-open terminal window + + If you are using Nix (not NixOS) for GHC and Hledger, you might need +to set the 'LOCALE_ARCHIVE' variable: + +$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile +# close and re-open terminal window + + *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file* +Not all of Ledger's journal file syntax or feature set is supported. +See hledger and Ledger for full details. + + +Tag Table: +Node: Top210 +Node: PART 1 USER INTERFACE3822 +Ref: #part-1-user-interface3961 +Node: Input3961 +Ref: #input4071 +Node: Data formats5020 +Ref: #data-formats5133 +Node: Standard input6495 +Ref: #standard-input6635 +Node: Multiple files6862 +Ref: #multiple-files7001 +Node: Strict mode7599 +Ref: #strict-mode7709 +Node: Commands8433 +Ref: #commands8535 +Node: Add-on commands9602 +Ref: #add-on-commands9704 +Node: Options10820 +Ref: #options10932 +Node: General help options11260 +Ref: #general-help-options11406 +Node: General input options11688 +Ref: #general-input-options11870 +Node: General reporting options12572 +Ref: #general-reporting-options12733 +Node: Command line tips16123 +Ref: #command-line-tips16253 +Node: Option repetition16512 +Ref: #option-repetition16656 +Node: Special characters16760 +Ref: #special-characters16933 +Node: Single escaping shell metacharacters17096 +Ref: #single-escaping-shell-metacharacters17337 +Node: Double escaping regular expression metacharacters17940 +Ref: #double-escaping-regular-expression-metacharacters18251 +Node: Triple escaping for add-on commands18777 +Ref: #triple-escaping-for-add-on-commands19037 +Node: Less escaping19681 +Ref: #less-escaping19835 +Node: Unicode characters20159 +Ref: #unicode-characters20334 +Node: Regular expressions21746 +Ref: #regular-expressions21919 +Node: hledger's regular expressions25015 +Ref: #hledgers-regular-expressions25174 +Node: Argument files26560 +Ref: #argument-files26696 +Node: Output27193 +Ref: #output27305 +Node: Output destination27432 +Ref: #output-destination27563 +Node: Output format27988 +Ref: #output-format28134 +Node: CSV output29731 +Ref: #csv-output29847 +Node: HTML output29950 +Ref: #html-output30088 +Node: JSON output30182 +Ref: #json-output30320 +Node: SQL output31242 +Ref: #sql-output31358 +Node: Commodity styles32093 +Ref: #commodity-styles32233 +Node: Colour32832 +Ref: #colour32950 +Node: Box-drawing33354 +Ref: #box-drawing33472 +Node: Paging33762 +Ref: #paging33876 +Node: Debug output34829 +Ref: #debug-output34935 +Node: Environment35598 +Ref: #environment35722 +Node: PART 2 DATA FORMATS36266 +Ref: #part-2-data-formats36409 +Node: Journal36409 +Ref: #journal36518 +Node: Journal cheatsheet37175 +Ref: #journal-cheatsheet37314 +Node: About journal format41299 +Ref: #about-journal-format41459 +Node: Comments43075 +Ref: #comments43205 +Node: Transactions44021 +Ref: #transactions44144 +Node: Dates45158 +Ref: #dates45265 +Node: Simple dates45310 +Ref: #simple-dates45426 +Node: Posting dates45926 +Ref: #posting-dates46044 +Node: Status47013 +Ref: #status47114 +Node: Code48822 +Ref: #code48925 +Node: Description49157 +Ref: #description49288 +Node: Payee and note49608 +Ref: #payee-and-note49714 +Node: Transaction comments50049 +Ref: #transaction-comments50202 +Node: Postings50565 +Ref: #postings50698 +Node: Account names51693 +Ref: #account-names51823 +Node: Amounts53497 +Ref: #amounts53612 +Node: Decimal marks digit group marks54597 +Ref: #decimal-marks-digit-group-marks54772 +Node: Commodity55631 +Ref: #commodity55818 +Node: Directives influencing number parsing and display56770 +Ref: #directives-influencing-number-parsing-and-display57029 +Node: Commodity display style57481 +Ref: #commodity-display-style57687 +Node: Rounding59097 +Ref: #rounding59215 +Node: Costs59665 +Ref: #costs59781 +Node: Other cost/lot notations61977 +Ref: #other-costlot-notations62109 +Node: Balance assertions64698 +Ref: #balance-assertions64849 +Node: Assertions and ordering65932 +Ref: #assertions-and-ordering66121 +Node: Assertions and multiple included files66821 +Ref: #assertions-and-multiple-included-files67081 +Node: Assertions and multiple -f files67581 +Ref: #assertions-and-multiple--f-files67832 +Node: Assertions and commodities68229 +Ref: #assertions-and-commodities68451 +Node: Assertions and prices69631 +Ref: #assertions-and-prices69837 +Node: Assertions and subaccounts70264 +Ref: #assertions-and-subaccounts70485 +Node: Assertions and virtual postings70809 +Ref: #assertions-and-virtual-postings71047 +Node: Assertions and auto postings71179 +Ref: #assertions-and-auto-postings71409 +Node: Assertions and precision72054 +Ref: #assertions-and-precision72236 +Node: Posting comments72503 +Ref: #posting-comments72649 +Node: Tags73026 +Ref: #tags73140 +Node: Tag values74333 +Ref: #tag-values74422 +Node: Directives75181 +Ref: #directives75308 +Node: Directives and multiple files76638 +Ref: #directives-and-multiple-files76816 +Node: Directive effects77583 +Ref: #directive-effects77737 +Node: account directive80750 +Ref: #account-directive80906 +Node: Account comments82304 +Ref: #account-comments82454 +Node: Account subdirectives82962 +Ref: #account-subdirectives83153 +Node: Account error checking83295 +Ref: #account-error-checking83493 +Node: Account display order84682 +Ref: #account-display-order84870 +Node: Account types85971 +Ref: #account-types86112 +Node: alias directive89739 +Ref: #alias-directive89900 +Node: Basic aliases90950 +Ref: #basic-aliases91081 +Node: Regex aliases91825 +Ref: #regex-aliases91982 +Node: Combining aliases92872 +Ref: #combining-aliases93050 +Node: Aliases and multiple files94326 +Ref: #aliases-and-multiple-files94530 +Node: end aliases directive95109 +Ref: #end-aliases-directive95328 +Node: Aliases can generate bad account names95477 +Ref: #aliases-can-generate-bad-account-names95725 +Node: Aliases and account types96310 +Ref: #aliases-and-account-types96502 +Node: commodity directive97198 +Ref: #commodity-directive97372 +Node: Commodity directive syntax98557 +Ref: #commodity-directive-syntax98742 +Node: Commodity error checking100193 +Ref: #commodity-error-checking100374 +Node: decimal-mark directive100668 +Ref: #decimal-mark-directive100850 +Node: include directive101247 +Ref: #include-directive101411 +Node: P directive102323 +Ref: #p-directive102468 +Node: payee directive103357 +Ref: #payee-directive103506 +Node: tag directive103979 +Ref: #tag-directive104134 +Node: Periodic transactions104602 +Ref: #periodic-transactions104767 +Node: Periodic rule syntax106473 +Ref: #periodic-rule-syntax106651 +Node: Periodic rules and relative dates107296 +Ref: #periodic-rules-and-relative-dates107562 +Node: Two spaces between period expression and description!108073 +Ref: #two-spaces-between-period-expression-and-description108350 +Node: Auto postings109034 +Ref: #auto-postings109182 +Node: Auto postings and multiple files111619 +Ref: #auto-postings-and-multiple-files111783 +Node: Auto postings and dates112184 +Ref: #auto-postings-and-dates112432 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions112607 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112963 +Node: Auto posting tags113466 +Ref: #auto-posting-tags113748 +Node: Auto postings on forecast transactions only114384 +Ref: #auto-postings-on-forecast-transactions-only114630 +Node: Other syntax114877 +Ref: #other-syntax114993 +Node: Balance assignments115620 +Ref: #balance-assignments115776 +Node: Balance assignments and prices117149 +Ref: #balance-assignments-and-prices117364 +Node: Balance assignments and multiple files117575 +Ref: #balance-assignments-and-multiple-files117806 +Node: Bracketed posting dates117999 +Ref: #bracketed-posting-dates118183 +Node: D directive118697 +Ref: #d-directive118865 +Node: apply account directive120465 +Ref: #apply-account-directive120645 +Node: Y directive121332 +Ref: #y-directive121492 +Node: Secondary dates122320 +Ref: #secondary-dates122474 +Node: Star comments123288 +Ref: #star-comments123448 +Node: Valuation expressions123980 +Ref: #valuation-expressions124157 +Node: Virtual postings124279 +Ref: #virtual-postings124456 +Node: Other Ledger directives125893 +Ref: #other-ledger-directives126056 +Node: CSV126622 +Ref: #csv126715 +Node: CSV rules cheatsheet128795 +Ref: #csv-rules-cheatsheet128924 +Node: source130722 +Ref: #source130845 +Node: separator131725 +Ref: #separator131838 +Node: skip132378 +Ref: #skip132486 +Node: date-format133030 +Ref: #date-format133151 +Node: timezone133875 +Ref: #timezone133998 +Node: newest-first135003 +Ref: #newest-first135141 +Node: intra-day-reversed135718 +Ref: #intra-day-reversed135872 +Node: decimal-mark136320 +Ref: #decimal-mark136461 +Node: fields list136800 +Ref: #fields-list136939 +Node: Field assignment138610 +Ref: #field-assignment138754 +Node: Field names139831 +Ref: #field-names139962 +Node: date field141165 +Ref: #date-field141283 +Node: date2 field141331 +Ref: #date2-field141472 +Node: status field141528 +Ref: #status-field141671 +Node: code field141720 +Ref: #code-field141865 +Node: description field141910 +Ref: #description-field142070 +Node: comment field142129 +Ref: #comment-field142284 +Node: account field142577 +Ref: #account-field142727 +Node: amount field143297 +Ref: #amount-field143446 +Node: currency field146138 +Ref: #currency-field146291 +Node: balance field146548 +Ref: #balance-field146680 +Node: if block147052 +Ref: #if-block147173 +Node: Matchers148581 +Ref: #matchers148695 +Node: What matchers match149492 +Ref: #what-matchers-match149641 +Node: Combining matchers150081 +Ref: #combining-matchers150249 +Node: Match groups150735 +Ref: #match-groups150863 +Node: if table151610 +Ref: #if-table151732 +Node: balance-type153294 +Ref: #balance-type153423 +Node: include154123 +Ref: #include154250 +Node: Working with CSV154694 +Ref: #working-with-csv154841 +Node: Rapid feedback155248 +Ref: #rapid-feedback155381 +Node: Valid CSV155833 +Ref: #valid-csv155979 +Node: File Extension156711 +Ref: #file-extension156884 +Node: Reading CSV from standard input157448 +Ref: #reading-csv-from-standard-input157672 +Node: Reading multiple CSV files157836 +Ref: #reading-multiple-csv-files158067 +Node: Reading files specified by rule158308 +Ref: #reading-files-specified-by-rule158536 +Node: Valid transactions159707 +Ref: #valid-transactions159906 +Node: Deduplicating importing160534 +Ref: #deduplicating-importing160729 +Node: Setting amounts161765 +Ref: #setting-amounts161936 +Node: Amount signs164294 +Ref: #amount-signs164464 +Node: Setting currency/commodity165361 +Ref: #setting-currencycommodity165565 +Node: Amount decimal places166739 +Ref: #amount-decimal-places166945 +Node: Referencing other fields167257 +Ref: #referencing-other-fields167470 +Node: How CSV rules are evaluated168367 +Ref: #how-csv-rules-are-evaluated168584 +Node: Well factored rules170037 +Ref: #well-factored-rules170205 +Node: CSV rules examples170529 +Ref: #csv-rules-examples170664 +Node: Bank of Ireland170729 +Ref: #bank-of-ireland170866 +Node: Coinbase172328 +Ref: #coinbase172466 +Node: Amazon173513 +Ref: #amazon173638 +Node: Paypal175357 +Ref: #paypal175465 +Node: Timeclock183109 +Ref: #timeclock183214 +Node: Timedot185392 +Ref: #timedot185515 +Node: Timedot examples188620 +Ref: #timedot-examples188726 +Node: PART 3 REPORTING CONCEPTS190897 +Ref: #part-3-reporting-concepts191079 +Node: Amount formatting parseability191079 +Ref: #amount-formatting-parseability191276 +Node: Time periods193481 +Ref: #time-periods193620 +Node: Report start & end date193738 +Ref: #report-start-end-date193890 +Node: Smart dates195549 +Ref: #smart-dates195702 +Node: Report intervals197570 +Ref: #report-intervals197725 +Node: Date adjustment198143 +Ref: #date-adjustment198303 +Node: Period expressions199154 +Ref: #period-expressions199295 +Node: Period expressions with a report interval201059 +Ref: #period-expressions-with-a-report-interval201293 +Node: More complex report intervals201507 +Ref: #more-complex-report-intervals201752 +Node: Multiple weekday intervals203553 +Ref: #multiple-weekday-intervals203742 +Node: Depth204564 +Ref: #depth204666 +Node: Queries204962 +Ref: #queries205064 +Node: Query types206189 +Ref: #query-types206310 +Node: Combining query terms209646 +Ref: #combining-query-terms209823 +Node: Queries and command options211091 +Ref: #queries-and-command-options211290 +Node: Queries and valuation211539 +Ref: #queries-and-valuation211734 +Node: Querying with account aliases211963 +Ref: #querying-with-account-aliases212174 +Node: Querying with cost or value212304 +Ref: #querying-with-cost-or-value212481 +Node: Pivoting212782 +Ref: #pivoting212896 +Node: Generating data214673 +Ref: #generating-data214805 +Node: Forecasting216388 +Ref: #forecasting216513 +Node: --forecast217044 +Ref: #forecast217175 +Node: Inspecting forecast transactions218221 +Ref: #inspecting-forecast-transactions218423 +Node: Forecast reports219553 +Ref: #forecast-reports219726 +Node: Forecast tags220662 +Ref: #forecast-tags220822 +Node: Forecast period in detail221282 +Ref: #forecast-period-in-detail221476 +Node: Forecast troubleshooting222370 +Ref: #forecast-troubleshooting222538 +Node: Budgeting223441 +Ref: #budgeting223561 +Node: Cost reporting223998 +Ref: #cost-reporting224132 +Node: Recording costs224793 +Ref: #recording-costs224929 +Node: Reporting at cost226520 +Ref: #reporting-at-cost226695 +Node: Equity conversion postings227285 +Ref: #equity-conversion-postings227499 +Node: Inferring equity conversion postings229930 +Ref: #inferring-equity-conversion-postings230193 +Node: Combining costs and equity conversion postings230945 +Ref: #combining-costs-and-equity-conversion-postings231255 +Node: Requirements for detecting equity conversion postings232243 +Ref: #requirements-for-detecting-equity-conversion-postings232565 +Node: Infer cost and equity by default ?233765 +Ref: #infer-cost-and-equity-by-default233994 +Node: Value reporting234202 +Ref: #value-reporting234344 +Node: -V Value235118 +Ref: #v-value235250 +Node: -X Value in specified commodity235445 +Ref: #x-value-in-specified-commodity235646 +Node: Valuation date235795 +Ref: #valuation-date235972 +Node: Finding market price236755 +Ref: #finding-market-price236966 +Node: --infer-market-prices market prices from transactions238135 +Ref: #infer-market-prices-market-prices-from-transactions238417 +Node: Valuation commodity241179 +Ref: #valuation-commodity241398 +Node: Simple valuation examples242611 +Ref: #simple-valuation-examples242815 +Node: --value Flexible valuation243474 +Ref: #value-flexible-valuation243684 +Node: More valuation examples245328 +Ref: #more-valuation-examples245543 +Node: Interaction of valuation and queries246813 +Ref: #interaction-of-valuation-and-queries247060 +Node: Effect of valuation on reports247532 +Ref: #effect-of-valuation-on-reports247735 +Node: PART 4 COMMANDS255432 +Ref: #part-4-commands255581 +Node: Commands overview255960 +Ref: #commands-overview256094 +Node: DATA ENTRY256273 +Ref: #data-entry256397 +Node: DATA CREATION256596 +Ref: #data-creation256750 +Node: DATA MANAGEMENT256868 +Ref: #data-management257033 +Node: REPORTS FINANCIAL257154 +Ref: #reports-financial257329 +Node: REPORTS VERSATILE257634 +Ref: #reports-versatile257807 +Node: REPORTS BASIC258060 +Ref: #reports-basic258212 +Node: HELP258721 +Ref: #help258843 +Node: ADD-ONS258953 +Ref: #add-ons259059 +Node: accounts259638 +Ref: #accounts259771 +Node: activity261658 +Ref: #activity261777 +Node: add262151 +Ref: #add262261 +Node: aregister265072 +Ref: #aregister265193 +Node: aregister and posting dates268081 +Ref: #aregister-and-posting-dates268226 +Node: balance268982 +Ref: #balance269108 +Node: balance features270093 +Ref: #balance-features270233 +Node: Simple balance report272199 +Ref: #simple-balance-report272384 +Node: Balance report line format274009 +Ref: #balance-report-line-format274211 +Node: Filtered balance report276369 +Ref: #filtered-balance-report276561 +Node: List or tree mode276888 +Ref: #list-or-tree-mode277056 +Node: Depth limiting278401 +Ref: #depth-limiting278567 +Node: Dropping top-level accounts279168 +Ref: #dropping-top-level-accounts279368 +Node: Showing declared accounts279678 +Ref: #showing-declared-accounts279877 +Node: Sorting by amount280408 +Ref: #sorting-by-amount280575 +Node: Percentages281245 +Ref: #percentages281404 +Node: Multi-period balance report281952 +Ref: #multi-period-balance-report282152 +Node: Balance change end balance284427 +Ref: #balance-change-end-balance284636 +Node: Balance report types286064 +Ref: #balance-report-types286245 +Node: Calculation type286743 +Ref: #calculation-type286898 +Node: Accumulation type287447 +Ref: #accumulation-type287627 +Node: Valuation type288529 +Ref: #valuation-type288717 +Node: Combining balance report types289718 +Ref: #combining-balance-report-types289912 +Node: Budget report291750 +Ref: #budget-report291912 +Node: Budget report start date297566 +Ref: #budget-report-start-date297744 +Node: Budgets and subaccounts299076 +Ref: #budgets-and-subaccounts299283 +Node: Selecting budget goals302723 +Ref: #selecting-budget-goals302922 +Node: Budget vs forecast303957 +Ref: #budget-vs-forecast304116 +Node: Balance report layout305746 +Ref: #balance-report-layout305926 +Node: Useful balance reports314111 +Ref: #useful-balance-reports314271 +Node: balancesheet315356 +Ref: #balancesheet315501 +Node: balancesheetequity316828 +Ref: #balancesheetequity316986 +Node: cashflow318382 +Ref: #cashflow318513 +Node: check319948 +Ref: #check320062 +Node: Default checks320866 +Ref: #default-checks320992 +Node: Strict checks321489 +Ref: #strict-checks321634 +Node: Other checks322114 +Ref: #other-checks322256 +Node: Custom checks322789 +Ref: #custom-checks322946 +Node: More about specific checks323363 +Ref: #more-about-specific-checks323525 +Node: close324231 +Ref: #close324342 +Node: close and balance assertions327807 +Ref: #close-and-balance-assertions327985 +Node: Example retain earnings329136 +Ref: #example-retain-earnings329353 +Node: Example migrate balances to a new file329785 +Ref: #example-migrate-balances-to-a-new-file330050 +Node: Example excluding closing/opening transactions330626 +Ref: #example-excluding-closingopening-transactions330875 +Node: codes332093 +Ref: #codes332210 +Node: commodities333074 +Ref: #commodities333202 +Node: demo333272 +Ref: #demo333393 +Node: descriptions334309 +Ref: #descriptions334439 +Node: diff334730 +Ref: #diff334845 +Node: files335887 +Ref: #files335996 +Node: help336137 +Ref: #help-1336246 +Node: import337619 +Ref: #import337742 +Node: Deduplication338850 +Ref: #deduplication338975 +Node: Import testing340994 +Ref: #import-testing341159 +Node: Importing balance assignments342002 +Ref: #importing-balance-assignments342208 +Node: Commodity display styles342857 +Ref: #commodity-display-styles343030 +Node: incomestatement343159 +Ref: #incomestatement343301 +Node: notes344629 +Ref: #notes344751 +Node: payees345113 +Ref: #payees345228 +Node: prices345747 +Ref: #prices345862 +Node: print346515 +Ref: #print346630 +Node: print explicitness347606 +Ref: #print-explicitness347749 +Node: print amount style348528 +Ref: #print-amount-style348698 +Node: print parseability349750 +Ref: #print-parseability349922 +Node: print other features350671 +Ref: #print-other-features350850 +Node: print output format351371 +Ref: #print-output-format351519 +Node: register354638 +Ref: #register354760 +Node: Custom register output359791 +Ref: #custom-register-output359922 +Node: rewrite361266 +Ref: #rewrite361384 +Node: Re-write rules in a file363282 +Ref: #re-write-rules-in-a-file363445 +Node: Diff output format364594 +Ref: #diff-output-format364777 +Node: rewrite vs print --auto365869 +Ref: #rewrite-vs.-print---auto366029 +Node: roi366585 +Ref: #roi366692 +Node: Spaces and special characters in --inv and --pnl368504 +Ref: #spaces-and-special-characters-in---inv-and---pnl368744 +Node: Semantics of --inv and --pnl369232 +Ref: #semantics-of---inv-and---pnl369471 +Node: IRR and TWR explained371321 +Ref: #irr-and-twr-explained371481 +Node: stats374734 +Ref: #stats374842 +Node: tags376229 +Ref: #tags-1376336 +Node: test377345 +Ref: #test377438 +Node: PART 5 COMMON TASKS378180 +Ref: #part-5-common-tasks378326 +Node: Getting help378624 +Ref: #getting-help378765 +Node: Constructing command lines379525 +Ref: #constructing-command-lines379726 +Node: Starting a journal file380383 +Ref: #starting-a-journal-file380585 +Node: Setting LEDGER_FILE381787 +Ref: #setting-ledger_file381979 +Node: Setting opening balances382936 +Ref: #setting-opening-balances383137 +Node: Recording transactions386278 +Ref: #recording-transactions386467 +Node: Reconciling387023 +Ref: #reconciling387175 +Node: Reporting389432 +Ref: #reporting389581 +Node: Migrating to a new file393566 +Ref: #migrating-to-a-new-file393723 +Node: BUGS394022 +Ref: #bugs394112 +Node: Troubleshooting394991 +Ref: #troubleshooting395091  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -16,8951 +16,8964 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.32. It - also describes the common options, file formats and concepts used by - all hledger programs. It might accidentally teach you some bookkeep- - ing/accounting as well! You don't need to know everything in here to - use hledger productively, but when you have a question about function- - ality, this doc should answer it. It is detailed, so do skip ahead or - skim when needed. You can read it on hledger.org, or as an info manual - or man page on your system. You can also get it from hledger itself - with - hledger --man, hledger --info or hledger help [TOPIC]. - - The main function of the hledger CLI is to read plain text files de- - scribing financial transactions, crunch the numbers, and print a useful - report on the terminal (or save it as HTML, CSV, JSON or SQL). Many - reports are available, as subcommands. hledger will also detect other - hledger-* executables as extra subcommands. - - hledger usually reads from (and appends to) a journal file specified by - the LEDGER_FILE environment variable (defaulting to - $HOME/.hledger.journal); or you can specify files with -f options. It - can also read timeclock files, timedot files, or any CSV/SSV/TSV file - with a date field. - - Here is a small journal file describing one transaction: - - 2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more - accounts: bank accounts, your wallet, revenue/expense categories, peo- - ple, etc. You can choose any account names you wish, using : to indi- - cate subaccounts. There must be at least two spaces between account - name and amount. Positive amounts are inflow to that account (debit), - negatives are outflow from it (credit). (Some reports show revenue, - liability and equity account balances as negative numbers as a result; - this is normal.) - - hledger's add command can help you add transactions, or you can install - other data entry UIs like hledger-web or hledger-iadd. For more exten- - sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM + - vim-ledger, or VS Code + hledger-vscode are some good choices (see - https://hledger.org/editors.html). - - To get started, run hledger add and follow the prompts, or save some - entries like the above in $HOME/.hledger.journal, then try commands - like: - hledger print -x - hledger aregister assets - hledger balance - hledger balancesheet - hledger incomestatement. - Run hledger to list the commands. See also the "Starting a journal - file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -PART 1: USER INTERFACE -Input - hledger reads one or more data files, each time you run it. You can - specify a file with -f, like so - - $ hledger -f FILE print - - Files are most often in hledger's journal format, with the .journal - file extension (.hledger or .j also work); these files describe trans- - actions, like an accounting general journal. - - When no file is specified, hledger looks for .hledger.journal in your - home directory. - - But most people prefer to keep financial files in a dedicated folder, - perhaps with version control. Also, starting a new journal file each - year is common (it's not required, but helps keep things fast and or- - ganised). So we usually configure a different journal file, by setting - the LEDGER_FILE environment variable, to something like ~/fi- - nance/2023.journal. For more about how to do that on your system, see - Common tasks > Setting LEDGER_FILE. - - 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 .journal .j .hledger .ledger - Ledger journals, for transac- - tions - timeclock timeclock files, for precise .timeclock - time logging - timedot timedot files, for approximate .timedot - time logging - csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules - rated values, for data import .ssv.rules .tsv.rules - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a - recognised file extension, so as to either read successfully or to show - relevant error messages. - - You can also force a specific reader/format by prefixing the file path - with the format and a colon. Eg, to read a .dat file as csv format: - - $ hledger -f csv:/some/csv-file.dat stats - - Standard input - The file name - means standard input: - - $ cat FILE | hledger -f- print - - If reading non-journal data in this way, you'll need to add a file for- - mat prefix, like: - - $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- - - Multiple files - You can specify multiple -f options, to read multiple files as one big - journal. When doing this, note that certain features (described below) - will be affected: - - o Balance assertions will not see the effect of transactions in previ- - ous files. (Usually this doesn't matter as each file will set the - corresponding opening balances.) - - o Some directives will not affect previous or subsequent files. - - If needed, you can work around these by using a single parent file - which includes the others, or concatenating the files into one, 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. - -Commands - hledger provides various subcommands for getting things done. Most of - these commands do not change the journal file; they just read it and - output a report. A few commands assist with adding data and file man- - agement. - - To show the commands list, run hledger with no arguments. The commands - are described in detail in PART 4: COMMANDS, below. - - To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], - - o CMD is the full command name, or its standard abbreviation shown in - the commands list, or any unambiguous prefix of the name. - - o CMDOPTS are command-specific options, if any. Command-specific op- - tions must be written after the command name. Eg: hledger print -x. - - o CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit the - data in some way. Eg: hledger reg assets:checking. - - To list a command's options, arguments, and documentation in the termi- - nal, run hledger CMD -h. Eg: hledger bal -h. - - Add-on commands - In addition to the built-in commands, you can install add-on commands: - programs or scripts named "hledger-SOMETHING", which will also appear - in hledger's commands list. If you used the hledger-install script, - you will have several add-ons installed already. Some more can be - found in hledger's bin/ directory, documented at - https://hledger.org/scripts.html. - - More precisely, add-on commands are programs or scripts in your shell's - PATH, whose name starts with "hledger-" and ends with no extension or a - recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", - ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix - and mac) which has executable permission for the current user. - - You can run add-on commands using hledger, much like built-in commands: - hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double - hyphen argument, required before add-on-specific options. Eg: hledger - ui -- --watch or hledger web -- --serve. If this causes difficulty, - you can always run the add-on directly, without using hledger: hledger- - ui --watch or hledger-web --serve. - -Options - Run hledger -h to see general command line help, and general options - which are common to most hledger commands. These options can be writ- - ten anywhere on the command line. They can be grouped into help, in- - put, and reporting options: - - 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 de- - clared) - - 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 ef- - fects) - - --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-equity - infer conversion equity postings from costs - - --infer-costs - infer costs from conversion equity postings - - --infer-market-prices - use costs as additional market prices, as if they were P direc- - tives - - --forecast - generate transactions from periodic rules, between the latest - recorded txn and 6 months from today, or during the specified - PERIOD (= is required). Auto posting rules will be applied to - these transactions as well. Also, in hledger-ui make future- - dated transactions visible. - - --auto generate extra postings by applying auto posting rules to all - txns (not just forecast txns) - - --verbose-tags - add visible tags indicating transactions or postings which have - been generated/modified - - --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 line tips - Here are some details useful to know about for hledger command lines - (and elsewhere). Feel free to skip this section until you need it. - - Option repetition - If options are repeated in a command line, hledger will generally use - the last (right-most) occurence. - - 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 ac- - count 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 be- - low), 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:\\$ - - 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 de- - code 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 - A regular expression (regexp) is a small piece of text where certain - characters (like ., ^, $, +, *, (), |, [], \) have special meanings, - forming a tiny language for matching text precisely - very useful in - hledger and elsewhere. To learn all about them, visit regular-expres- - sions.info. - - hledger supports regexps whenever you are entering a pattern to match - something, eg in query arguments, account aliases, CSV if rules, - hledger-web's search form, hledger-ui's / search, etc. You may need to - wrap them in quotes, especially at the command line (see Special char- - acters above). Here are some examples: - - Account name queries (quoted for command line use): - - Regular expression: Matches: - ------------------- ------------------------------------------------------------ - bank assets:bank, assets:bank:savings, expenses:art:banksy, ... - :bank assets:bank:savings, expenses:art:banksy - :bank: assets:bank:savings - '^bank' none of those ( ^ matches beginning of text ) - 'bank$' assets:bank ( $ matches end of text ) - 'big \$ bank' big $ bank ( \ disables following character's special meaning ) - '\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) - '(sav|check)ing' saving or checking ( (|) matches either alternative ) - 'saving|checking' saving or checking ( outer parentheses are not needed ) - 'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) - 'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) - 'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) - 'b.nk' bank, bonk, b nk, ... ( . matches any character ) - - Some other queries: - - desc:'amazon|amzn|audible' Amazon transactions - cur:EUR amounts with commodity symbol containing EUR - cur:'\$' amounts with commodity symbol containing $ - cur:'^\$$' only $ amounts, not eg AU$ or CA$ - cur:....? amounts with 4-or-more-character symbols - tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 - - Account name aliases: accept . instead of : as account separator: - - alias /\./=: replaces all periods in account names with colons - - Show multiple top-level accounts combined as one: - - --alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) - - Show accounts with the second-level part removed: - - --alias '/^([^:]+):[^:]+/ = \1' - match a top-level account and a second-level account - and replace those with just the top-level account - ( \1 in the replacement text means "whatever was matched - by the first parenthesised part of the regexp" - - CSV rules: match CSV records containing dining-related MCC codes: - - if \?MCC581[124] - - Match CSV records with a specific amount around the end/start of month: - - if %amount \b3\.99 - & %date (29|30|31|01|02|03)$ - - hledger's regular expressions - 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. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the re- - placement string to reference capturing groups in the search regexp. - Otherwise, if you write \1, it will match the digit 1. - - 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. - - Argument files - You can save a set of command line options and arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: - hledger bal @foo.args. - - Inside the argument file, each line should contain just one option or - argument. Don't use spaces except inside quotes (or you'll see a con- - fusing error); write = (or nothing) between a flag and its argument. - For the special characters mentioned above, use one less level of quot- - ing than you would at the command prompt. - -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) - - Output format - Some commands offer other kinds of output, not just text on the termi- - nal. Here are those commands and the formats currently supported: - - - txt csv/tsv html json sql - -------------------------------------------------------------------------------------- - aregister Y Y Y Y - balance Y 1 Y 1 Y 1,2 Y - balancesheet Y 1 Y 1 Y 1 Y - balancesheete- Y 1 Y 1 Y 1 Y - quity - 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 - - 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 - - Some notes about the various output formats: - - 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 This is not yet much used; real-world feedback is welcome. - - o Our JSON is rather large and verbose, since it is a faithful repre- - sentation 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 This is not yet much used; real-world feedback is welcome. - - o SQL output is expected to work at least with SQLite, MySQL and Post- - gres. - - o For SQLite, it will be more useful if you modify the generated id - field to be a PRIMARY KEY. Eg: - - $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - - 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 - When displaying amounts, hledger infers a standard display style for - each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a -c/--commodity-style option (ex- - cept for cost amounts and amounts displayed by the print command, which - are always displayed with all decimal digits). For example, the fol- - lowing will force dollar amounts to be displayed as shown: - - $ hledger print -c '$1.000,0' - - This option can repeated to set the display style for multiple commodi- - ties/currencies. Its argument is as described in the commodity direc- - tive. - - Colour - In terminal output, some commands can produce colour when the terminal - supports it: - - o if the --color/--colour option is given a value of yes or always (or - no or never), colour will (or will not) be used; - - o otherwise, if the NO_COLOR environment variable is set, colour will - not be used; - - o otherwise, colour will be used if the output (terminal or file) sup- - ports it. - - Box-drawing - In terminal output, you can enable unicode box-drawing characters to - render prettier tables: - - o if the --pretty option is given a value of yes or always (or no or - never), unicode characters will (or will not) be used; - - o otherwise, unicode characters will not be used. - - Paging - When showing long output in the terminal, hledger will try to use the - pager specified by the PAGER environment variable, or less, or more. - (A pager is a helper program that shows one page at a time rather than - scrolling everything off screen). Currently it does this only for help - output, not for reports; specifically, - - o when listing commands, with hledger - - o when showing help with hledger [CMD] --help, - - o when viewing manuals with hledger help or hledger --man. - - Note the pager is expected to handle ANSI codes, which hledger uses eg - for bold emphasis. For the common pager less (and its more compatibil- - ity mode), we add R to the LESS and MORE environment variables to make - this work. If you use a different pager, you might need to configure - it similarly, to avoid seeing junk on screen (let us know). Otherwise, - you can set the NO_COLOR environment variable to 1 to disable all ANSI - output (see Colour). - - Debug output - We intend hledger to be relatively easy to troubleshoot, introspect and - develop. You can add --debug[=N] to any hledger command line to see - additional debug output. N ranges from 1 (least output, the default) - to 9 (maximum output). Typically you would start with 1 and increase - until you are seeing enough. Debug output goes to stderr, and is not - affected by -o/--output-file (unless you redirect stderr to stdout, eg: - 2>&1). It will be interleaved with normal output, which can help re- - veal when parts of the code are evaluated. To capture debug output in - a log file instead, you can usually redirect stderr, eg: - - hledger bal --debug=3 2>hledger.log - -Environment - These environment variables affect hledger: - - COLUMNS This is normally set by your terminal; some hledger commands - (register) will format their output to this width. If not set, they - will try to use the available terminal width. - - LEDGER_FILE The main journal file to use when not specified with - -f/--file. Default: $HOME/.hledger.journal. - - NO_COLOR If this environment variable is set (with any value), hledger - will not use ANSI color codes in terminal output, unless overridden by - an explicit --color/--colour option. - -PART 2: DATA FORMATS -Journal - hledger's default file format, representing a General Journal. Here's - a cheatsheet/mini-tutorial, or you can skip ahead to About journal for- - mat. - - Journal cheatsheet - # Here is the main syntax of hledger's journal format - # (omitting extra Ledger compatibility syntax). - # hledger journals contain comments, directives, and transactions, in any order: - - ############################################################################### - # 1. Comment lines are for notes or temporarily disabling things. - # They begin with #, ;, or a line containing the word "comment". - - # hash comment line - ; semicolon comment line - comment - These lines - are commented. - end comment - - # Some but not all hledger entries can have same-line comments attached to them, - # from ; (semicolon) to end of line. - - ############################################################################### - # 2. Directives modify parsing or reports in some way. - # They begin with a word or letter (or symbol). - - account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. - account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) - alias chkg = assets:checking - commodity $0.00 - decimal-mark . - include /dev/null - payee Whole Foods - P 2022-01-01 AAAA $1.40 - ~ monthly budget goals ; <- 2+ spaces between period expression and description - expenses:food $400 - expenses:home $1000 - budgeted - - ############################################################################### - # 3. Transactions are what it's all about; they are dated events, - # usually describing movements of money. - # They begin with a date. - - # DATE DESCRIPTION ; This is a transaction comment. - # ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. - # ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. - # ; ^^ At least 2 spaces between account and amount. - # ... ; Any number of postings is allowed. The amounts must balance (sum to 0). - - 2022-01-01 opening balances are declared this way - assets:checking $1000 ; Account names can be anything. lower case is easy to type. - assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. - assets:cash:wallet $100 ; : indicates subaccounts. - liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. - equity ; One amount can be left blank; $-1900 is inferred here. - - 2022-04-15 * (#12345) pay taxes - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a transaction code (text in parentheses) after the date/status. - ; Amounts' sign represents direction of flow, or credit/debit: - assets:checking $-500 ; minus means removed from this account (credit) - expenses:tax:us:2021 $500 ; plus means added to this account (debit) - ; revenue/expense categories are also "accounts" - - 2022-01-01 ; The description is optional. - ; Any currency/commodity symbols are allowed, on either side. - assets:cash:wallet GBP -10 - expenses:clothing GBP 10 - assets:gringotts -10 gold - assets:pouch 10 gold - revenues:gifts -2 "Liquorice Wands" ; Complex symbols - assets:bag 2 "Liquorice Wands" ; must be double-quoted. - - 2022-01-01 Cost in another commodity can be noted with @ or @@ - assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments 3.0 AAAA @@ $4 ; @@ means total cost - assets:checking $-7.00 - - 2022-01-02 assert balances - ; Balances can be asserted for extra error checking, in any transaction. - assets:investments 0 AAAA = 5.0 AAAA - assets:pouch 0 gold = 10 gold - assets:savings $0 = $1000 - - 1999-12-31 Ordering transactions by date is recommended but not required. - ; Postings are not required. - - 2022.01.01 These date - 2022/1/1 formats are - 12/31 also allowed (but consistent YYYY-MM-DD is recommended). - - About journal format - hledger's usual data source is a plain text file containing journal en- - tries in hledger journal format. This file represents a standard ac- - counting 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 compatible with most of Ledger's journal - format, but not all of it. The differences and interoperation tips are - described at hledger and Ledger. With some care, and by avoiding in- - compatible features, you can keep your hledger journal readable by - Ledger and vice versa. This can useful eg for comparing the behaviour - of one app against the other. - - 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). - - A hledger journal file can contain three kinds of thing: file comments, - transactions, and/or directives (counting periodic transaction rules - and auto posting rules as directives). - - Comments - Lines in the journal will be ignored if they begin with a hash (#) or a - semicolon (;). (See also Other syntax.) hledger will also ignore re- - gions beginning with a comment line and ending with an end comment line - (or file end). Here's a suggestion for choosing between them: - - o # for top-level notes - - o ; for commenting out things temporarily - - o comment for quickly commenting large regions (remember it's there, or - you might get confused) - - Eg: - - # a comment line - ; another commentline - comment - A multi-line comment block, - continuing until "end comment" directive - or the end of the current file. - end comment - - Some hledger entries can have same-line comments attached to them, from - ; (semicolon) to end of line. See Transaction comments, Posting com- - ments, and Account comments below. - - 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 op- - tional 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 Y directive, or the cur- - rent 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.) - - 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 re- - ports, and the deduction from checking should be reported on 6/1 for - easy bank reconciliation: - - 2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - - $ hledger -f t.j register food - 2015-05-30 expenses:food $10 $10 - - $ hledger -f t.j register checking - 2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. - The date: tag must have a valid simple date value if it is present, eg - a date: tag with no value is not allowed. - - Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction de- - scription or posting account name, separated from it by a space, indi- - cating 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 un- - marked 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 un- - cashed 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 (af- - ter the first |). This may be worthwhile if you need to do more pre- - cise querying and pivoting by payee or by note. - - Transaction comments - Text following ;, after a transaction description, and/or on indented - lines immediately below it, form comments for that transaction. They - are reproduced by print but otherwise ignored, except they may contain - tags, which are not ignored. - - 2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - 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 - spaces. But if you accidentally leave only one space (or tab) before - the amount, the amount will be considered part of the account name. - - Account names - Accounts are the main way of categorising things in hledger. As in - Double Entry Bookkeeping, they can represent real world accounts (such - as a bank account), or more abstract categories such as "money borrowed - from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the - traditional accounting categories, which in english are assets, liabil- - ities, equity, revenues, expenses. (You might see these referred to as - A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts - into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking - and expenses:food, hledger will infer this hierarchy of five accounts: - - assets - assets:bank - assets:bank:checking - expenses - expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - - assets - bank - checking - expenses - food - - hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account - names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or - more spaces (or tabs). - - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to - the account name have no special meaning. - - Account names can be altered temporarily or permanently by account - aliases. - - Amounts - After the account name, there is usually an amount. (Important: be- - tween 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,23 - - 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 - - hledger is not biased towards period or comma decimal marks, so a num- - ber containing just one period or comma, like 1,000 or 1.000, is am- - biguous. In such cases hledger assumes it is a decimal mark, parsing - both of these as 1. - - To disambiguate these and ensure accurate number parsing, especially if - you use digit group marks, we recommend declaring the decimal mark. - You can declare it for each file with decimal-mark directives, or for - each commodity with commodity directives (described 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, but here's a quick example: - - # the decimal mark character used by all amounts in this file (all commodities) - decimal-mark . - - # display styles for the $, EUR, INR and no-symbol commodities: - commodity $1,000.00 - commodity EUR 1.000,00 - commodity INR 9,99,99,999.00 - commodity 1 000 000.9455 - - Commodity display style - For the amounts in each commodity, hledger chooses a consistent display - style (symbol placement, decimal mark and digit group marks, number of - decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a D directive declaring a default commodity, that - commodity symbol and amount format is applied to all no-symbol amounts - in the journal. - - Then each commodity's display style is determined from its commodity - directive. We recommend always declaring commodities with commodity - directives, since they help ensure consistent display styles and preci- - sions, and bring other benefits such as error checking for commodity - symbols. - - But if a commodity directive is not present, hledger infers a commod- - ity's display styles from its amounts as they are written in the jour- - nal (excluding cost amounts and amounts in periodic transaction rules - or auto posting rules). It uses - - o the symbol placement and decimal mark of the first amount seen - - o the digit group marks of the first amount with digit group marks - - o and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a de- - fault style, like $1000.00 (symbol on the left with no space, period as - decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -c/--commodity-style - command line option. - - Rounding - Amounts are stored internally as decimal numbers with up to 255 decimal - places. They are displayed with their original journal precisions by - print and print-like reports, and rounded to their display precision - (the number of decimal digits specified by the commodity display style) - by other reports. When rounding, hledger uses banker's rounding (it - rounds to the nearest even digit). So eg 0.5 displayed with zero deci- - mal digits appears as "0". - - Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- - tion, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, - discussions, or code; that term was directionally neutral and reminded - that it is a price specific to a transaction, but we now just call it - "cost", with the understanding that the transaction could be a purchase - or a sale.) - - Costs are usually written explicitly with @ or @@, but can also be in- - ferred automatically for simple multi-commodity transactions. Note, if - costs are inferred, the order of postings is significant; the first - posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign - currency in hledger, using the cost notation either explicitly or im- - plicitly: - - 1. Write the price per unit, as @ UNITPRICE after the amount: - - 2009/1/1 - assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as @@ TOTALPRICE after the amount: - - 2009/1/1 - assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, and - let hledger infer the price that balances the transaction. Note the - effect of posting order: the price is added to first posting, making - it 100 @@ $135, as in example 2: - - 2009/1/1 - assets:euros 100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the -B/--cost - flag; this is discussed more in the Cost reporting section. - - Note that the cost normally should be a positive amount, though it's - not required to be. This can be a little confusing, see discussion at - --infer-market-prices: market prices from transactions. - - Other cost/lot notations - A slight digression for Ledger and Beancount users. Ledger has a num- - ber of cost/lot-related notations: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a conversion rate, as in hledger - - o when buying, also creates a lot than can be selected at selling - time - - o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - - o like the above, but also means "this cost was exceptional, don't - use it when inferring market prices". - - Currently, hledger treats the above like @ and @@; the parentheses are - ignored. - - o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) - - o when buying, means "this cost is also the fixed price, don't let it - fluctuate in value reports" - - o {UNITCOST} and {{TOTALCOST}} (lot price) - - o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- - ates a lot - - o when selling, combined with @ ..., specifies an investment lot by - its cost basis; does not check if that lot is present - - o and related: [YYYY/MM/DD] (lot date) - - o when buying, attaches this acquisition date to the lot - - o when selling, selects a lot by its acquisition date - - o (SOME TEXT) (lot note) - - o when buying, attaches this note to the lot - - o when selling, selects a lot by its note - - Currently, hledger accepts any or all of the above in any order after - the posting amount, but ignores them. (This can break transaction bal- - ancing.) - - For Beancount users, the notation and behaviour is different: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a cost without creating a lot, as in hledger - - o when buying (augmenting) or selling (reducing) a lot, combined with - {...}: documents the cost/selling price (not used for transaction - balancing) - - o {UNITCOST} and {{TOTALCOST}} - - o when buying (augmenting), expresses the cost for transaction bal- - ancing, and also creates a lot with this cost basis attached - - o when selling (reducing), - - o selects a lot by its cost basis - - o raises an error if that lot is not present or can not be selected - unambiguously (depending on booking method configured) - - o expresses the selling price for transaction balancing - - Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but - ignores it. - - o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- - COST, YYYY-MM-DD, "LABEL"} etc. - - Currently, hledger rejects these. - - 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, described 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 or- - der 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 in- - clude, 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 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 - - Assertions and prices - Balance assertions ignore costs, and should normally be written without - one: - - 2019/1/1 - (a) $1 @ 1 = $1 - - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance 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. - - Posting comments - Text following ;, at the end of a posting line, and/or on indented - lines immediately below it, form comments for that posting. They are - reproduced by print but otherwise ignored, except they may contain - tags, which are not ignored. - - 2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - Tags - Tags are a way to add extra labels or labelled data to transactions, - postings, or accounts, which you can then search or pivot on. - - They are written as a word (optionally hyphenated) immediately followed - by a full colon, in a transaction or posting or account directive's - comment. (This is an exception to the usual rule that things in com- - ments are ignored.) Eg, here four different tags are recorded: one on - the checking account, two on the transaction, and one on the expenses - posting: - - account assets:checking ; accounttag: - - 2017/1/16 bought groceries ; transactiontag-1: - ; transactiontag-2: - assets:checking $-1 - expenses:food $1 ; postingtag: - - Postings also inherit tags from their transaction and their account. - And transactions also acquire tags from their postings (and postings' - accounts). So in the example above, the expenses posting effectively - has all four tags (by inheriting from account and transaction), and the - transaction also has all four tags (by acquiring from the expenses - posting). - - You can list tag names with hledger tags [NAMEREGEX], or match by tag - name with a tag:NAMEREGEX query. - - Tag values - Tags can have a value, which is any text after the colon up until a - comma or end of line (with surrounding whitespace removed). Note this - means that hledger tag values can not contain commas. Eg in the fol- - lowing posting, the three tags' values are "value 1", "value 2", and "" - (empty) respectively: - - expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - - Note that tags can be repeated, and are additive rather than overrid- - ing: when the same tag name is seen again with a new value, the new - name:value pair is added to the tags. (It is not possible to override - a tag's value or remove a tag.) - - You can list a tag's values with hledger tags TAGNAME --values, or - match by tag value with a tag:NAMEREGEX=VALUEREGEX query. - - Directives - Besides transactions, there is something else you can put in a journal - file: directives. These are declarations, beginning with a keyword, - that modify hledger's behaviour. Some directives can have more spe- - cific subdirectives, indented below them. hledger's directives are - similar to Ledger's in many cases, but there are also many differences. - Directives are not required, but can be useful. Here are the main di- - rectives: - - purpose directive - -------------------------------------------------------------------------- - READING DATA: - Rewrite account names alias - Comment out sections of the file comment - Declare file's decimal mark, to help decimal-mark - parse amounts accurately - Include other data files include - GENERATING DATA: - Generate recurring transactions or bud- ~ - get goals - Generate extra postings on existing = - transactions - CHECKING FOR ERRORS: - Define valid entities to provide more account, commodity, payee, tag - error checking - REPORTING: - Declare accounts' type and display order account - Declare commodity display styles commodity - Declare market prices P - - Directives and multiple files - Directives vary in their scope, ie which journal entries and which in- - put files they affect. Most often, a directive will affect the follow- - ing entries and included files if any, until the end of the current - file - and no further. You might find this inconvenient! For example, - alias directives do not affect parent or sibling files. But there are - usually workarounds; for example, put alias directives in your top-most - file, before including other files. - - The restriction, though it may be annoying at first, is in a good - cause; it allows reports to be stable and deterministic, independent of - the order of input. Without it, reports could show different numbers - depending on the order of -f options, or the positions of include di- - rectives in your files. - - Directive effects - Here are all hledger's directives, with their effects and scope sum- - marised - nine main directives, plus four others which we consider non- - essential: - - di- what it does ends - rec- at - tive file - end? - -------------------------------------------------------------------------------------- - ac- Declares an account, for checking all entries in all files; and N - count its display order and type. Subdirectives: any text, ignored. - alias Rewrites account names, in following entries until end of cur- Y - rent file or end aliases. Command line equivalent: --alias - com- Ignores part of the journal file, until end of current file or Y - ment end comment. - com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N - mod- all amounts in all files 2. the decimal mark for parsing - ity amounts of this commodity, in the following entries until end of - current file (if there is no decimal-mark directive) 3. and the - display style for amounts of this commodity 4. which is also - the precision to use for balanced-transaction checking in this - commodity. Takes precedence over D. Subdirectives: format - (Ledger-compatible syntax). Command line equivalent: -c/--com- - modity-style - deci- Declares the decimal mark, for parsing amounts of all commodi- Y - mal- ties in following entries until next decimal-mark or end of cur- - mark rent file. Included files can override. Takes precedence over - commodity and D. - in- Includes entries and directives from another file, as if they N - clude were written inline. Command line alternative: multiple - -f/--file - payee Declares a payee name, for checking all entries in all files. N - P Declares the market price of a commodity on some date, for value N - reports. - ~ Declares a periodic transaction rule that generates future N - (tilde) transactions with --forecast and budget goals with balance - --budget. - Other - syntax: - apply Prepends a common parent account to all account names, in fol- Y - account lowing entries until end of current file or end apply account. - D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no commodity directive for this commodity: its decimal - mark, balancing precision, and display style, as above. - Y Sets a default year to use for any yearless dates, in following Y - entries until end of current file. - = Declares an auto posting rule that generates extra postings on partly - (equals) matched transactions with --auto, in current, parent, and child - files (but not sibling files, see #1212). - Other Other directives from Ledger's file format are accepted but ig- - Ledger nored. - direc- - tives - - account directive - 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 In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - - o They control account display order in reports, allowing non-alpha- - betic sorting (eg Revenues to appear above Expenses). - - o They help with account name completion (in hledger add, hledger-web, - hledger-iadd, ledger-mode, etc.) - - o They can store additional account information as comments, or as tags - which can be used to filter or pivot reports. - - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - - They are written as the word account followed by a hledger-style ac- - count name, eg: - - account assets:bank:checking - - Note, however, that accounts declared in account directives are not al- - lowed to have surrounding brackets and parentheses, unlike accounts - used in postings. So the following journal will not parse: - - account (assets:bank:checking) - - Account comments - Text following two or more spaces and ; at the end of an account direc- - tive line, and/or following ; on indented lines immediately below it, - form comments for that account. They are ignored except they may con- - tain tags, which are not ignored. - - The two-space requirement for same-line account comments is because ; - is allowed in account names. - - account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - Account subdirectives - Ledger-style indented subdirectives are also accepted, but currently - ignored: - - account assets:bank:checking - format subdirective is ignored - - Account error checking - By default, accounts need not be declared; they come into existence - when a posting references them. This is convenient, but it means - hledger can't warn you when you mis-spell an account name in the jour- - nal. Usually you'll find that error later, as an extra account in bal- - ance 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 de- - clared 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 ac- - count 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 in- - cluded files of all types. - - o It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - Account display order - The order in which account directives are written influences the order - in which accounts appear in reports, hledger-ui, hledger-web etc. By - default accounts appear in alphabetical order, but if you add these ac- - count directives to the journal file: - - account assets - account liabilities - account equity - account revenues - account expenses - - those accounts will be displayed in declaration order: - - $ hledger accounts -1 - assets - liabilities - equity - revenues - expenses - - Any undeclared accounts are displayed last, in alphabetical order. - - Sorting is done at each level of the account tree, within each group of - sibling accounts under the same parent. And currently, this directive: - - account other:zoo - - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - - o you will sometimes declare parent accounts (eg account other above) - that you don't intend to post to, just to customize their display or- - der - - o sibling accounts stay together (you couldn't display x:y in between - a:b and a:c). - - 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 (de- - scribed below). But generally we recommend you declare types explic- - itly, by adding a type: tag to your top-level account directives. Sub- - accounts 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 Cost re- - porting).) - - 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. - - 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 ac- - count for all of the account types, 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] - - alias directive - You can define account alias rules which rewrite your account names, or - parts of them, before generating reports. This can be useful for: - - 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 re- - place any occurrence of the old account name with the new one. Subac- - counts 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 ex- - pression.) - - Eg: - - alias /REGEX/ = REPLACEMENT - - or: - - $ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by RE- - PLACEMENT. 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. In- - cluding the aliases doesn't work either: - - include a.aliases - - 2023-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 - - 2023-01-01 ; affected by aliases above - foo 1 - bar - - include c.journal ; also affected - - end aliases directive - 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 ef- - fect. - - 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 - - commodity directive - The commodity directive performs several functions: - - 1. It declares which commodity symbols may be used in the journal, en- - abling useful error checking with strict mode or the check command. - (See Commodity error checking below.) - - 2. It declares the precision with which this commodity's amounts should - be compared when checking for balanced transactions. - - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See Commodity display style above.) - - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no decimal-mark - directive in effect. See Decimal marks, digit group marks above. - For related dev discussion, see #793.) - - Declaring commodities solves several common parsing/display problems, - so we recommend it. Generally you should put commodity directives at - the top of your journal file (because function 4 is position-sensi- - tive). - - Commodity directive syntax - A commodity directive is normally the word commodity followed by a sam- - ple amount (and optionally a comment). Only the amount's symbol and - format is significant. Eg: - - commodity $1000.00 - commodity 1.000,00 EUR - commodity 1 000 000.0000 ; the no-symbol commodity - - A commodity directive's sample amount must always include a period or - comma decimal mark (this rule helps disambiguate decimal marks and - digit group marks). If you don't want to show any decimal digits, - write the decimal mark at the end: - - commodity 1000. AAAA ; show AAAA with no decimals - - Commodity symbols containing spaces, numbers, or punctuation must be - enclosed in double quotes, as usual: - - commodity 1.0000 "AAAA 2023" - - Commodity directives normally include a sample amount, but can declare - only a symbol (ie, just function 1 above): - - commodity $ - commodity INR - commodity "AAAA 2023" - commodity "" ; the no-symbol commodity - - Commodity directives may also be written with an indented format subdi- - rective, as in Ledger. The symbol is repeated and must be the same in - both places. Other subdirectives are currently ignored: - - ; 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 - an unsupported subdirective ; ignored by hledger - - Commodity error checking - In strict mode (-s/--strict) (or when you run hledger check commodi- - ties), hledger will report an error if an undeclared commodity symbol - is used. (With one exception: zero amounts are always allowed to have - no commodity symbol.) It works like account error checking (described - above). - - decimal-mark directive - You can use a decimal-mark directive - usually one per file, at the top - of the file - to declare which character represents a decimal mark when - parsing amounts in this file. It can look like - - decimal-mark . - - or - - decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we - recommend it, especially if the file contains digit group marks (eg - thousands separators). - - include directive - You can pull in the content of additional files by writing an include - directive, like this: - - include FILEPATH - - Only journal files can include, and only journal, timeclock or timedot - files can be included (not CSV files, currently). - - If the file path does not begin with a slash, it is relative to the - current file's folder. - - A tilde means home directory, eg: include ~/main.journal. - - The path may contain glob patterns to match multiple files, eg: include - *.journal. - - There is limited support for recursive wildcards: **/ (the slash is re- - quired) 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 Data formats): include time- - dot:~/notes/2023*.md. - - P directive - The P directive declares a market price, which is a conversion rate be- - tween two commodities on a certain date. This allows value reports to - convert amounts of one commodity to their value in another, on or after - that date. These prices are often obtained from a stock exchange, - cryptocurrency exchange, the or foreign exchange market. - - The format is: - - P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity - being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) - of commodity 2 that one unit of commodity 1 is worth on this date. Ex- - amples: - - # 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 Value reporting. - - payee directive - payee PAYEE NAME - - This directive can be used to declare a limited set of payees which may - appear in transaction descriptions. The "payees" check will report an - error if any transaction refers to a payee that has not been declared. - Eg: - - payee Whole Foods - - Any indented subdirectives are currently ignored. - - tag directive - tag TAGNAME - - This directive can be used to declare a limited set of tag names al- - lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - - tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is - used. It is quite easy to accidentally create a tag through normal use - of colons in comments(#comments]; if you want to prevent this, you can - declare and check your tags . - - Periodic transactions - The ~ directive declares recurring transactions. Such directives allow - hledger to generate temporary future transactions (visible in reports, - not in the journal file) to help with forecasting or budgeting. - - Periodic transactions can be a little tricky, so before you use them, - read this whole section, or at least these tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast - tag:generated. - - 3. Forecasted transactions will begin only after the last non-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 im- - provement, 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 - 2023/01, which is equivalent to ~ every 10th day of month from - 2023/01/01, will be adjusted to start on 2019/12/10. - - Periodic rule syntax - A periodic transaction rule looks like a normal journal entry, with the - date replaced by a tilde (~) followed by a period expression (mnemonic: - ~ looks like a recurring sine wave.): - - # every first of month - ~ monthly - expenses:rent $2000 - assets:bank:checking - - # every 15th of month in 2023's first quarter: - ~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying multi-pe- - riod reports, just interpreted differently; there, it specifies report - periods; here it specifies recurrence dates (the periods' start dates). - - 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 re- - sults 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 2023" - ; || - ; vv - ~ every 2 months in 2023, 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 ex- - pression. - - Auto postings - The = directive declares a rule for generating temporary extra postings - on transactions. Wherever the rule matches an existing posting, it can - add one or more companion postings below that one, optionally influ- - enced by the matched posting's amount. This can be useful for generat- - ing tax postings with a standard percentage, for example. - - Note that depending on generated data is not ideal for financial - records (it's less portable, less future-proof, less auditable by oth- - ers, and less robust, since other features like balance assertions will - depend on using or not using --auto). - - 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". - - Auto postings on forecast transactions only - Tip: you can can make auto postings that will apply to forecast trans- - actions but not recorded transactions, by adding tag:_generated-trans- - action to their QUERY. This can be useful when generating new journal - entries to be saved in the journal. - - Other syntax - hledger journal format supports quite a few other features, mainly to - make interoperating with or converting from Ledger easier. Note some - of the features below are powerful and can be useful in special cases, - but in general, features in this section are considered less important - or even not recommended for most users. Downsides are mentioned to - help you decide if you want to use them. - - 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). - - Downsides: using balance assignments makes your journal less explicit; - to know the exact amount posted, you have to run hledger or do the cal- - culations yourself, instead of just reading it. Also balance assign- - ments' forcing of balances can hide errors. These things make your fi- - nancial data less portable, less future-proof, and less trustworthy in - an audit. - - Balance assignments and prices - A cost in a balance assignment will cause the calculated amount to have - that price attached: - - 2019/1/1 - (a) = $1 @ 2 - - $ hledger print --explicit - 2019-01-01 - (a) $1 @ 2 = $1 @ 2 - - Balance assignments and multiple files - Balance assignments handle multiple files like balance assertions. - They see balance from other files previously included from the current - file, but not from previous sibling or parent files. - - Bracketed posting dates - For setting posting dates and secondary posting dates, Ledger's brack- - eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in - posting comments. hledger will attempt to parse any square-bracketed - sequence of the 0123456789/-.= characters in this way. With this syn- - tax, DATE infers its year from the transaction and DATE2 infers its - year from DATE. - - Downsides: another syntax to learn, redundant with hledger's - date:/date2: tags, and confusingly similar to Ledger's lot date syntax. - - D directive - D AMOUNT - - This directive sets a default commodity, to be used for any subsequent - commodityless amounts (ie, plain numbers) seen while parsing the 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 di- - rective (setting the commodity's decimal mark for parsing and display - style for output). So its argument is not just a commodity symbol, but - a full amount demonstrating the style. The amount must include a deci- - mal mark (either period or comma). Eg: - - ; commodity-less amounts should be treated as dollars - ; (and displayed with the dollar sign on the left, thousands separators and two decimal places) - D $1,000.00 - - 1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity's display style, a commodity directive has - highest priority, then a D directive. - - For detecting a commodity's decimal mark during parsing, decimal-mark - has highest priority, then commodity, then D. - - For checking commodity symbols with the check command, a commodity di- - rective is required (hledger check commodities ignores D directives). - - Downsides: omitting commodity symbols makes your financial data less - explicit, less portable, and less trustworthy in an audit. It is usu- - ally an unsustainable shortcut; sooner or later you will want to track - multiple commodities. D is overloaded with functions redundant with - commodity and decimal-mark. And it works differently from Ledger's D. - - apply account directive - This directive sets a default parent account, which will be prepended - to all accounts in following entries, until an end apply account direc- - tive or end of current file. Eg: - - apply account home - - 2010/1/1 - food $10 - cash - - end apply account - - is equivalent to: - - 2010/01/01 - home:food $10 - home:cash $-10 - - account directives are also affected, and so is any included content. - - Account names entered via hledger add or hledger-web are not affected. - - Account aliases, if any, are applied after the parent account is - prepended. - - Downsides: this can make your financial data less explicit, less - portable, and less trustworthy in an audit. - - Y directive - Y YEAR - - or (deprecated backward-compatible forms): - - year YEAR apply year YEAR - - The space is optional. This sets a default year to be used for subse- - quent dates which don't specify a year. Eg: - - Y2009 ; set default year to 2009 - - 12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - - year 2010 ; change default year to 2010 - - 2009/1/30 ; specifies the year, not affected - expenses 1 - assets - - 1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at least) - makes your financial data less explicit, less portable, and less trust- - worthy in an audit. Such dates can get separated from their corre- - sponding Y directive, eg when evaluating a region of the journal in - your editor. A missing Y directive makes reports dependent on today's - date. - - Secondary dates - A secondary date is written after the primary date, following an equals - sign. If the year is omitted, the primary date's year is assumed. - When running reports, the primary (left) date is used by default, but - with the --date2 flag (or --aux-date or --effective), the secondary - (right) date will be used instead. - - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg "primary = the bank's clearing date, secondary = - date the transaction was initiated, if different". - - Downsides: makes your financial data more complicated, less portable, - and less trustworthy in an audit. Keeping the meaning of the two dates - consistent requires discipline, and you have to remember which report- - ing mode is appropriate for a given report. Posting dates are simpler - and better. - - Star comments - Lines beginning with * (star/asterisk) are also comment lines. This - feature allows Emacs users to insert org headings in their journal, al- - lowing them to fold/unfold/navigate it like an outline when viewed with - org mode. - - Downsides: another, unconventional comment syntax to learn. Decreases - your journal's portability. And switching to Emacs org mode just for - folding/unfolding meant losing the benefits of ledger mode; nowadays - you can add outshine mode to ledger mode to get folding without losing - ledger mode's features. - - Valuation expressions - Ledger allows a valuation function or value to be written in double - parentheses after an amount. hledger ignores these. - - Virtual postings - A posting with parentheses around the account name ((some:account)) is - called a unbalanced virtual posting. Such postings do not participate - in transaction balancing. (And if you write them without an amount, a - zero amount is always inferred.) These can occasionally be convenient - for special circumstances, but they violate double entry bookkeeping - and make your data less portable across applications, so many people - avoid using them at all. - - A posting with brackets around the account name ([some:account]) is - called a balanced virtual posting. The balanced virtual postings in a - transaction must add up to zero, just like ordinary postings, but sepa- - rately from them. These are not part of double entry bookkeeping ei- - ther, but they are at least balanced. An example: - - 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Ordinary postings, whose account names are neither parenthesised nor - bracketed, are called real postings. You can exclude virtual postings - from reports with the -R/--real flag or a real:1 query. - - Other Ledger directives - These other Ledger directives are currently accepted but ignored. This - allows hledger to read more Ledger files, but be aware that hledger's - reports may differ from Ledger's if you use these. - - apply fixed COMM AMT - apply tag TAG - assert EXPR - bucket / A ACCT - capture ACCT REGEX - check EXPR - define VAR=EXPR - end apply fixed - end apply tag - end apply year - end tag - eval / expr EXPR - python - PYTHONCODE - tag NAME - value EXPR - --command-line-flags - - See also https://hledger.org/ledger.html for a detailed hledger/Ledger - syntax comparison. - -CSV - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records, automatically converting - each record into a transaction. - - (To learn about writing CSV, see CSV output.) - - For best error messages when reading CSV/TSV/SSV files, make sure they - have a corresponding .csv, .tsv or .ssv file extension or use a hledger - file prefix (see File Extension below). - - Each CSV file must be described by a corresponding rules file. - This contains rules describing the CSV data (header line, fields lay- - out, date format etc.), how to construct hledger transactions from it, - and how to categorise transactions based on description or other at- - tributes. - - By default hledger looks for a rules file named like the CSV file with - an extra .rules extension, in the same directory. Eg when asked to - read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec- - ify a different rules file with the --rules-file option. If no rules - file is found, hledger will create a sample rules file, which you'll - need to adjust. - - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines - there are. Here's a simple CSV file and a rules file for it: - - Date, Description, Id, Amount - 12/11/2019, Foo, 123, 10.23 - - # basic.csv.rules - skip 1 - fields date, description, , amount - date-format %d/%m/%Y - - $ hledger print -f basic.csv - 2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There's an introductory Importing CSV data tutorial on hledger.org, and - more CSV rules examples below, and a larger collection at - https://github.com/simonmichael/hledger/tree/master/examples/csv. - - CSV rules cheatsheet - The following kinds of rule can appear in the rules file, in any order. - (Blank lines and lines beginning with # or ; or * are ignored.) - - source optionally declare which file to read data - from - separator declare the field separator, instead of rely- - ing on file extension - skip skip one or more header lines at start of file - date-format declare how to parse CSV dates/date-times - timezone declare the time zone of ambiguous CSV date- - times - newest-first improve txn order when: there are multiple - records, newest first, all with the same date - intra-day-reversed improve txn order when: same-day txns are in - opposite order to the overall file - decimal-mark declare the decimal mark used in CSV amounts, - when ambiguous - fields list name CSV fields for easy reference, and op- - tionally assign their values to hledger fields - Field assignment assign a CSV value or interpolated text value - to a hledger field - if block conditionally assign values to hledger fields, - or skip a record or end (skip rest of file) - if table conditionally assign values to hledger fields, - using compact syntax - balance-type select which type of balance assertions/as- - signments to generate - include inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are - evaluated. - - source - If you tell hledger to read a csv file with -f foo.csv, it will look - for rules in foo.csv.rules. Or, you can tell it to read the rules - file, with -f foo.csv.rules, and it will look for data in foo.csv - (since 1.30). - - These are mostly equivalent, but the second method provides some extra - features. For one, the data file can be missing, without causing an - error; it is just considered empty. And, you can specify a different - data file by adding a "source" rule: - - source ./Checking1.csv - - If you specify just a file name with no path, hledger will look for it - in your system's downloads directory (~/Downloads, currently): - - source Checking1.csv - - And if you specify a glob pattern, hledger will read the most recent of - the matched files (useful with repeated downloads): - - source Checking1*.csv - - See also "Working with CSV > Reading files specified by rule". - - 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. - - skip - skip N - - The word skip followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines at the start of the input - data. You'll need this whenever your CSV data contains header lines. - Note, empty and blank lines are skipped automatically, so you don't - need to count those. - - skip has a second meaning: it can be used inside if blocks (described - below), to skip one or more records whenever the condition is true. - Records skipped in this way are ignored, except they are still required - to be valid CSV. - - date-format - date-format DATEFMT - - This is a helper for the date (and date2) fields. If your CSV dates - are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll - need to add a date-format rule describing them with a strptime-style - date parsing pattern - see https://hackage.haskell.org/pack- - age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must - parse the CSV date value completely. Some examples: - - # MM/DD/YY - date-format %m/%d/%y - - # D/M/YYYY - # The - makes leading zeros optional. - date-format %-d/%-m/%Y - - # YYYY-Mmm-DD - date-format %Y-%h-%d - - # M/D/YYYY HH:MM AM some other junk - # Note the time and junk must be fully parsed, though only the date is used. - date-format %-m/%-d/%Y %l:%M %p some other junk - - timezone - timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone - other than yours, but containing no explicit time zone information, you - can use this rule to declare the CSV's native time zone, which helps - prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don't - need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see - the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware conversion, - localising the CSV date-times to your current system time zone. If you - prefer to localise to some other time zone, eg for reproducibility, you - can (on unix at least) set the output timezone with the TZ environment - variable, eg: - - $ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - timezone currently does not understand timezone names, except "UTC", - "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For - others, use numeric format: +HHMM or -HHMM. - - newest-first - hledger tries to ensure that the generated transactions will be ordered - chronologically, including same-day transactions. Usually it can auto- - detect how the CSV records are ordered. But if it encounters CSV where - all records are on the same date, it assumes that the records are old- - est first. If in fact the CSV's records are normally newest first, - like: - - 2022-10-01, txn 3... - 2022-10-01, txn 2... - 2022-10-01, txn 1... - - you can add the newest-first rule to help hledger generate the transac- - tions in correct order. - - # same-day CSV records are newest first - newest-first - - intra-day-reversed - If CSV records within a single day are ordered opposite to the overall - record order, you can add the intra-day-reversed rule to improve the - order of journal entries. Eg, here the overall record order is newest - first, but same-day records are oldest first: - - 2022-10-02, txn 3... - 2022-10-02, txn 4... - 2022-10-01, txn 1... - 2022-10-01, txn 2... - - # transactions within each day are reversed with respect to the overall date order - intra-day-reversed - - 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. - - fields list - fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word fields followed by comma-separated field names) - is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say %SomeField - instead of remembering %13. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and - build a transaction. - - Here's an example that says "use the 1st, 2nd and 4th fields as the - transaction's date, description and amount; name the last two fields - for later reference; and ignore the others": - - fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to the - CSV file's separator. Also: - - o 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 Fields you don't care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it's convenient to use these for - your field names, suitably modified (eg lower-cased with spaces re- - placed by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning to - a hledger field with the same name. Eg you could call the CSV's "bal- - ance" field balance_ to avoid directly setting hledger's balance field - (and generating a balance assertion). - - Field assignment - HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to - hledger fields. They can be used instead of or in addition to a fields - list (see above). - - To assign a value to a hledger field, write the field name (any of the - standard hledger field/pseudo-field names, defined below), a space, - followed by a text value on the same line. This text value may inter- - polate CSV fields, referenced either by their 1-based position in the - CSV record (%N) or by the name they were given in the fields list - (%CSVFIELD), and regular expression match groups (\N). - - 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 " be- - comes 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 - Note the two kinds of field names mentioned here, and used only in - hledger CSV rules files: - - 1. CSV field names (CSVFIELD in these docs): you can optionally name - the CSV columns for easy reference (since hledger doesn't yet auto- - matically recognise column headings in a CSV file), by writing arbi- - trary names in a fields list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special hledger field names (HLEDGERFIELD in these docs): you must - set at least some of these to generate the hledger transaction from - a CSV record, by writing them as the left hand side of a field as- - signment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a fields list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what hap- - pens when you assign values to them: - - 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. - - 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. - - account field - Assigning to accountN, where N is 1 to 99, sets the account name of the - Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you'll want to set account1 and - account2. Typically account1 is associated with the CSV file, and is - set once with a top-level assignment, while account2 is set based on - each transaction's description, in conditional rules. - - If a posting's account name is left unset but its amount is set (see - below), a default account name will be chosen (like "expenses:unknown" - or "income:unknown"). - - amount field - There are several ways to set posting amounts from CSV, useful in dif- - ferent situations. - - 1. amount is the oldest and simplest. Assigning to this sets the - amount of the first and second postings. In the second posting, the - amount will be negated; also, if it has a cost attached, it will be - converted to cost. - - 2. amount-in and amount-out work exactly like the above, but should be - used when the CSV has two amount fields (such as "Debit" and - "Credit", or "Inflow" and "Outflow"). Whichever field has a non- - zero value will be used as the amount of the first and second post- - ings. Here are some tips to avoid confusion: - - o It's not "amount-in for posting 1 and amount-out for posting 2", - it is "extract a single amount from the amount-in or amount-out - field, and use that for posting 1 and (negated) for posting 2". - - o Don't use both amount and amount-in/amount-out in the same rules - file; choose based on whether the amount is in a single CSV field - or spread across two fields. - - o In each record, at most one of the two CSV fields should contain - a non-zero amount; the other field must contain a zero or noth- - ing. - - o hledger assumes both CSV fields contain unsigned numbers, and it - automatically negates the amount-out values. - - o If the data doesn't fit these requirements, you'll probably need - an if rule (see below). - - 3. amountN (where N is a number from 1 to 99) sets the amount of only a - single posting: the Nth posting in the transaction. You'll usually - need at least two such assignments to make a balanced transaction. - You can also generate more than two postings, to represent more com- - plex transactions. The posting numbers don't have to be consecu- - tive; with if rules, higher posting numbers can be useful to ensure - a certain order of postings. - - 4. amountN-in and amountN-out work exactly like the above, but should - be used when the CSV has two amount fields. This is analogous to - amount-in and amount-out, and those tips also apply here. - - 5. Remember that a fields list can also do assignments. So in a fields - list if you name a CSV field "amount", that counts as assigning to - amount. (If you don't want that, call it something else in the - fields list, like "amount_".) - - 6. The above don't handle every situation; if you need more flexibil- - ity, use an if rule to set amounts conditionally. See "Working with - CSV > Setting amounts" below for more on this and on amount-setting - generally. - - 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. - - if block - Rules can be applied conditionally, depending on patterns in the CSV - data. This allows flexibility; in particular, it is how you can cate- - gorise transactions, selecting an appropriate account name based on - their description (for example). There are two ways to write condi- - tional rules: "if blocks", described here, and "if tables", described - below. - - An if block is the word if and one or more "matcher" expressions (can - be a word or phrase), one per line, starting either on the same or next - line; followed by one or more indented rules. Eg, - - if MATCHER - RULE - - or - - if - MATCHER - MATCHER - MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be ap- - plied. They are usually field assignments, but the following special - rules may also be used within an if block: - - o skip - skips the matched CSV record (generating no transaction from - it) - - o end - skips the rest of the current CSV file. - - Some examples: - - # if the record contains "groceries", set account2 to "expenses:groceries" - if groceries - account2 expenses:groceries - - # if the record contains any of these phrases, set account2 and a transaction comment as shown - if - monthly service fee - atm transaction fee - banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - # if an empty record is seen (assuming five fields), ignore the rest of the CSV file - if ,,,, - end - - Matchers - There are two kinds: - - 1. A record matcher is a word or single-line text fragment or regular - expression (REGEX), which hledger will try to match case-insensi- - tively anywhere within the CSV record. - Eg: whole foods - - 2. A field matcher is preceded with a percent sign and CSV field name - (%CSVFIELD REGEX). hledger will try to match these just within the - named CSV field. - Eg: %date 2023 - - The regular expression is (as usual in hledger) a POSIX extended regu- - lar expression, that also supports GNU word boundaries (\b, \B, \<, - \>), and nothing else. If you have trouble, see "Regular expressions" - in the hledger manual (https://hledger.org/hledger.html#regular-expres- - sions). - - With record matchers, it's important to know that the record matched is - not the original CSV record, but a modified one: separators will be - converted to commas, and enclosing double quotes (but not enclosing - whitespace) are removed. So for example, when reading an SSV file, if - the original record was: - - 2023-01-01; "Acme, Inc."; 1,000 - - the regex would see, and try to match, this modified record text: - - 2023-01-01,Acme, Inc., 1,000 - - When an if block has multiple matchers, they are combined as follows: - - o By default they are OR'd (any one of them can match) - - o When a matcher is preceded by ampersand (&) it will be AND'ed with - the previous matcher (both of them must match). - - When a matcher is preceded by an exclamation mark (!), the matcher will - be negated, ie it will exclude CSV records that match. - - Match groups - Matchers can define match groups: parenthesised portions of the regular - expression which are available for reference in field assignments. - Groups are enclosed in regular parentheses (( and )) and can be nested. - Each group is available in field assignments using the token \N, where - N is an index into the match groups for this conditional block (e.g. - \1, \2, etc.). - - Example: Warp credit card payment postings to the beginning of the - billing period (Month start), to match how they are presented in state- - ments, using posting dates: - - if %date (....-..)-.. - comment2 date:\1-01 - - Another example: Read the expense account from the CSV field, but throw - away a prefix: - - if %account1 liabilities:family:(expenses:.*) - account1 \1 - - if table - "if tables" are an alternative to if blocks; they can express many - matchers and field assignments in a more compact tabular format, like - this: - - if,HLEDGERFIELD1,HLEDGERFIELD2,... - MATCHERA,VALUE1,VALUE2,... - MATCHERB,VALUE1,VALUE2,... - MATCHERC,VALUE1,VALUE2,... - - - The first character after if is taken to be this if table's field sepa- - rator. It is unrelated to the separator used in the CSV file. It - should be a non-alphanumeric character like , or | that does not appear - anywhere else in the table (it should not be used in field names or - matchers or values, and it cannot be escaped with a backslash). - - Each line must contain the same number of separators; empty values are - allowed. Whitespace can be used in the matcher lines for readability - (but not in the if line, currently). The table must be terminated by - an empty line (or end of file). - - An if table like the above is interpreted as follows: try all of the - matchers; whenever a matcher succeeds, assign all of the values on that - line to the corresponding hledger fields; later lines can overrider - earlier ones. It is equivalent to this sequence of if blocks: - - if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - if MATCHERB - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - if MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - - if,account2,comment - atm transaction fee,expenses:business:banking,deductible? check it - %description groceries,expenses:groceries, - 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - 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 - - 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 - - Working with CSV - Some 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 - Note that hledger will only accept valid CSV conforming to RFC 4180, - and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or - tab as separators). This means, eg: - - o Values may be enclosed in double quotes, or not. Enclosing in single - quotes is not allowed. (Eg 'A','B' is rejected.) - - o When values are enclosed in double quotes, spaces outside the quotes - are not allowed. (Eg "A", "B" is rejected.) - - o When values are not enclosed in quotes, they may not contain double - quotes. (Eg A"A, B is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- - form it before reading with hledger. Try using sed, or a more permis- - sive CSV parser like python's csv lib. - - File Extension - To help hledger choose the CSV file reader and show the right error - messages (and choose the right field separator character by default), - it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv - filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV - reader (and the default field separator) by prefixing the file path - with csv:, ssv: or tsv:: Eg: - - $ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator rule - if needed. - - Reading CSV from standard input - You'll need the file format prefix when reading CSV from stdin also, - since hledger assumes journal format by default. Eg: - - $ cat foo.dat | hledger -f ssv:- print - - 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. - - Reading files specified by rule - Instead of specifying a CSV file in the command line, you can specify a - rules file, as in hledger -f foo.csv.rules CMD. By default this will - read data from foo.csv in the same directory, but you can add a source - rule to specify a different data file, perhaps located in your web - browser's download directory. - - This feature was added in hledger 1.30, so you won't see it in most CSV - rules examples. But it helps remove some of the busywork of managing - CSV downloads. Most of your financial institutions's default CSV file- - names are different and can be recognised by a glob pattern. So you - can put a rule like source Checking1*.csv in foo-checking.csv.rules, - and then periodically follow a workflow like: - - 1. Download CSV from Foo's website, using your browser's defaults - - 2. Run hledger import foo-checking.csv.rules to import any new transac- - tions - - After import, you can: discard the CSV, or leave it where it is for a - while, or move it into your archives, as you prefer. If you do noth- - ing, next time your browser will save something like Checking1-2.csv, - and hledger will use that because of the * wild card and because it is - the most recent. - - 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 as- - sertions 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 - Continuing from amount field above, here are more tips for amount-set- - ting: - - 1. If the amount is in a single CSV field: - a. If its sign indicates direction of flow: - Assign it to amountN, to set the Nth posting's amount. N is usu- - ally 1 or 2 but can go up to 99. - - b. If another field indicates direction of flow: - Use one or more conditional rules to set the appropriate amount - sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. If the amount is in two CSV fields (such as Debit and Credit, or In - and Out): - a. If both fields are unsigned: - Assign one field to amountN-in and the other to amountN-out. - hledger will automatically negate the "out" field, and will use - whichever field value is non-zero as posting N's amount. - - b. If either field is signed: - You will probably need to override hledger's sign for one or the - other field, as in the following example: - - # Negate the -out value, but only if it is not empty: - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. If both fields can contain a non-zero value (or both can be - empty): - The -in/-out rules normally choose the value which is non-zero/non- - empty. Some value pairs can be ambiguous, such as 1 and none. For - such cases, use conditional rules to help select the amount. Eg, - to handle the above you could select the value containing non-zero - digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. If you want posting 2's amount converted to cost: - Use the unnumbered amount (or amount-in and amount-out) syntax. - - 4. If the CSV has only balance amounts, not transaction amounts: - Assign to balanceN, to set a balance assignment on the Nth posting, - causing the posting's amount to be calculated automatically. balance - with no number is equivalent to balance1. In this situation hledger is - more likely to guess the wrong default account name, so you may need to - set that explicitly. - - Amount signs - There is some special handling making it easier to parse and to reverse - amount signs. (This only works for whole amounts, not for cost amounts - such as COST in amount1 AMT @ COST): - - 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 - "". - - It's not possible (without preprocessing the CSV) to set an amount to - its absolute value, ie discard its sign. - - Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount - field(s): - - 2023-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 - - 2023-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - - 2023-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 - - 2023-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 - - 2023-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 re- - peated, 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 re- - maining 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 as- - signed to it (and interpolate the %CSVFIELD references), or a default - - o generate a hledger transaction (journal entry) from these values. - - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the - user specified. - - Well factored rules - Some things than can help reduce duplication and complexity in rules - files: - - o Extracting common rules usable with multiple CSV files into a com- - mon.rules, and adding include common.rules to each CSV's rules file. - - o Splitting if blocks into smaller if blocks, extracting the frequently - used parts. - - CSV rules examples - 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. - - Coinbase - A simple example with some CSV from Coinbase. The spot price is - recorded using cost notation. The legacy amount field name conve- - niently sets amount 2 (posting 2's amount) to the total cost. - - # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes - # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - - # coinbase.csv.rules - skip 1 - fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes - date %Timestamp - date-format %Y-%m-%dT%T%Z - description %Notes - account1 assets:coinbase:cc - amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - - $ hledger print -f coinbase.csv - 2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - 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: - -Timeclock - The time logging format of timeclock.el, as read by hledger. - - hledger can read time logs in timeclock format. As with Ledger, these - are (a subset of) timeclock.el's format, containing clock-in and clock- - out entries as in the example below. The date is a simple date. The - time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. - The timezone, if present, must be four digits and is ignored (currently - the time is always interpreted as a local time). Lines beginning with - # or ; or *, and blank lines, are ignored. - - i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: - 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 2 spaces ; optional comment, tags: - (some account) 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 - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is more convenient for quick, approxi- - mate, and retroactive time logging, and more human-readable (you can - see at a glance where time was spent). A quick example: - - 2023-05-01 - hom:errands .... .... ; two hours; the space is ignored - fos:hledger:timedot .. ; half an hour - per:admin:finance ; no time spent yet - - hledger reads this as a transaction on this day with three (unbalanced) - postings, where each dot represents "0.25". No commodity symbol is as- - sumed, but we typically interpret it as hours. - - $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required - 2023-05-01 * - (hom:errands) 2.00 ; two hours - (fos:hledger:timedot) 0.50 ; half an hour - (per:admin:finance) 0 - - A timedot file contains a series of transactions (usually one per day). - Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be - followed on the same line by a transaction description, and/or a trans- - action comment following a semicolon. - - After the date line are zero or more time postings, consisting of: - - o An account name - any hledger-style account name, optionally in- - dented. - - o Two or more spaces - required if there is an amount (as in journal - format). - - o A timedot amount, which can be - - o empty (representing zero) - - o a number, optionally followed by a unit s, m, h, d, w, mo, or y, - representing a precise number of seconds, minutes, hours, days - weeks, months or years (hours is assumed by default), which will be - converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = - 1w, 30d = 1mo, 365d = 1y. - - o one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can be - used for grouping/alignment. - - o one or more letters. These are like dots but they also generate a - tag t: (short for "type") with the letter as its value, and a sepa- - rate posting for each of the values. This provides a second dimen- - sion of categorisation, viewable in reports with --pivot t. - - o An optional comment following a semicolon (a hledger-style posting - comment). - - There is some flexibility to help with keeping time log data and notes - in the same file: - - o Blank lines and lines beginning with # or ; are ignored. - - o After the first date line, lines which do not contain a double space - are parsed as postings with zero amount. (hledger's register reports - will show these if you add -E). - - o Before the first date line, lines beginning with * (eg org headings) - are ignored. And from the first date line onward, Emacs org mode - heading prefixes at the start of lines (one or more *'s followed by a - space) will be ignored. This means the time log can also be a org - outline. - - Timedot examples - Numbers: - - 2016/2/3 - inc:client1 4 - fos:hledger 3h - biz:research 60m - - Dots: - - # 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 . - - $ 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 - - Letters: - - # Activity types: - # c cleanup/catchup/repair - # e enhancement - # s support - # l learning/research - - 2023-11-01 - work:adm ccecces - - $ hledger -f a.timedot print - 2023-11-01 - (work:adm) 1 ; t:c - (work:adm) 0.5 ; t:e - (work:adm) 0.25 ; t:s - - $ hledger -f a.timedot bal - 1.75 work:adm - -------------------- - 1.75 - - $ hledger -f a.timedot bal --pivot t - 1.00 c - 0.50 e - 0.25 s - -------------------- - 1.75 - - Org: - - * 2023 Work Diary - ** Q1 - *** 2023-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 - - Using . as account name separator: - - 2016/2/4 - fos.hledger.timedot 4h - fos.ledger .. - - $ hledger -f a.timedot --alias '/\./=:' bal -t - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger - -------------------- - 4.50 - -PART 3: REPORTING CONCEPTS -Amount formatting, parseability - If you're wondering why your print report sometimes shows trailing dec- - imal marks, with no decimal digits; it does this when showing amounts - that have digit group marks but no decimal digits, to disambiguate them - and allow them to be re-parsed reliably (see also Decimal marks, digit - group marks. Eg: - - commodity $1,000.00 - - 2023-01-02 - (a) $1000 - - $ hledger print - 2023-01-02 - (a) $1,000. - - If this is a problem (eg when exporting to Ledger), you can avoid it by - disabling digit group marks, eg with -c/--commodity (for each affected - commodity): - - $ hledger print -c '$1000.00' - 2023-01-02 - (a) $1000 - - or by forcing print to always show decimal digits, with --round: - - $ hledger print -c '$1,000.00' --round=soft - 2023-01-02 - (a) $1,000.00 - - More generally: hledger output falls into three rough categories, which - format amounts a little bit differently to suit different consumers: - - 1. "hledger-readable output" - should be readable by hledger (and by - humans) - - o This is produced by reports that show full journal entries: print, - import, close, rewrite etc. - - o It shows amounts with their original journal precisions, which may - not be consistent. - - o It adds a trailing decimal mark when needed to avoid showing ambigu- - ous amounts. - - o It can be parsed reliably (by hledger and ledger2beancount at least, - but perhaps not by Ledger..) - - 2. "human-readable output" - usually for humans - - o This is produced by all other reports. - - o It shows amounts with standard display precisions, which will be con- - sistent within each commodity. - - o It shows ambiguous amounts unmodified. - - o It can be parsed reliably in the context of a known report (when you - know decimals are consistently not being shown, you can assume a sin- - gle mark is a digit group mark). - - 3. "machine-readable output" - usually for other software - - o This is produced by all reports when an output format like csv, tsv, - json, or sql is selected. - - o It shows amounts as 1 or 2 do, but without digit group marks. - - o It can be parsed reliably (if needed, the decimal mark can be changed - with -c/--commodity-style). - -Time periods - Report start & end date - By default, most hledger reports will show the full span of time repre- - sented by the journal. The report start date will be the earliest - transaction or posting date, and the report end date will be the latest - transaction, posting, or market price date. - - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, - -e/--end, -p/--period or a date: query (described below). All of these - accept the smart date syntax (below). - - Some notes: - - 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 In some cases a report interval will adjust start/end dates to fall - on interval boundaries (see below). - - 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 re- - placed with -) - date:..12/1 - date:thismonth.. - date:thismonth - - Smart dates - hledger's user interfaces accept a "smart date" syntax for added conve- - nience. Smart dates optionally can be relative to today's date, be - written with english words, and have less-significant parts omitted - (missing parts are inferred as 1). Some examples: - - 2004/10/1, 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 - - Some counterexamples - malformed digit sequences might give surprising - results: - - 201813 6 digits with an invalid month is parsed as start of - 6-digit year - 20181301 8 digits with an invalid month is parsed as start of - 8-digit year - 20181232 8 digits with an invalid day gives an error - 201801012 9+ digits beginning with a valid YYYYMMDD gives an error - - "Today's date" can be overridden with the --today option, in case it's - needed for testing or for recreating old reports. (Except for periodic - transaction rules, which are not affected by --today.) - - Report intervals - A report interval can be specified so that reports like register, bal- - ance or activity become multi-period, showing each subperiod as a sepa- - rate row or column. - - The following standard intervals can be enabled with command-line - flags: - - o -D/--daily - - o -W/--weekly - - o -M/--monthly - - o -Q/--quarterly - - o -Y/--yearly - - More complex intervals can be specified using -p/--period, described - below. - - Date adjustment - When there is a report interval (other than daily), report start/end - dates which have been inferred, eg from the journal, are automatically - adjusted to natural period boundaries. This is convenient for produc- - ing simple periodic reports. More precisely: - - o an inferred start date will be adjusted earlier if needed to fall on - a natural period boundary - - o an inferred end date will be adjusted later if needed to make the - last period the same length as the others. - - By contrast, start/end dates which have been specified explicitly, with - -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This - makes it possible to specify non-standard report periods, but it also - means that if you are specifying a start date, you should pick one - that's on a period boundary if you want to see simple report period - headings. - - Period expressions - The -p/--period option specifies a period expression, which is a com- - pact way of expressing a start date, end date, and/or report interval. - - Here's a period expression with a start and end date (specifying the - first quarter of 2009): - - -p "from 2009/1/1 to 2009/4/1" - - Several keywords like "from" and "to" are supported for readability; - these are optional. "to" can also be written as ".." or "-". The - spaces are also optional, as long as you don't run two dates together. - So the following are equivalent to the above: - - -p "2009/1/1 2009/4/1" - -p2009/1/1to2009/4/1 - -p2009/1/1..2009/4/1 - - Dates are smart dates, so if the current year is 2009, these are also - equivalent to the above: - - -p "1/1 4/1" - -p "jan-apr" - -p "this year to 4/1" - - If you specify only one date, the missing start or end date will be the - earliest or latest transaction date in the journal: - - -p "from 2009/1/1" everything after january - 1, 2009 - -p "since 2009/1" the same, since is a syn- - onym - -p "from 2009" the same - -p "to 2009" everything before january - 1, 2009 - - You can also specify a period by writing a single partial or full date: - - -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to - 2009/2/1" - -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to - 2009/1/2" - - or by using the "Q" quarter-year syntax (case insensitive): - - -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to - 2009/4/1" - -p "q4" fourth quarter of the current year - - Period expressions with a report interval - A period expression can also begin with a report interval, separated - from the start/end dates (if any) by a space or the word in: - - -p "weekly from 2009/1/1 to 2009/4/1" - -p "monthly in 2008" - -p "quarterly" - - More complex report intervals - Some more complex intervals can be specified within period expressions, - such as: - - o biweekly (every two weeks) - - o fortnightly - - o bimonthly (every two months) - - o every day|week|month|quarter|year - - o every N days|weeks|months|quarters|years - - Weekly on a 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 a custom day: - - o every Nth day [of month] - - o every Nth WEEKDAYNAME [of month] - - Yearly on a 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 "bimonthly from 2008" - -p "every 2 weeks" - -p "every 5 months from - 2009/03" - -p "every 2nd day of week" periods will go from Tue to Tue - -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each - month - -p "every 2nd Monday" period boundaries will be on second Monday - of each month - -p "every 11/05" yearly periods with boundaries on 5th of - 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" - - Multiple weekday intervals - This special form is also supported: - - o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- - day names, case insensitive) - - Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and - sat,sun. - - This is mainly intended for use with --forecast, to generate periodic - transactions on arbitrary days of the week. It may be less useful with - -p, since it divides each week into subperiods of unequal length, which - is unusual. (Related: #1632) - - Examples: - - -p "every dates will be Mon, Wed, Fri; periods will be Mon- - 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), reports will show ac- - counts only to the specified depth, hiding deeper subaccounts. Use - this when you want a summary with less detail. This flag has the same - effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- - lent. - -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 ac- - count 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:202312- - status: - desc:amazon - cur:USD - "amt:>0" - - o Add a not: prefix to negate: - - not:cur:USD - - o Multiple unlike terms are AND-ed, multiple like terms are OR-ed - - date:2022 desc:amazon desc:amzn - (all transactions with "amazon" or "amzn" in description during 2022) - - 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 es- - caping. 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 in- - terval. 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. - - expr:"TERM AND NOT (TERM OR TERM)" (eg) - Match with a boolean combination of queries (which must be enclosed in - quotes). See Combining query terms below. - - 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 - When given multiple space-separated 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. - - The print command is a little different, showing 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. - - We also support more complex boolean queries with the 'expr:' prefix. - This allows one to combine queries using one of three operators: AND, - OR, and NOT, where NOT is different syntax for 'not:'. - - Examples of such queries are: - - o Match transactions with 'cool' in the description AND with the 'A' - tag - - expr:"desc:cool AND tag:A" - - o Match transactions NOT to the 'expenses:food' account OR with the 'A' - tag - - expr:"NOT expenses:food OR tag:A" - - o Match transactions NOT involving the 'expenses:food' account OR with - the 'A' tag AND involving the 'expenses:drink' account. (the AND is - implicitly added by space-separation, following the rules above) - - expr:"expenses:food OR (tag:A expenses:drink)" - - Queries and command options - Some queries can also be expressed as command-line options: depth:2 is - equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When - you mix command options and query arguments, generally the resulting - query is their intersection. - - Queries and valuation - When amounts are converted to other commodities in cost or value re- - ports, 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 re- - versed, 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 re- - ports, 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. - -Pivoting - Normally, hledger groups and sums amounts within each account. The - --pivot FIELD option substitutes some other transaction field for ac- - count names, causing amounts to be grouped and summed by that field's - value instead. FIELD can be any of the transaction fields acct, sta- - tus, code, desc, payee, note, or a tag name. When pivoting on a tag - and a posting has multiple values of that tag, only the first value is - displayed. Values containing colon:separated:parts will be displayed - hierarchically, like account names. Multiple, colon-delimited fields - can be pivoted simultaneously, generating a hierarchical account name. - - Some examples: - - 2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe, kind: Lifetime - - Normal balance report showing account names: - - $ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues - -------------------- - 0 - - Pivoted balance report, using member: tag values instead: - - $ hledger balance --pivot member - 2 EUR - -2 EUR John Doe - -------------------- - 0 - - One way to show only amounts with a member: value (using a query): - - $ hledger balance --pivot member tag:member=. - -2 EUR John Doe - -------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account - name"): - - $ hledger balance --pivot member acct:. - -2 EUR John Doe - -------------------- - -2 EUR - - Hierarchical reports can be generated with multiple pivots: - - $ hledger balance Income:Dues --pivot kind:member - -2 EUR Lifetime:John Doe - -------------------- - -2 EUR - -Generating data - hledger has several features for generating data, such as: - - o Periodic transaction rules can generate single or repeating transac- - tions following a template. These are usually dated in the future, - eg to help with forecasting. They are activated by the --forecast - option. - - o The balance command's --budget option uses these same periodic rules - to generate goals for the budget report. - - o Auto posting rules can generate extra postings on certain matched - transactions. They are always applied to forecast transactions; with - the --auto flag they are applied to transactions recorded in the - journal as well. - - o The --infer-equity flag infers missing conversion equity postings - from @/@@ costs. And the inverse --infer-costs flag infers missing - @/@@ costs from conversion equity postings. - - Generated data of this kind is temporary, existing only at report time. - But you can see it in the output of hledger print, and you can save - that to your journal, in effect converting it from temporary generated - data to permanent recorded data. This could be useful as a data entry - aid. - - If you are wondering what data is being generated and why, add the - --verbose-tags flag. In hledger print output you will see extra tags - like generated-transaction, generated-posting, and modified on gener- - ated/modified data. Also, even without --verbose-tags, generated data - always has equivalen hidden tags (with an underscore prefix), so eg you - could match generated transactions with tag:_generated-transaction. - -Forecasting - Forecasting, or speculative future reporting, can be useful for esti- - mating future balances, or for exploring different future scenarios. - - The simplest and most flexible way to do it with hledger is to manually - record a bunch of future-dated transactions. You could keep these in a - separate future.journal and include that with -f only when you want to - see them. - - --forecast - There is another way: with the --forecast option, hledger can generate - temporary "forecast transactions" for reporting purposes, according to - periodic transaction rules defined in the journal. Each rule can gen- - erate multiple recurring transactions, so by changing one rule you can - change many forecasted transactions. (These same rules can also gener- - ate budget goals, described in Budgeting.) - - Forecast transactions usually start after ordinary transactions end. - By default, they begin after your latest-dated ordinary transaction, or - today, whichever is later, and they end six months from today. (The - exact rules are a little more complicated, and are given below.) - - This is the "forecast period", which need not be the same as the report - period. You can override it - eg to forecast farther into the future, - or to force forecast transactions to overlap your ordinary transactions - - by giving the --forecast option a period expression argument, like - --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- - quired. - - Inspecting forecast transactions - print is the best command for inspecting and troubleshooting forecast - transactions. Eg: - - ~ monthly from 2022-12-20 rent - assets:bank:checking - expenses:rent $1000 - - $ hledger print --forecast --today=2023/4/21 - 2023-05-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-06-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-07-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-08-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-09-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - Here there are no ordinary transactions, so the forecasted transactions - begin on the first occurence after today's date. (You won't normally - use --today; it's just to make these examples reproducible.) - - Forecast reports - Forecast transactions affect all reports, as you would expect. Eg: - - $ hledger areg rent --forecast --today=2023/4/21 - Transactions in expenses:rent and subaccounts: - 2023-05-20 rent as:ba:checking $1000 $1000 - 2023-06-20 rent as:ba:checking $1000 $2000 - 2023-07-20 rent as:ba:checking $1000 $3000 - 2023-08-20 rent as:ba:checking $1000 $4000 - 2023-09-20 rent as:ba:checking $1000 $5000 - - $ hledger bal -M expenses --forecast --today=2023/4/21 - Balance changes in 2023-05-01..2023-09-30: - - || May Jun Jul Aug Sep - ===============++=================================== - expenses:rent || $1000 $1000 $1000 $1000 $1000 - ---------------++----------------------------------- - || $1000 $1000 $1000 $1000 $1000 - - Forecast tags - Forecast transactions generated by --forecast have a hidden tag, _gen- - erated-transaction. So if you ever need to match forecast transac- - tions, you could use tag:_generated-transaction (or just tag:generated) - in a query. - - For troubleshooting, you can add the --verbose-tags flag. Then, visi- - ble generated-transaction tags will be added also, so you can view them - with the print command. Their value indicates which periodic rule was - responsible. - - Forecast period, in detail - Forecast start/end dates are chosen so as to do something useful by de- - fault in almost all situations, while also being flexible. Here are - (with luck) the exact rules, to help with troubleshooting: - - The forecast period starts on: - - o the later of - - o the start date in the periodic transaction rule - - o the start date in --forecast's argument - - o otherwise (if those are not available): the later of - - o the report start date specified with -b/-p/date: - - o the day after the latest ordinary transaction in the journal - - o otherwise (if none of these are available): today. - - The forecast period ends on: - - o the earlier of - - o the end date in the periodic transaction rule - - o the end date in --forecast's argument - - o otherwise: the report end date specified with -e/-p/date: - - o otherwise: 180 days (~6 months) from today. - - Forecast troubleshooting - When --forecast is not doing what you expect, one of these tips should - help: - - o Remember to use the --forecast option. - - o Remember to have at least one periodic transaction rule in your jour- - nal. - - o Test with print --forecast. - - o Check for typos or too-restrictive start/end dates in your periodic - transaction rule. - - o Leave at least 2 spaces between the rule's period expression and de- - scription fields. - - o Check for future-dated ordinary transactions suppressing forecasted - transactions. - - o Try setting explicit report start and/or end dates with -b, -e, -p or - date: - - o Try adding the -E flag to encourage display of empty periods/zero - transactions. - - o Try setting explicit forecast start and/or end dates with --fore- - cast=START..END - - o Consult Forecast period, in detail, above. - - o Check inside the engine: add --debug=2 (eg). - -Budgeting - With the balance command's --budget report, each periodic transaction - rule generates recurring budget goals in specified accounts, and goals - and actual performance can be compared. See the balance command's doc - below. - - You can generate budget goals and forecast transactions at the same - time, from the same or different periodic transaction rules: hledger - bal -M --budget --forecast ... - - See also: Budgeting and Forecasting. - -Cost reporting - In some transactions - for example a currency conversion, or a purchase - or sale of stock - one commodity is exchanged for another. In these - transactions there is a conversion rate, also called the cost (when - buying) or selling price (when selling). In hledger docs we just say - "cost", for convenience; feel free to mentally translate to "conversion - rate" or "selling price" if helpful. - - Recording costs - We'll explore several ways of recording transactions involving costs. - These are also summarised at hledger Cookbook > Cost notation. - - Costs can be recorded explicitly in the journal, using the @ UNITCOST - or @@ TOTALCOST notation described in Journal > Costs: - - Variant 1 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 @ $1.35 ; $1.35 per euro (unit cost) - - Variant 2 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 @@ $135 ; $135 total cost - - Typically, writing the unit cost (variant 1) is preferable; it can be - more effort, requiring more attention to decimal digits; but it reveals - the per-unit cost basis, and makes stock sales easier. - - Costs can also be left implicit, and hledger will infer the cost that - is consistent with a balanced transaction: - - Variant 3 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 - - Here, hledger will attach a @@ 100 cost to the first amount (you can - see it with hledger print -x). This form looks convenient, but there - are downsides: - - o It sacrifices some error checking. For example, if you accidentally - wrote 10 instead of 100, hledger would not be able to detect the mis- - take. - - o It is sensitive to the order of postings - if they were reversed, a - different entry would be inferred and reports would be different. - - o The per-unit cost basis is not easy to read. - - So generally this kind of entry is not recommended. You can make sure - you have none of these by using -s (strict mode), or by running hledger - check balanced. - - Reporting at cost - Now when you add the -B/--cost flag to reports ("B" is from Ledger's - -B/--basis/--cost flag), any amounts which have been annotated with - costs will be converted to their cost's commodity (in the report out- - put). Ie they will be displayed "at cost" or "at sale price". - - Some things to note: - - o Costs are attached to specific posting amounts in specific transac- - tions, and once recorded they do not change. This contrasts with - market prices, which are ambient and fluctuating. - - o Conversion to cost is performed before conversion to market value - (described below). - - Equity conversion postings - There is a problem with the entries above - they are not conventional - Double Entry Bookkeeping (DEB) notation, and because of the "magical" - transformation of one commodity into another, they cause an imbalance - in the Accounting Equation. This shows up as a non-zero grand total in - balance reports like hledger bse. - - For most hledger users, this doesn't matter in practice and can safely - be ignored ! But if you'd like to learn more, keep reading. - - Conventional DEB uses an extra pair of equity postings to balance the - transaction. Of course you can do this in hledger as well: - - Variant 4 - - 2022-01-01 - assets:dollars $-135 - assets:euros 100 - equity:conversion $135 - equity:conversion -100 - - Now the transaction is perfectly balanced according to standard DEB, - and hledger bse's total will not be disrupted. - - And, hledger can still infer the cost for cost reporting, but it's not - done by default - you must add the --infer-costs flag like so: - - $ hledger print --infer-costs - 2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 @@ 100 - assets:euros 100 - equity:conversion $135 - equity:conversion -100 - - $ hledger bal --infer-costs -B - -100 assets:dollars - 100 assets:euros - -------------------- - 0 - - Here are some downsides of this kind of entry: - - o The per-unit cost basis is not easy to read. - - o Instead of -B you must remember to type -B --infer-costs. - - o --infer-costs works only where hledger can identify the two eq- - uity:conversion postings and match them up with the two non-equity - postings. So writing the journal entry in a particular format be- - comes more important. More on this below. - - Inferring equity conversion postings - Can we go in the other direction ? Yes, if you have transactions writ- - ten with the @/@@ cost notation, hledger can infer the missing equity - postings, if you add the --infer-equity flag. Eg: - - 2022-01-01 - assets:dollars -$135 - assets:euros 100 @ $1.35 - - $ hledger print --infer-equity - 2022-01-01 - assets:dollars $-135 - assets:euros 100 @ $1.35 - equity:conversion:$-: -100 - equity:conversion:$-:$ $135.00 - - The equity account names will be "equity:conversion:A-B:A" and "eq- - uity:conversion:A-B:B" where A is the alphabetically first commodity - symbol. You can customise the "equity:conversion" part by declaring an - account with the V/Conversion account type. - - Combining costs and equity conversion postings - Finally, you can use both the @/@@ cost notation and equity postings at - the same time. This in theory gives the best of all worlds - preserv- - ing the accounting equation, revealing the per-unit cost basis, and - providing more flexibility in how you write the entry: - - Variant 5 - - 2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion -100 - assets:euros 100 @ $1.35 - - All the other variants above can (usually) be rewritten to this final - form with: - - $ hledger print -x --infer-costs --infer-equity - - Downsides: - - o This was added in hledger-1.29 and is still somewhat experimental. - - o The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it - will give a transaction balancing error. - - o The add command does not yet accept this kind of entry (#2056). - - o This is the most verbose form. - - Requirements for detecting equity conversion postings - --infer-costs has certain requirements (unlike --infer-equity, which - always works). It will infer costs only in transactions with: - - o Two non-equity postings, in different commodities. Their order is - significant: the cost will be added to the first of them. - - o Two postings to equity conversion accounts, next to one another, - which balance the two non-equity postings. This balancing is checked - to the same precision (number of decimal places) used in the conver- - sion posting's amount. Equity conversion accounts are: - - o any accounts declared with account type V/Conversion, or their sub- - accounts - - o otherwise, accounts named equity:conversion, equity:trade, or eq- - uity:trading, or their subaccounts. - - And multiple such four-posting groups can coexist within a single - transaction. When --infer-costs fails, it does not infer a cost in - that transaction, and does not raise an error (ie, it infers costs - where it can). - - Reading variant 5 journal entries, combining cost notation and equity - postings, has all the same requirements. When reading such an entry - fails, hledger raises an "unbalanced transaction" error. - - Infer cost and equity by default ? - Should --infer-costs and --infer-equity be enabled by default ? Try - using them always, eg with a shell alias: - - alias h="hledger --infer-equity --infer-costs" - - and let us know what problems you find. - -Value reporting - 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] op- - tion, 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 - Market prices can change from day to day. hledger will use the prices - on a particular valuation date (or on more than one date). By default - hledger uses "end" dates for valuation. More specifically: - - o For single period reports (including normal print and register re- - ports): - - o If an explicit report end date is specified, that is used - - o Otherwise the latest transaction date or P directive date is used - (even if it's in the future) - - o For multiperiod reports, each period is valued on its last day. - - This can be customised with the --value option described below, which - can select either "then", "end", "now", or "custom" dates. (Note, this - has a bug in hledger-ui <=1.31: turning on valuation with the V key al- - ways resets it to "end".) - - Finding market price - To convert a commodity A to its market value in another commodity B, - hledger looks for a suitable market price (exchange rate) as follows, - in this order of preference: - - 1. A declared market price or inferred market price: A's latest market - price in B on or before the valuation date as declared by a P direc- - tive, or (with the --infer-market-prices flag) inferred from costs. - - 2. A reverse market price: the inverse of a declared or inferred market - price from B to A. - - 3. A forward chain of market prices: a synthetic price formed by 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 costs as additional market prices (as - Ledger does) ? Adding the --infer-market-prices flag to -V, -X or - --value enables this. - - So for example, hledger bs -V --infer-market-prices will get market - prices both from P directives and from transactions. If both occur on - the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, - read all of this Value reporting 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 multicommodity transactions with equity postings, if cost is inferred - with --infer-costs. - - There is a limitation (bug) currently: when a valuation commodity is - not specified, prices inferred with --infer-market-prices do not help - select a default valuation commodity, as P prices would. So conversion - might not happen because no valuation commodity was detected (--debug=2 - will show this). To be safe, specify the valuation commmodity, eg: - - 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 - - Signed costs and market prices can be confusing. For reference, here - is the current behaviour, since hledger 1.25. (If you think it should - work differently, see #1870.) - - 2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - - 2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - - 2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - - 2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - - 2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - - 2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each day, - the two transactions are considered equivalent). Here are the market - prices inferred for B: - - $ hledger -f- --infer-market-prices prices - P 2022-01-01 B A 1 - P 2022-01-01 B A 1.0 - P 2022-01-02 B A -1 - P 2022-01-02 B A -1.0 - P 2022-01-03 B A -1 - P 2022-01-03 B A -1.0 - - 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, - costs 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 $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 - - --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 - - 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. Re- - lated: #329, #1083. - - Report -B, --cost -V, -X --value=then --value=end --value=DATE, - type --value=now - -------------------------------------------------------------------------------------------- - print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today - today journal end - balance unchanged unchanged unchanged unchanged unchanged - asser- - tions/as- - signments - - register - starting cost value at re- valued at day value at re- value at - balance port or each historical port or DATE/today - (-H) journal end posting was made journal end - starting cost value at day valued at day value at day value at - balance before re- each historical before re- DATE/today - (-H) with port or posting was made port or - report journal journal - interval start start - posting cost value at re- value at posting value at re- value at - amounts port or date port or DATE/today - journal end journal end - summary summarised value at pe- sum of postings value at pe- value at - posting cost riod ends in interval, val- riod ends DATE/today - amounts ued at interval - with re- start - port in- - terval - running sum/average sum/average sum/average of sum/average sum/average - total/av- of displayed of displayed displayed values of displayed of displayed - erage values values values values - - balance - (bs, bse, - cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of - 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 - (--bud- - get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- - tal played val- played val- valued played val- played values - ues ues ues - - balance - (bs, bse, - cf, is) - with re- - port in- - terval - starting sums of value at re- sums of values of value at re- sums of post- - balances costs of port start postings before port start ings before - (-H) postings be- of sums of report start at of sums of report start - fore report all postings respective post- all postings - start before re- ing dates before re- - port start port start - balance sums of same as sums of values of balance value at - changes costs of --value=end postings in pe- change in DATE/today of - (bal, is, postings in riod at respec- each period, sums of post- - bs period tive posting valued at ings - --change, dates period ends - cf - --change) - end bal- sums of same as sums of values of period end value at - ances costs of --value=end postings from be- balances, DATE/today of - (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings - bs, cf) report start respective post- - to period ing dates - end - budget like balance like balance like balance like bal- like balance - amounts changes/end changes/end changes/end bal- ances changes/end - (--bud- balances balances ances balances - get) - row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- - averages played val- played val- played val- played values - (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- - totals played val- played val- values played val- played values - ues ues ues - grand to- sum, average sum, average sum, average of sum, average sum, average - tal, of column of column column totals of column of column to- - grand av- totals totals totals tals - erage - - - --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). - -PART 4: COMMANDS - Commands overview - Here are the built-in commands: - - DATA ENTRY - These data entry commands are the only ones which can modify your jour- - nal file. - - o add - add transactions using terminal prompts - - o import - add new transactions from other files, eg CSV files - - DATA CREATION - o close - generate balance-zeroing/restoring transactions - - o rewrite - generate auto postings, like print --auto - - DATA MANAGEMENT - o check - check for various kinds of error in the data - - o diff - compare account transactions in two journal files - - REPORTS, FINANCIAL - 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 - - REPORTS, VERSATILE - o balance (bal) - show balance changes, end balances, budgets, gains.. - - o print - show transactions or export journal data - - o register (reg) - show postings in one or more accounts & running to- - tal - - o roi - show return on investments - - REPORTS, BASIC - o accounts - show account names - - o activity - show bar charts of posting counts per period - - o codes - show transaction codes - - o commodities - show commodity/currency symbols - - o descriptions - show transaction descriptions - - o files - show input file paths - - o notes - show note parts of transaction descriptions - - o payees - show payee parts of transaction descriptions - - o prices - show market prices - - o stats - show journal statistics - - o tags - show tag names - - o test - run self tests - - HELP - o help - show the hledger manual with info/man/pager - - o demo - show small hledger demos in the terminal - - ADD-ONS - And here are some typical add-on commands. Some of these are installed - by the hledger-install script. If installed, they will appear in - hledger's commands list: - - o ui - run hledger's terminal UI - - o web - run hledger's web UI - - o iadd - add transactions using a TUI (currently hard to build) - - o interest - generate interest transactions - - o stockquotes - download market prices from AlphaVantage - - o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, - pijul, plot, and more.. - - Next, each command is described in detail, in alphabetical order. - - accounts - Show account names. - - This command lists account names. By default it shows all known ac- - counts, either used in transactions or declared with account direc- - tives. - - With query arguments, only matched account names and account names ref- - erenced by matched postings are shown. - - Or it can show just the used accounts (--used/-u), the declared ac- - counts (--declared/-d), the accounts declared but not used (--unused), - the accounts used but not declared (--undeclared), or the first account - matched by an account name pattern, if any (--find). - - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. In flat mode you can add --drop N to omit - the first few account name components. Account names can be depth- - clipped with depth:N or --depth N or -N. - - With --types, it also shows each account's type, if it's known. (See - Declaring accounts > Account types.) - - With --positions, it also shows the file and line number of each ac- - count's declaration, if any, and the account's overall declaration or- - der; these may be useful when troubleshooting account display order. - - With --directives, it adds the account keyword, showing valid account - directives which can be pasted into a journal file. This is useful to- - gether with --undeclared when updating your account declarations to - satisfy hledger check accounts. - - The --find flag can be used to look up a single account name, in the - same way that the aregister command does. It returns the alphanumeri- - cally-first matched account name, or if none can be found, it fails - with a non-zero exit code. - - Examples: - - $ hledger accounts - assets:bank:checking - assets:bank:saving - assets:cash - expenses:food - expenses:supplies - income:gifts - income:salary - liabilities:debts - - $ hledger accounts --undeclared --directives >> $LEDGER_FILE - $ hledger check accounts - - 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 - 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 de- - scription) 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, pay- - ees/descriptions, 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 https://hledger.org/add.html for a detailed tutorial): - - $ hledger add - Adding transactions to journal file /src/hledger/examples/sample.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to go one step backward. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2015/05/22]: - Description: supermarket - Account 1: expenses:food - Amount 1: $10 - Account 2: assets:checking - Amount 2 [$-10.0]: - Account 3 (or . or enter to finish this transaction): . - 2015/05/22 supermarket - expenses:food $10 - assets:checking $-10.0 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2015/05/22]: $ - - On Microsoft Windows, the add command makes sure that no part of the - file path ends with a period, as that would cause problems (#1056). - - aregister - (areg) - - Show the transactions and running historical balance of a single ac- - count, 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 in- - cluded 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 ex- - pression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can be - surprising; eg if you have assets:per:checking 1 and assets:biz:check- - ing 2 accounts, hledger areg checking would select assets:biz:checking - 2. It's just a convenience to save typing, so if in doubt, write the - full account name, or a distinctive substring that matches uniquely. - - Transactions involving subaccounts of this account will also be shown. - aregister ignores depth limits, so its final total will always match a - balance report with similar arguments. - - Any additional arguments form a query which will filter the 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 op- - tions. The output formats supported are txt, csv, tsv, and json. - - aregister and posting dates - aregister always shows one line (and date and amount) per transaction. - But sometimes transactions have postings with different dates. Also, - not all of a transaction's postings may be within the report period. - To resolve this, aregister shows the earliest of the transaction's date - and posting dates that is in-period, and the sum of the in-period post- - ings. In other words it will show a combined line item with just the - earliest date, and the running balance will (temporarily, until the - transaction's last posting) be inaccurate. Use register -H if you need - to see the individual postings. - - There is also a --txn-dates flag, which filters strictly by transaction - date, ignoring posting dates. This too can cause an inaccurate running - 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) - - o or postings count (--count) - - ..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 (--in- - vert) - - 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, tsv, 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. ("Simple" here - means just one column of numbers, covering a single period. You can - also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end bal- - ance 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 (re- - vealing 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. - - Balance report line format - For single-period balance reports displayed in the terminal (only), you - can use --format FMT to customise the format and content of each line. - Eg: - - $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 - --------------------------------- - 0 - - The FMT format string specifies the formatting applied to each ac- - count/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 ef- - fect, 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 - - 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 - - Showing declared accounts - With --declared, accounts which have been declared with an account di- - rective 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 re- - port, even when you don't have transactions in all of your declared ac- - counts yet. - - 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 - biggest averaged monthly expenses first. When more than one commodity - is present, they will be sorted by the alphabetically earliest commod- - ity 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 --in- - vert 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. - - 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: - - 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 - - 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 ac- - count 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 - The balance command is quite flexible; here is the full detail on how - to control what it reports. If the following seems complicated, don't - worry - this is for advanced reporting, and it does take time and ex- - perimentation to get familiar with all the report modes. - - There are three important option groups: - - hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] - ... - - Calculation type - The basic calculation to perform for each table cell. It is one of: - - o --sum : sum the posting amounts (default) - - o --budget : sum the amounts, but also show the budget goal amount (for - each account/period) - - 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) - - o --count : show the count of postings - - Accumulation type - How amounts should accumulate across report periods. Another way to - say it: which time period's postings should contribute to each cell's - calculation. It is one of: - - o --change : calculate with postings from column start to column end, - ie "just this column". Typically used to see revenues/expenses. - (default for balance, incomestatement) - - o --cumulative : calculate with postings from report start to column - end, ie "previous columns plus this column". Typically used to show - changes accumulated since the report's start date. Not often used. - - o --historical/-H : calculate with postings from journal start to col- - umn end, ie "all postings from before report start date until this - column's end". Typically used to see historical end balances of as- - sets/liabilities/equity. (default for balancesheet, balancesheete- - quity, cashflow) - - Valuation type - Which kind of value or cost conversion should be applied, if any, be- - fore displaying the report. It is one of: - - o no valuation type : don't convert to cost or value (default) - - o --value=cost[,COMM] : convert amounts to cost (then optionally to - some other commodity) - - o --value=then[,COMM] : convert amounts to market value on transaction - dates - - o --value=end[,COMM] : convert amounts to market value on period end - date(s) - (default with --valuechange, --gain) - - o --value=now[,COMM] : convert amounts to market value on today's date - - o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- - other date - - or one of the equivalent simpler flags: - - o -B/--cost : like --value=cost (though, note --cost and --value are - independent options which can both be used at once) - - o -V/--market : like --value=end - - o -X COMM/--exchange COMM : like --value=end,COMM - - See Cost reporting and Value reporting for more about these. - - Combining balance report types - Most combinations of these options should produce reasonable reports, - but if you find any that seem wrong or misleading, let us know. The - following restrictions are applied: - - 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 pe- - ues in period in period riod - --cumu- change from re- sum of posting- period-end DATE-value of - lative port 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 - - Budget report - The --budget report type activates extra columns showing any budget - goals for each account and period. The budget goals are defined by pe- - riodic transactions. This is useful for comparing planned and actual - income, expenses, time usage, etc. - - For example, you can take average monthly expenses in the common ex- - pense 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. Cur- - rently: - - o Accounts with budget goals during the report period, and their par- - ents, are shown. - - o Their subaccounts are not shown (regardless of the depth setting). - - o Accounts without budget goals, if any, are aggregated and shown as - "". - - o Amounts are always inclusive (subaccount-including), even in list - mode. - - o After each actual amount, the corresponding goal amount and percent- - age of goal reached are also shown, in square brackets. - - This means that the numbers displayed will not always add up! Eg - above, the expenses actual amount includes the gifts and supplies - transactions, but the expenses:gifts and expenses:supplies accounts are - not shown, as they have no budget amounts declared. - - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted - ones, giving the full picture. Eg: - - $ hledger balance -M --budget --empty - Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - expenses:supplies || $20 0 - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] - ----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - You can roll over unspent budgets to next period with --cumulative: - - $ hledger balance -M --budget --cumulative - Budget performance in 2017/11/01-2017/12/31: - - || Nov Dec - ======================++==================================================== - assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] - expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] - expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] - income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] - ----------------------++---------------------------------------------------- - || 0 [ 0] 0 [ 0] - - It's common to limit budgets/budget reports to just expenses - - hledger bal -M --budget expenses - - or just revenues and expenses (eg, using account types): - - hledger bal -M --budget type:rx - - It's also common to limit or convert them to a single currency - (cur:COMM or -X COMM [--infer-market-prices]). If showing multiple - currencies, --layout bare or --layout tall can help. - - For more examples and notes, see Budgeting. - - 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 to- - wards 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: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 ac- - count in each report subperiod. When troubleshooting, you can use - print --forecast to show these as forecasted transactions: - - $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated - - By default, the budget report uses all available periodic transaction - rules to generate goals. This includes rules with a different report - interval from your report. Eg if you have daily, weekly and monthly - periodic rules, all of these will contribute to the goals in a monthly - budget report. - - You can select a subset of periodic rules by providing an argument to - the --budget flag. --budget=DESCPAT will match all periodic rules - whose description contains DESCPAT, a case-insensitive substring (not a - regular expression or query). This means you can give your periodic - rules descriptions (remember that two spaces are needed), and then se- - lect from multiple budgets defined in your journal. - - Budget vs forecast - hledger --forecast ... and hledger balance --budget ... are separate - features, though both of them use the periodic transaction rules de- - fined in the journal, and both of them generate temporary transactions - for reporting purposes ("forecast transactions" and "budget goal trans- - actions", respectively). You can use both features at the same time if - you want. Here are some differences between them, as of hledger 1.29: - - CLI: - - o --forecast is a general hledger option, usable with any command - - o --budget is a balance command option, usable only with that command. - - Visibility of generated transactions: - - o forecast transactions are visible in any report, like ordinary trans- - actions - - o budget goal transactions are invisible except for the goal amounts - they produce in --budget reports. - - Periodic transaction rules: - - o --forecast uses all available periodic transaction rules - - o --budget uses all periodic rules (--budget) or a selected subset - (--budget=DESCPAT) - - Period of generated transactions: - - o --forecast generates forecast transactions - - o from after the last regular transaction to the end of the report - period (--forecast) - - o or, during a specified period (--forecast=PERIODEXPR) - - o possibly further restricted by a period specified in the periodic - transaction rule - - o and always restricted within the bounds of the report period - - o --budget generates budget goal transactions - - o throughout the report period - - o possibly restricted by a period specified in the periodic transac- - tion rule. - - Balance report layout - The --layout option affects how balance reports show multi-commodity - amounts and commodity symbols, which can improve readability. It can - also normalise the data for easy consumption by other programs. It has - four possible values: - - o --layout=wide[,WIDTH]: commodities are shown on a single line, op- - tionally elided to WIDTH - - o --layout=tall: each commodity is shown on a separate line - - o --layout=bare: commodity symbols are in their own column, amounts are - bare numbers - - o --layout=tidy: data is normalised to easily-consumed "tidy" form, - with one row per data value - - Here are the --layout modes supported by each output format; note only - CSV output supports all of them: - - - txt csv html json sql - ------------------------------------- - wide Y Y Y - tall Y Y Y - bare Y Y Y - tidy Y - - Examples: - - 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 for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - - o Note: bare layout will sometimes display an extra row for the no-sym- - bol commodity, because of zero amounts (hledger treats zeroes as com- - modity-less, usually). This can break hledger-bar confusingly - (workaround: add a cur: query to exclude the no-symbol row). - - o Tidy layout produces normalised "tidy data", where every variable has - its own column and each row represents a single data point. See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- - data.html for more. This is the easiest kind of data for other soft- - ware to consume. Here's how it looks: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - 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 - - 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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - 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 in- - sensitive, 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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - 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 al- - lowed) - - o whose name contains some variation of cash, bank, checking or saving. - - More precisely: all accounts matching this case insensitive regular ex- - pression: - - ^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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - check - Check for various kinds of errors in your data. - - hledger provides a number of built-in error checks to help prevent - problems in your data. Some of these are run automatically; or, you - can use this check command to run them on demand, with no output and a - zero exit code if all is well. Specify their names (or a prefix) as - argument(s). - - Some examples: - - hledger check # basic checks - hledger check -s # basic + strict checks - hledger check ordereddates payees # basic + two other checks - - If you are an Emacs user, you can also configure flycheck-hledger to - run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available: - - Default checks - These checks are run automatically by (almost) all hledger commands: - - o parseable - data files are in a supported format, with no syntax er- - rors and no invalid include directives. - - o autobalanced - all transactions are balanced, after converting to - cost. Missing amounts and missing costs are inferred automatically - where possible. - - 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 balanced - all transactions are balanced after converting to cost, - without inferring missing costs. If conversion costs are required, - they must be explicit. - - o accounts - all account names used by transactions have been declared - - o commodities - all commodity symbols used have been declared - - 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: - - o ordereddates - transactions are ordered by date within each file - - o payees - all payees used by transactions have been declared - - o recentassertions - all accounts with balance assertions have a bal- - ance assertion within 7 days of their latest posting - - o tags - all tags 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. - - More about specific checks - hledger check recentassertions will complain if any balance-asserted - account has postings more than 7 days after its latest balance asser- - tion. This aims to prevent the situation where you are regularly up- - dating your journal, but forgetting to check your balances against the - real world, then one day must dig back through months of data to find - an error. It assumes that adding a balance assertion requires/reminds - you to check the real-world balance. (That may not be true if you - auto-generate balance assertions from bank data; in that case, I recom- - mend to import transactions uncleared, and when you manually review and - clear them, also check the latest assertion against the real-world bal- - ance.) - - close - (equity) - - Generate transactions which transfer account balances to and/or from - another account (typically equity). This can be useful for migrating - balances to a new journal file, or for merging earnings into equity at - end of accounting period. - - By default, it prints a transaction that zeroes out ALE accounts (as- - set, liability, equity accounts; this requires account types to be con- - figured); or if ACCTQUERY is provided, the accounts matched by that. - - (experimental) - - This command has four main modes, corresponding to the most common use - cases: - - 1. With --close (default), it prints a "closing balances" transaction - that zeroes out ALE (asset, liability, equity) accounts by default - (this requires account types to be inferred or declared); or, the - accounts matched by the provided ACCTQUERY arguments. - - 2. With --open, it prints an opposite "opening balances" transaction - that restores those balances from zero. This is similar to Ledger's - equity command. - - 3. With --migrate, it prints both the closing and opening transactions. - This is the preferred way to migrate balances to a new file: run - hledger close --migrate, add the closing transaction at the end of - the old file, and add the opening transaction at the start of the - new file. The matching closing/opening transactions cancel each - other out, preserving correct balances during multi-file reporting. - - 4. With --retain, it prints a "retain earnings" transaction that trans- - fers RX (revenue and expense) balances to equity:retained earnings. - Businesses traditionally do this at the end of each accounting pe- - riod; it is less necessary with computer-based accounting, but it - could still be useful if you want to see the accounting equation - (A=L+E) satisfied. - - In all modes, the defaults can be overridden: - - o the transaction descriptions can be changed with --close-desc=DESC - and --open-desc=DESC - - o the account to transfer to/from can be changed with --close-acct=ACCT - and --open-acct=ACCT - - o the accounts to be closed/opened can be changed with ACCTQUERY (ac- - count query arguments). - - o the closing/opening dates can be changed with -e DATE (a report end - date) - - By default just one destination/source posting will be used, with its - amount left implicit. With --x/--explicit, the amount will be shown - explicitly, and if it involves multiple commodities, a separate posting - will be generated for each of them (similar to print -x). - - With --show-costs, any amount costs are shown, with separate postings - for each cost. This is currently the best way to view investment lots. - If you have many currency conversion or investment transactions, it can - generate very large journal entries. - - With --interleaved, each individual transfer is shown with source and - destination postings next to each other. This could be useful for - troubleshooting. - - The default closing date is yesterday, or the journal's end date, - whichever is later. You can change this by specifying a report end - date with -e. The last day of the report period will be the closing - date, eg -e 2024 means "close on 2023-12-31". The opening date is al- - ways the day after the closing date. - - close and balance assertions - Balance assertions will be generated, verifying that the accounts have - been reset to zero (and then restored to their previous balances, if - there is an opening transaction). - - These provide useful error checking, but you can ignore them temporar- - ily with -I, or remove them if you prefer. - - You probably should avoid filtering transactions by status or realness - (-C, -R, status:), or generating postings (--auto), with this command, - since the balance assertions would depend on these. - - Note custom posting dates spanning the file boundary will disrupt the - balance assertions: - - 2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve that you can transfer the money to and from a temporary ac- - count, in effect splitting the multi-day transaction into two single- - day transactions: - - ; in 2022.journal: - 2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - - ; in 2023.journal: - 2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - Example: retain earnings - Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- - pending the generated transaction to the journal: - - $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - Note 2022's income statement will now show only zeroes, because rev- - enues and expenses have been moved entirely to equity. To see them - again, you could exclude the retain transaction: - - $ hledger -f 2022.journal is not:desc:'retain earnings' - - Example: migrate balances to a new file - Close assets/liabilities/equity on 2022-12-31 and re-open them on - 2023-01-01: - - $ hledger close --migrate -f 2022.journal -p 2022 - # copy/paste the closing transaction to the end of 2022.journal - # copy/paste the opening transaction to the start of 2023.journal - - Now 2022's balance sheet will show only zeroes, indicating a balanced - accounting equation. (Unless you are using @/@@ notation - in that - case, try adding --infer-equity.) To see the end-of-year balances - again, you could exclude the closing transaction: - - $ hledger -f 2022.journal bs not:desc:'closing balances' - - Example: excluding closing/opening transactions - When combining many files for multi-year reports, the closing/opening - transactions cause some noise in transaction-oriented reports like - print and register. You can exclude them as shown above, but - not:desc:... is not ideal as it depends on consistent descriptions; - also you will want to avoid excluding the very first opening transac- - tion, which could be awkward. Here is one alternative, using tags: - - Add clopen: tags to all opening/closing balances transactions except - the first, like this: - - ; 2021.journal - 2021-06-01 first opening balances - ... - 2021-12-31 closing balances ; clopen:2022 - ... - - ; 2022.journal - 2022-01-01 opening balances ; clopen:2022 - ... - 2022-12-31 closing balances ; clopen:2023 - ... - - ; 2023.journal - 2023-01-01 opening balances ; clopen:2023 - ... - - Now, assuming a combined journal like: - - ; all.journal - include 2021.journal - include 2022.journal - include 2023.journal - - The clopen: tag can exclude all but the first opening transaction. To - show a clean multi-year checking register: - - $ hledger -f all.journal areg checking not:tag:clopen - - And the year values allow more precision. To show 2022's year-end bal- - ance sheet: - - $ hledger -f all.journal bs -e2023 not:tag:clopen=2023 - - codes - List the codes seen in transactions, in the order parsed. - - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often - used to store a cheque number, order number or similar. - - Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be - printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - - 2022/1/1 (123) Supermarket - Food $5.00 - Checking - - 2022/1/2 (124) Post Office - Postage $8.32 - Checking - - 2022/1/3 Supermarket - Food $11.23 - Checking - - 2022/1/4 (126) Post Office - Postage $3.21 - Checking - - $ hledger codes - 123 - 124 - 126 - - $ hledger codes -E - 123 - 124 - - 126 - - commodities - List all commodity/currency symbols used or declared in the journal. - - demo - Play demos of hledger usage in the terminal, if asciinema is installed. - - Run this command with no argument to list the demos. To play a demo, - write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/--speed SPEED option to set your preferred playback speed, - eg -s4 to play at 4x original speed or -s.5 to play at half speed. The - default speed is 2x. - - Other asciinema options can be added following a double dash, eg -- - -i.1 to limit pauses or -- -h to list asciinema's other options. - - During playback, several keys are available: SPACE to pause/unpause, . - to step forward (while paused), CTRL-c quit. - - Examples: - - $ hledger demo # list available demos - $ hledger demo 1 # play the first demo at default speed (2x) - $ hledger demo install -s4 # play the "install" demo at 4x speed - - 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 - 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 - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - help - Show the hledger user manual in the terminal, with info, man, or a - pager. With a TOPIC argument, open it at that topic if possible. - TOPIC can be any heading in the manual, or a heading prefix, case in- - sensitive. Eg: commands, print, forecast, journal, amount, "auto post- - ings". - - This command shows the hledger manual built in to your hledger version. - It can be useful when offline, or when you prefer the terminal to a web - browser, or when the appropriate hledger manual or viewing tools are - not installed on your system. - - By default it chooses the best viewer found in $PATH, trying (in this - order): info, man, $PAGER, less, more. You can force the use of info, - man, or a pager with the -i, -m, or -p flags, If no viewer can be - found, or the command is run non-interactively, it just prints the man- - ual to stdout. - - If using info, note that version 6 or greater is needed for TOPIC - lookup. If you are on mac you will likely have info 4.8, and should - consider installing a newer version, eg with brew install texinfo - (#1770). - - Examples - - $ hledger help --help # show how the help command works - $ hledger help # show the hledger manual with info, man or $PAGER - $ hledger help journal # show the journal topic in the hledger manual - $ hledger help -m journal # show it with man, even if info is installed - - import - Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. - - 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 - import does time-based deduplication, to detect only the new transac- - tions since the last successful import. (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 periodi- - cally importing downloaded data, which may overlap with previous down- - loads. Eg if every week (or every day) you download a bank's last - three months of CSV data, you can safely run hledger import thebank.csv - each time and only new transactions will be imported. - - 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.FILE" file in FILE's directory (after a succesful - import). - - Eg when reading finance/bank.csv, it will look for and update the fi- - nance/.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 cer- - tain date. - - Note deduplication (and updating of state files) can also be done by - print --new, but this is less often used. - - Related: CSV > Working with CSV > Deduplicating, importing. - - Import testing - With --dry-run, the transactions that will be imported are printed to - the terminal, without updating your journal or state files. The output - is valid journal format, like the print command, so you can re-parse - it. Eg, to see any importable transactions which CSV rules have not - categorised: - - $ hledger import --dry bank.csv | hledger -f- -I print unknown - - or (live updating): - - $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' - - Note: when importing from multiple files at once, it's currently possi- - ble for some .latest files to be updated successfully, while the actual - import fails because of a problem in one of the files, leaving them out - of sync (and causing some transactions to be missed). To prevent this, - do a --dry-run first and fix any problems before the real import. - - 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 - (is) - - This command displays an income statement, showing revenues and ex- - penses during one or more periods. Amounts are shown with normal posi- - tive 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 op- - tions The output formats supported are txt, csv, tsv, html, and (exper- - imental) json. - - notes - List the unique notes that appear in transactions. - - This command lists the unique notes that appear in transactions, in al- - phabetic 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 - 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 - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With - --show-reverse, also show additional prices inferred by reversing known - prices. - - Price amounts are always displayed with their full precision, except - for reverse prices which are limited to 8 decimal digits. - - Prices can be filtered by a date:, cur: or amt: query. - - Generally if you run this command with --infer-market-prices --show-re- - verse, it will show the same prices used internally to calculate value - reports. But if in doubt, you can inspect those directly by running - the value report with --debug=2. - - 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). - - 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/regenerate your journal you should take care to also copy - over the directives and inter-transaction comments. - - Eg: - - $ hledger print -f examples/sample.journal date:200806 - 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 - - print explicitness - Normally, whether posting amounts are implicit or explicit is pre- - served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, if a conversion cost is implied - but not written, it will not appear in the output. - - You can use the -x/--explicit flag to force explicit display of all - amounts and costs. This can be useful for troubleshooting or for mak- - ing your journal more readable and robust against data entry errors. - -x is also implied by using any of -B,-V,-X,--value. - - The -x/--explicit flag will cause any postings with a multi-commodity - amount (which can arise when a multi-commodity transaction has an im- - plicit amount) to be split into multiple single-commodity postings, - keeping the output parseable. - - print amount style - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can do that with ledger-mode in - Emacs). - - Amounts will be (mostly) normalised to their commodity display style: - their symbol placement, decimal mark, and digit group marks will be - made consistent. By default, decimal digits are shown as they are - written in the journal. - - With the --round option, print will try increasingly hard to display - decimal digits according to the commodity display styles: - - o --round=none show amounts with original precisions (default) - - o --round=soft add/remove decimal zeros in amounts (except costs) - - o --round=hard round amounts (except costs), possibly hiding signifi- - cant digits - - o --round=all round all amounts and costs - - soft is good for non-lossy cleanup, formatting amounts more consis- - tently where it's safe to do so. - - hard and all can cause print to show invalid unbalanced journal en- - tries; they may be useful eg for stronger cleanup, with manual fixups - when needed. - - print parseability - 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 (though the same can be achieved with expr: queries - now): - - # 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 Value reporting affects posting amounts but not balance assertion or - balance 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. - - print, other features - With -B/--cost, amounts with costs are shown converted to cost. - - With --new, print shows 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.) - - With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription is most similar to DESC. DESC should contain at least two - characters. If there is no similar-enough match, no transaction will - be shown and the program exit code will be non-zero. - - print output format - This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount, csv, tsv, json - and sql. - - Experimental: The beancount format tries to produce Beancount-compati- - ble output, as follows: - - o Transaction and postings with unmarked status are converted to - cleared (*) status. - - o Transactions' payee and note are backslash-escaped and double-quote- - escaped and wrapped in double quotes. - - o Transaction tags are copied to Beancount #tag format. - - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency - names. - - o Account name parts are capitalised and unsupported characters are re- - placed with -. If an account name part does not begin with a letter, - or if the first part is not Assets, Liabilities, Equity, Income, or - Expenses, an error is raised. (Use --alias options to bring your ac- - counts into compliance.) - - o An open directive is generated for each account used, on the earliest - transaction date. - - Some limitations: - - o Balance assertions are removed. - - o Balance assignments become missing amounts. - - o Virtual and balanced virtual postings become regular postings. - - o Directives are not converted. - - 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.) - - 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 ac- - count 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 to- - gether with the related account: - - $ hledger register --related --invert assets:checking - - With a reporting interval, register shows summary postings, one per in- - terval, 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 op- - tion 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 in- - tervals. This ensures that the first and last intervals are full - length and comparable to the others in the report. - - With -m DESC/--match=DESC, register does a fuzzy search for one recent - posting whose description is most similar to DESC. DESC should contain - at least two characters. If there is no similar-enough match, no post- - ing will be shown and the program exit code will be non-zero. - - 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 de- - scription 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 op- - tions The output formats supported are txt, csv, tsv, and (experimen- - tal) json. - - 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 in- - cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- - ity. - - 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 - 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 ac- - count 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, also known as money-weighted rate of return) and time-weighted - rate of return (TWR) for your investments for the time period re- - quested. IRR is always annualized due to the way it is computed, but - TWR is reported both as a rate over the chosen reporting period and as - an annual rate. - - 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 be- - comes 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 as- - sets, 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 re- - turn. - - 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, and the - time between them. Investment at a particular fixed interest rate is - going to give you more interest than the same amount invested at the - same interest rate, but made later in time. 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, - so your IRR will be smaller. And if you are adding to your investment, - you will receive bigger absolute gains, which will be a bigger percent- - age of your initial investment, so your IRR will be larger. - - 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 ac- - count for the effect of your in-flows and out-flows, but unlike IRR it - will try to compute the true rate of return of the underlying asset, - compensating for the effect that deposits and withdrawas have on the - apparent rate of growth of your investment. - - 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, and make TWR less sensitive than IRR to the effects of - cash in-flows and out-flows. - - References: - - o Explanation of rate of return - - o Explanation of IRR - - o Explanation of TWR - - o IRR vs TWR - - o Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - stats - Show journal and performance statistics. - - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report - for each report period. - - At the end, it shows (in the terminal) the overall run time and number - of transactions processed per second. Note these are approximate and - will vary based on machine, current load, data size, hledger version, - haskell lib versions, GHC version.. but they may be of interest. The - stats command's run time is similar to that of a single-column balance - report. - - Example: - - $ hledger stats -f examples/1000x1000x10.journal - Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal - Included files : - Transactions span : 2000-01-01 to 2002-09-27 (1000 days) - Last transaction : 2002-09-26 (6995 days ago) - Transactions : 1000 (1.0 per day) - Transactions last 30 days: 0 (0.0 per day) - Transactions last 7 days : 0 (0.0 per day) - Payees/descriptions : 1000 - Accounts : 1000 (depth 10) - Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) - Market prices : 1000 (A) - - Run time : 0.12 s - Throughput : 8342 txns/s - - This command supports the -o/--output-file option (but not -O/--output- - format selection). - - 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 - 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). - -PART 5: COMMON TASKS - Here are some quick examples of how to do some basic tasks with - hledger. - - Getting help - Here's how to list commands and view options and command docs: - - $ hledger # show available commands - $ hledger --help # show common options - $ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version's manual in several formats by - using the help command. Eg: - - $ hledger help # show the hledger manual with info, man or $PAGER (best available) - $ hledger help journal # show the journal topic in the hledger manual - $ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit - https://hledger.org. Chat and mail list support and discussion - archives can be found at https://hledger.org/support. - - Constructing command lines - hledger has a flexible command line interface. We strive to keep it - simple and ergonomic, but if you run into one of the sharp edges de- - scribed in OPTIONS, here are some tips that might help: - - o command-specific options must go after the command (it's fine to put - common options there too: 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 line 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 - (see below). 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 2023.journal - $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile - $ source ~/.profile - $ hledger stats - Main file : /Users/simon/finance/2023.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 LEDGER_FILE - How to set LEDGER_FILE permanently depends on your setup: - - On unix and mac, running these commands in the terminal will work for - many people; adapt as needed: - - $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile - $ source ~/.profile - - When correctly configured, in a new terminal window env | grep - LEDGER_FILE will show your file, and so will hledger files. - - On mac, this additional step might be helpful for GUI applications - (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- - ment.plist like - - { - "LEDGER_FILE" : "~/finance/2023.journal" - } - - and then run killall Dock in a terminal window (or restart the ma- - chine). - - On Windows, see https://www.java.com/en/download/help/path.html, or try - running these commands in a powershell window (let us know if it per- - sists across a reboot, and if you need to be an Administrator): - - > CD - > MKDIR finance - > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - 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 re- - cent starting date, like today or the start of the week. You can al- - ways 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: - - 2023-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/2023.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 [2023-02-07]: 2023-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): . - 2023-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 [2023-01-01]: . - - If you're using version control, this could be a good time to commit - the journal. Eg: - - $ git commit -m 'initial balances' 2023.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: - - 2023/1/10 * gift received - assets:cash $20 - income:gifts - - 2023.1.12 * farmers market - expenses:food $13 - assets:cash - - 2023-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 al- - ready-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: - - 2023-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 re- - ported by hledger reg checking -C. This will be easier if you gen- - erally record transaction dates quite similar to your bank's clear- - ing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a live-up- - dating register while you edit the journal: hledger-ui --watch --regis- - ter 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 2023-01-15 and paycheck - - If you're using version control, this can be another good time to com- - mit: - - $ git commit -m 'txns' 2023.journal - - Reporting - Here are some basic reports. - - Show all transactions: - - $ hledger print - 2023-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - - 2023-01-10 * gift received - assets:cash $20 - income:gifts - - 2023-01-12 * farmers market - expenses:food $13 - assets:cash - - 2023-01-15 * paycheck - income:salary - assets:bank:checking $1000 - - 2023-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - - $ hledger accounts --tree - assets - bank - checking - savings - cash - equity - opening/closing balances - expenses - food - misc - income - gifts - salary - liabilities - creditcard - - Show all account totals: - - $ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard - -------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to - depth 2: - - $ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard - -------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple - balance sheet: - - $ hledger bs -2 - Balance Sheet 2023-01-16 - - || 2023-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 2023-01-01-2023-01-16 - - || 2023-01-01-2023-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 - 2023-01-01 opening balances assets:cash $100 $100 - 2023-01-10 gift received assets:cash $20 $120 - 2023-01-12 farmers market assets:cash $-13 $107 - 2023-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - - $ hledger activity -W - 2019-12-30 ***** - 2023-01-06 **** - 2023-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. - -BUGS - We welcome bug reports in the hledger issue tracker (shortcut: - http://bugs.hledger.org), or on the #hledger chat or hledger mail list - (https://hledger.org/support). - - Some known issues and limitations: - - The need to precede add-on command options with -- when invoked from - hledger is awkward. (See Command options, Constructing command lines.) - - A UTF-8-aware system locale must be configured to work with non-ascii - data. (See Unicode characters, Troubleshooting.) - - On Microsoft Windows, depending whether you are running in a CMD window - or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii - characters and colours may not be supported, and the tab key may not be - supported by hledger add. (Running in a WSL window should resolve - these.) - - When processing large data files, hledger uses more memory than Ledger. - - Troubleshooting - Here are some common issues you might encounter when you run hledger, - and how to resolve them (and remember also you can usually get quick - Support): - - PATH issues: I get an error like "No command 'hledger' found" - Depending how you installed hledger, the executables may not be in your - shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- - cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one - of these directories to your shell's PATH, and/or open a new terminal - window. - - LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using - it - o LEDGER_FILE should be a real environment variable, not just a shell - variable. Eg on unix, the command env | grep LEDGER_FILE should show - it. You may need to use export (see https://stackover- - flow.com/a/7411509). - - o You may need to force your shell to see the new configuration. A - simple way is to close your terminal window and open a new one. - - LANG issues: I get errors like "Illegal byte sequence" or "Invalid or - incomplete multibyte or wide character" or "commitAndReleaseBuffer: in- - valid argument (invalid character)" - Programs compiled with GHC (hledger, haskell build tools, etc.) need - the system locale to be UTF-8-aware, or they will fail when they en- - counter non-ascii characters. To fix it, set the LANG environment - variable to a locale which supports UTF-8 and which is installed on - your system. - - On unix, locale -a lists the installed locales. Look for one which - mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8, - fr_FR.utf8. If necessary, use your system package manager to install - one. Then select it by setting the LANG environment variable. Note, - exact spelling and capitalisation of the locale name may be important: - Here's one common way to configure this permanently for your shell: - - $ echo "export LANG=en_US.utf8" >>~/.profile - # close and re-open terminal window - - If you are using Nix (not NixOS) for GHC and Hledger, you might need to - set the LOCALE_ARCHIVE variable: - - $ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile - # close and re-open terminal window - - COMPATIBILITY ISSUES: hledger gives an error with my Ledger file - Not all of Ledger's journal file syntax or feature set is supported. - See hledger and Ledger for full details. - - - -AUTHORS - Simon Michael and contributors. - See http://hledger.org/CREDITS.html - - -COPYRIGHT - Copyright 2007-2023 Simon Michael and contributors. - - -LICENSE - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), ledger(1) - -hledger-1.32 December 2023 HLEDGER(1) + This manual is for hledger's command line interface, version 1.32.1. + It also describes the common options, file formats and concepts used by + all hledger programs. It might accidentally teach you some bookkeep- + ing/accounting as well! You don't need to know everything in here to + use hledger productively, but when you have a question about function- + ality, this doc should answer it. It is detailed, so do skip ahead or + skim when needed. You can read it on hledger.org, or as an info manual + or man page on your system. You can also get it from hledger itself + with + hledger --man, hledger --info or hledger help [TOPIC]. + + The main function of the hledger CLI is to read plain text files de- + scribing financial transactions, crunch the numbers, and print a useful + report on the terminal (or save it as HTML, CSV, JSON or SQL). Many + reports are available, as subcommands. hledger will also detect other + hledger-* executables as extra subcommands. + + hledger usually reads from (and appends to) a journal file specified by + the LEDGER_FILE environment variable (defaulting to + $HOME/.hledger.journal); or you can specify files with -f options. It + can also read timeclock files, timedot files, or any CSV/SSV/TSV file + with a date field. + + Here is a small journal file describing one transaction: + + 2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more + accounts: bank accounts, your wallet, revenue/expense categories, peo- + ple, etc. You can choose any account names you wish, using : to indi- + cate subaccounts. There must be at least two spaces between account + name and amount. Positive amounts are inflow to that account (debit), + negatives are outflow from it (credit). (Some reports show revenue, + liability and equity account balances as negative numbers as a result; + this is normal.) + + hledger's add command can help you add transactions, or you can install + other data entry UIs like hledger-web or hledger-iadd. For more exten- + sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM + + vim-ledger, or VS Code + hledger-vscode are some good choices (see + https://hledger.org/editors.html). + + To get started, run hledger add and follow the prompts, or save some + entries like the above in $HOME/.hledger.journal, then try commands + like: + hledger print -x + hledger aregister assets + hledger balance + hledger balancesheet + hledger incomestatement. + Run hledger to list the commands. See also the "Starting a journal + file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +PART 1: USER INTERFACE +Input + hledger reads one or more data files, each time you run it. You can + specify a file with -f, like so + + $ hledger -f FILE print + + Files are most often in hledger's journal format, with the .journal + file extension (.hledger or .j also work); these files describe trans- + actions, like an accounting general journal. + + When no file is specified, hledger looks for .hledger.journal in your + home directory. + + But most people prefer to keep financial files in a dedicated folder, + perhaps with version control. Also, starting a new journal file each + year is common (it's not required, but helps keep things fast and or- + ganised). So we usually configure a different journal file, by setting + the LEDGER_FILE environment variable, to something like ~/fi- + nance/2023.journal. For more about how to do that on your system, see + Common tasks > Setting LEDGER_FILE. + + 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 .journal .j .hledger .ledger + Ledger journals, for transac- + tions + timeclock timeclock files, for precise .timeclock + time logging + timedot timedot files, for approximate .timedot + time logging + csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules + rated values, for data import .ssv.rules .tsv.rules + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a + recognised file extension, so as to either read successfully or to show + relevant error messages. + + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg, to read a .dat file as csv format: + + $ hledger -f csv:/some/csv-file.dat stats + + Standard input + The file name - means standard input: + + $ cat FILE | hledger -f- print + + If reading non-journal data in this way, you'll need to add a file for- + mat prefix, like: + + $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- + + Multiple files + You can specify multiple -f options, to read multiple files as one big + journal. When doing this, note that certain features (described below) + will be affected: + + o Balance assertions will not see the effect of transactions in previ- + ous files. (Usually this doesn't matter as each file will set the + corresponding opening balances.) + + o Some directives will not affect previous or subsequent files. + + If needed, you can work around these by using a single parent file + which includes the others, or concatenating the files into one, 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. + +Commands + hledger provides various subcommands for getting things done. Most of + these commands do not change the journal file; they just read it and + output a report. A few commands assist with adding data and file man- + agement. + + To show the commands list, run hledger with no arguments. The commands + are described in detail in PART 4: COMMANDS, below. + + To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], + + o CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + o CMDOPTS are command-specific options, if any. Command-specific op- + tions must be written after the command name. Eg: hledger print -x. + + o CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit the + data in some way. Eg: hledger reg assets:checking. + + To list a command's options, arguments, and documentation in the termi- + nal, run hledger CMD -h. Eg: hledger bal -h. + + Add-on commands + In addition to the built-in commands, you can install add-on commands: + programs or scripts named "hledger-SOMETHING", which will also appear + in hledger's commands list. If you used the hledger-install script, + you will have several add-ons installed already. Some more can be + found in hledger's bin/ directory, documented at + https://hledger.org/scripts.html. + + More precisely, add-on commands are programs or scripts in your shell's + PATH, whose name starts with "hledger-" and ends with no extension or a + recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", + ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix + and mac) which has executable permission for the current user. + + You can run add-on commands using hledger, much like built-in commands: + hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double + hyphen argument, required before add-on-specific options. Eg: hledger + ui -- --watch or hledger web -- --serve. If this causes difficulty, + you can always run the add-on directly, without using hledger: hledger- + ui --watch or hledger-web --serve. + +Options + Run hledger -h to see general command line help, and general options + which are common to most hledger commands. These options can be writ- + ten anywhere on the command line. They can be grouped into help, in- + put, and reporting options: + + 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 de- + clared) + + 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 ef- + fects) + + --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-equity + infer conversion equity postings from costs + + --infer-costs + infer costs from conversion equity postings + + --infer-market-prices + use costs as additional market prices, as if they were P direc- + tives + + --forecast + generate transactions from periodic rules, between the latest + recorded txn and 6 months from today, or during the specified + PERIOD (= is required). Auto posting rules will be applied to + these transactions as well. Also, in hledger-ui make future- + dated transactions visible. + + --auto generate extra postings by applying auto posting rules to all + txns (not just forecast txns) + + --verbose-tags + add visible tags indicating transactions or postings which have + been generated/modified + + --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 line tips + Here are some details useful to know about for hledger command lines + (and elsewhere). Feel free to skip this section until you need it. + + Option repetition + If options are repeated in a command line, hledger will generally use + the last (right-most) occurence. + + 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 ac- + count 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 be- + low), 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:\\$ + + 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 de- + code 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 + A regular expression (regexp) is a small piece of text where certain + characters (like ., ^, $, +, *, (), |, [], \) have special meanings, + forming a tiny language for matching text precisely - very useful in + hledger and elsewhere. To learn all about them, visit regular-expres- + sions.info. + + hledger supports regexps whenever you are entering a pattern to match + something, eg in query arguments, account aliases, CSV if rules, + hledger-web's search form, hledger-ui's / search, etc. You may need to + wrap them in quotes, especially at the command line (see Special char- + acters above). Here are some examples: + + Account name queries (quoted for command line use): + + Regular expression: Matches: + ------------------- ------------------------------------------------------------ + bank assets:bank, assets:bank:savings, expenses:art:banksy, ... + :bank assets:bank:savings, expenses:art:banksy + :bank: assets:bank:savings + '^bank' none of those ( ^ matches beginning of text ) + 'bank$' assets:bank ( $ matches end of text ) + 'big \$ bank' big $ bank ( \ disables following character's special meaning ) + '\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) + '(sav|check)ing' saving or checking ( (|) matches either alternative ) + 'saving|checking' saving or checking ( outer parentheses are not needed ) + 'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) + 'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) + 'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) + 'b.nk' bank, bonk, b nk, ... ( . matches any character ) + + Some other queries: + + desc:'amazon|amzn|audible' Amazon transactions + cur:EUR amounts with commodity symbol containing EUR + cur:'\$' amounts with commodity symbol containing $ + cur:'^\$$' only $ amounts, not eg AU$ or CA$ + cur:....? amounts with 4-or-more-character symbols + tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 + + Account name aliases: accept . instead of : as account separator: + + alias /\./=: replaces all periods in account names with colons + + Show multiple top-level accounts combined as one: + + --alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) + + Show accounts with the second-level part removed: + + --alias '/^([^:]+):[^:]+/ = \1' + match a top-level account and a second-level account + and replace those with just the top-level account + ( \1 in the replacement text means "whatever was matched + by the first parenthesised part of the regexp" + + CSV rules: match CSV records containing dining-related MCC codes: + + if \?MCC581[124] + + Match CSV records with a specific amount around the end/start of month: + + if %amount \b3\.99 + & %date (29|30|31|01|02|03)$ + + hledger's regular expressions + 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. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the re- + placement string to reference capturing groups in the search regexp. + Otherwise, if you write \1, it will match the digit 1. + + 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. + + Argument files + You can save a set of command line options and arguments in a file, and + then reuse them by writing @FILENAME as a command line argument. Eg: + hledger bal @foo.args. + + Inside the argument file, each line should contain just one option or + argument. Don't use spaces except inside quotes (or you'll see a con- + fusing error); write = (or nothing) between a flag and its argument. + For the special characters mentioned above, use one less level of quot- + ing than you would at the command prompt. + +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) + + Output format + Some commands offer other kinds of output, not just text on the termi- + nal. Here are those commands and the formats currently supported: + + - txt csv/tsv html json sql + -------------------------------------------------------------------------------------- + aregister Y Y Y Y + balance Y 1 Y 1 Y 1,2 Y + balancesheet Y 1 Y 1 Y 1 Y + balancesheete- Y 1 Y 1 Y 1 Y + quity + 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 + + 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 + + Some notes about the various output formats: + + 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 This is not yet much used; real-world feedback is welcome. + + o Our JSON is rather large and verbose, since it is a faithful repre- + sentation 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 This is not yet much used; real-world feedback is welcome. + + o SQL output is expected to work at least with SQLite, MySQL and Post- + gres. + + o For SQLite, it will be more useful if you modify the generated id + field to be a PRIMARY KEY. Eg: + + $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... + + 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 + When displaying amounts, hledger infers a standard display style for + each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a -c/--commodity-style option (ex- + cept for cost amounts and amounts displayed by the print command, which + are always displayed with all decimal digits). For example, the fol- + lowing will force dollar amounts to be displayed as shown: + + $ hledger print -c '$1.000,0' + + This option can repeated to set the display style for multiple commodi- + ties/currencies. Its argument is as described in the commodity direc- + tive. + + Colour + In terminal output, some commands can produce colour when the terminal + supports it: + + o if the --color/--colour option is given a value of yes or always (or + no or never), colour will (or will not) be used; + + o otherwise, if the NO_COLOR environment variable is set, colour will + not be used; + + o otherwise, colour will be used if the output (terminal or file) sup- + ports it. + + Box-drawing + In terminal output, you can enable unicode box-drawing characters to + render prettier tables: + + o if the --pretty option is given a value of yes or always (or no or + never), unicode characters will (or will not) be used; + + o otherwise, unicode characters will not be used. + + Paging + When showing long output in the terminal, hledger will try to use the + pager specified by the PAGER environment variable, or less, or more. + (A pager is a helper program that shows one page at a time rather than + scrolling everything off screen). Currently it does this only for help + output, not for reports; specifically, + + o when listing commands, with hledger + + o when showing help with hledger [CMD] --help, + + o when viewing manuals with hledger help or hledger --man. + + Note the pager is expected to handle ANSI codes, which hledger uses eg + for bold emphasis. For the common pager less (and its more compatibil- + ity mode), we add R to the LESS and MORE environment variables to make + this work. If you use a different pager, you might need to configure + it similarly, to avoid seeing junk on screen (let us know). Otherwise, + you can set the NO_COLOR environment variable to 1 to disable all ANSI + output (see Colour). + + Debug output + We intend hledger to be relatively easy to troubleshoot, introspect and + develop. You can add --debug[=N] to any hledger command line to see + additional debug output. N ranges from 1 (least output, the default) + to 9 (maximum output). Typically you would start with 1 and increase + until you are seeing enough. Debug output goes to stderr, and is not + affected by -o/--output-file (unless you redirect stderr to stdout, eg: + 2>&1). It will be interleaved with normal output, which can help re- + veal when parts of the code are evaluated. To capture debug output in + a log file instead, you can usually redirect stderr, eg: + + hledger bal --debug=3 2>hledger.log + +Environment + These environment variables affect hledger: + + COLUMNS This is normally set by your terminal; some hledger commands + (register) will format their output to this width. If not set, they + will try to use the available terminal width. + + LEDGER_FILE The main journal file to use when not specified with + -f/--file. Default: $HOME/.hledger.journal. + + NO_COLOR If this environment variable is set (with any value), hledger + will not use ANSI color codes in terminal output, unless overridden by + an explicit --color/--colour option. + +PART 2: DATA FORMATS +Journal + hledger's default file format, representing a General Journal. Here's + a cheatsheet/mini-tutorial, or you can skip ahead to About journal for- + mat. + + Journal cheatsheet + # Here is the main syntax of hledger's journal format + # (omitting extra Ledger compatibility syntax). + # hledger journals contain comments, directives, and transactions, in any order: + + ############################################################################### + # 1. Comment lines are for notes or temporarily disabling things. + # They begin with #, ;, or a line containing the word "comment". + + # hash comment line + ; semicolon comment line + comment + These lines + are commented. + end comment + + # Some but not all hledger entries can have same-line comments attached to them, + # from ; (semicolon) to end of line. + + ############################################################################### + # 2. Directives modify parsing or reports in some way. + # They begin with a word or letter (or symbol). + + account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;. + account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX) + alias chkg = assets:checking + commodity $0.00 + decimal-mark . + include /dev/null + payee Whole Foods + P 2022-01-01 AAAA $1.40 + ~ monthly budget goals ; <- 2+ spaces between period expression and description + expenses:food $400 + expenses:home $1000 + budgeted + + ############################################################################### + # 3. Transactions are what it's all about; they are dated events, + # usually describing movements of money. + # They begin with a date. + + # DATE DESCRIPTION ; This is a transaction comment. + # ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment. + # ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented. + # ; ^^ At least 2 spaces between account and amount. + # ... ; Any number of postings is allowed. The amounts must balance (sum to 0). + + 2022-01-01 opening balances are declared this way + assets:checking $1000 ; Account names can be anything. lower case is easy to type. + assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common. + assets:cash:wallet $100 ; : indicates subaccounts. + liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative. + equity ; One amount can be left blank; $-1900 is inferred here. + + 2022-04-15 * (#12345) pay taxes + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a transaction code (text in parentheses) after the date/status. + ; Amounts' sign represents direction of flow, or credit/debit: + assets:checking $-500 ; minus means removed from this account (credit) + expenses:tax:us:2021 $500 ; plus means added to this account (debit) + ; revenue/expense categories are also "accounts" + + 2022-01-01 ; The description is optional. + ; Any currency/commodity symbols are allowed, on either side. + assets:cash:wallet GBP -10 + expenses:clothing GBP 10 + assets:gringotts -10 gold + assets:pouch 10 gold + revenues:gifts -2 "Liquorice Wands" ; Complex symbols + assets:bag 2 "Liquorice Wands" ; must be double-quoted. + + 2022-01-01 Cost in another commodity can be noted with @ or @@ + assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments 3.0 AAAA @@ $4 ; @@ means total cost + assets:checking $-7.00 + + 2022-01-02 assert balances + ; Balances can be asserted for extra error checking, in any transaction. + assets:investments 0 AAAA = 5.0 AAAA + assets:pouch 0 gold = 10 gold + assets:savings $0 = $1000 + + 1999-12-31 Ordering transactions by date is recommended but not required. + ; Postings are not required. + + 2022.01.01 These date + 2022/1/1 formats are + 12/31 also allowed (but consistent YYYY-MM-DD is recommended). + + About journal format + hledger's usual data source is a plain text file containing journal en- + tries in hledger journal format. This file represents a standard ac- + counting 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 compatible with most of Ledger's journal + format, but not all of it. The differences and interoperation tips are + described at hledger and Ledger. With some care, and by avoiding in- + compatible features, you can keep your hledger journal readable by + Ledger and vice versa. This can useful eg for comparing the behaviour + of one app against the other. + + 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). + + A hledger journal file can contain three kinds of thing: file comments, + transactions, and/or directives (counting periodic transaction rules + and auto posting rules as directives). + + Comments + Lines in the journal will be ignored if they begin with a hash (#) or a + semicolon (;). (See also Other syntax.) hledger will also ignore re- + gions beginning with a comment line and ending with an end comment line + (or file end). Here's a suggestion for choosing between them: + + o # for top-level notes + + o ; for commenting out things temporarily + + o comment for quickly commenting large regions (remember it's there, or + you might get confused) + + Eg: + + # a comment line + ; another commentline + comment + A multi-line comment block, + continuing until "end comment" directive + or the end of the current file. + end comment + + Some hledger entries can have same-line comments attached to them, from + ; (semicolon) to end of line. See Transaction comments, Posting com- + ments, and Account comments below. + + 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 op- + tional 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 Y directive, or the cur- + rent 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.) + + 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 re- + ports, and the deduction from checking should be reported on 6/1 for + easy bank reconciliation: + + 2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + + $ hledger -f t.j register food + 2015-05-30 expenses:food $10 $10 + + $ hledger -f t.j register checking + 2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. + The date: tag must have a valid simple date value if it is present, eg + a date: tag with no value is not allowed. + + Status + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction de- + scription or posting account name, separated from it by a space, indi- + cating 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 un- + marked 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 un- + cashed 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 (af- + ter the first |). This may be worthwhile if you need to do more pre- + cise querying and pivoting by payee or by note. + + Transaction comments + Text following ;, after a transaction description, and/or on indented + lines immediately below it, form comments for that transaction. They + are reproduced by print but otherwise ignored, except they may contain + tags, which are not ignored. + + 2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + 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 + spaces. But if you accidentally leave only one space (or tab) before + the amount, the amount will be considered part of the account name. + + Account names + Accounts are the main way of categorising things in hledger. As in + Double Entry Bookkeeping, they can represent real world accounts (such + as a bank account), or more abstract categories such as "money borrowed + from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the + traditional accounting categories, which in english are assets, liabil- + ities, equity, revenues, expenses. (You might see these referred to as + A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts + into more detailed subaccounts, by writing a full colon between account + name parts. For example, from the account names assets:bank:checking + and expenses:food, hledger will infer this hierarchy of five accounts: + + assets + assets:bank + assets:bank:checking + expenses + expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + + assets + bank + checking + expenses + food + + hledger reports can summarise the account tree to any depth, so you can + go as deep as you like with subcategories, but keeping your account + names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, num- + bers, symbols, or single spaces. Note, when an account name and an + amount are written on the same line, they must be separated by two or + more spaces (or tabs). + + Parentheses or brackets enclosing the full account name indicate vir- + tual postings, described below. Parentheses or brackets internal to + the account name have no special meaning. + + Account names can be altered temporarily or permanently by account + aliases. + + Amounts + After the account name, there is usually an amount. (Important: be- + tween 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,23 + + 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 + + hledger is not biased towards period or comma decimal marks, so a num- + ber containing just one period or comma, like 1,000 or 1.000, is am- + biguous. In such cases hledger assumes it is a decimal mark, parsing + both of these as 1. + + To disambiguate these and ensure accurate number parsing, especially if + you use digit group marks, we recommend declaring the decimal mark. + You can declare it for each file with decimal-mark directives, or for + each commodity with commodity directives (described 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, but here's a quick example: + + # the decimal mark character used by all amounts in this file (all commodities) + decimal-mark . + + # display styles for the $, EUR, INR and no-symbol commodities: + commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.00 + commodity 1 000 000.9455 + + Commodity display style + For the amounts in each commodity, hledger chooses a consistent display + style (symbol placement, decimal mark and digit group marks, number of + decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a D directive declaring a default commodity, that + commodity symbol and amount format is applied to all no-symbol amounts + in the journal. + + Then each commodity's display style is determined from its commodity + directive. We recommend always declaring commodities with commodity + directives, since they help ensure consistent display styles and preci- + sions, and bring other benefits such as error checking for commodity + symbols. + + But if a commodity directive is not present, hledger infers a commod- + ity's display styles from its amounts as they are written in the jour- + nal (excluding cost amounts and amounts in periodic transaction rules + or auto posting rules). It uses + + o the symbol placement and decimal mark of the first amount seen + + o the digit group marks of the first amount with digit group marks + + o and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a de- + fault style, like $1000.00 (symbol on the left with no space, period as + decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the -c/--commodity-style + command line option. + + Rounding + Amounts are stored internally as decimal numbers with up to 255 decimal + places. They are displayed with their original journal precisions by + print and print-like reports, and rounded to their display precision + (the number of decimal digits specified by the commodity display style) + by other reports. When rounding, hledger uses banker's rounding (it + rounds to the nearest even digit). So eg 0.5 displayed with zero deci- + mal digits appears as "0". + + Costs + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + tion, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, + discussions, or code; that term was directionally neutral and reminded + that it is a price specific to a transaction, but we now just call it + "cost", with the understanding that the transaction could be a purchase + or a sale.) + + Costs are usually written explicitly with @ or @@, but can also be in- + ferred automatically for simple multi-commodity transactions. Note, if + costs are inferred, the order of postings is significant; the first + posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign + currency in hledger, using the cost notation either explicitly or im- + plicitly: + + 1. Write the price per unit, as @ UNITPRICE after the amount: + + 2009/1/1 + assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as @@ TOTALPRICE after the amount: + + 2009/1/1 + assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction. Note the + effect of posting order: the price is added to first posting, making + it 100 @@ $135, as in example 2: + + 2009/1/1 + assets:euros 100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the -B/--cost + flag; this is discussed more in the Cost reporting section. + + Note that the cost normally should be a positive amount, though it's + not required to be. This can be a little confusing, see discussion at + --infer-market-prices: market prices from transactions. + + Other cost/lot notations + A slight digression for Ledger and Beancount users. Ledger has a num- + ber of cost/lot-related notations: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a conversion rate, as in hledger + + o when buying, also creates a lot than can be selected at selling + time + + o (@) UNITCOST and (@@) TOTALCOST (virtual cost) + + o like the above, but also means "this cost was exceptional, don't + use it when inferring market prices". + + Currently, hledger treats the above like @ and @@; the parentheses are + ignored. + + o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) + + o when buying, means "this cost is also the fixed price, don't let it + fluctuate in value reports" + + o {UNITCOST} and {{TOTALCOST}} (lot price) + + o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- + ates a lot + + o when selling, combined with @ ..., specifies an investment lot by + its cost basis; does not check if that lot is present + + o and related: [YYYY/MM/DD] (lot date) + + o when buying, attaches this acquisition date to the lot + + o when selling, selects a lot by its acquisition date + + o (SOME TEXT) (lot note) + + o when buying, attaches this note to the lot + + o when selling, selects a lot by its note + + Currently, hledger accepts any or all of the above in any order after + the posting amount, but ignores them. (This can break transaction bal- + ancing.) + + For Beancount users, the notation and behaviour is different: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a cost without creating a lot, as in hledger + + o when buying (augmenting) or selling (reducing) a lot, combined with + {...}: documents the cost/selling price (not used for transaction + balancing) + + o {UNITCOST} and {{TOTALCOST}} + + o when buying (augmenting), expresses the cost for transaction bal- + ancing, and also creates a lot with this cost basis attached + + o when selling (reducing), + + o selects a lot by its cost basis + + o raises an error if that lot is not present or can not be selected + unambiguously (depending on booking method configured) + + o expresses the selling price for transaction balancing + + Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but + ignores it. + + o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- + COST, YYYY-MM-DD, "LABEL"} etc. + + Currently, hledger rejects these. + + 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, described 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 or- + der 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 in- + clude, 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 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 + + Assertions and prices + Balance assertions ignore costs, and should normally be written without + one: + + 2019/1/1 + (a) $1 @ 1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance 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. + + Posting comments + Text following ;, at the end of a posting line, and/or on indented + lines immediately below it, form comments for that posting. They are + reproduced by print but otherwise ignored, except they may contain + tags, which are not ignored. + + 2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + Tags + Tags are a way to add extra labels or labelled data to transactions, + postings, or accounts, which you can then search or pivot on. + + They are written as a word (optionally hyphenated) immediately followed + by a full colon, in a transaction or posting or account directive's + comment. (This is an exception to the usual rule that things in com- + ments are ignored.) Eg, here four different tags are recorded: one on + the checking account, two on the transaction, and one on the expenses + posting: + + account assets:checking ; accounttag: + + 2017/1/16 bought groceries ; transactiontag-1: + ; transactiontag-2: + assets:checking $-1 + expenses:food $1 ; postingtag: + + Postings also inherit tags from their transaction and their account. + And transactions also acquire tags from their postings (and postings' + accounts). So in the example above, the expenses posting effectively + has all four tags (by inheriting from account and transaction), and the + transaction also has all four tags (by acquiring from the expenses + posting). + + You can list tag names with hledger tags [NAMEREGEX], or match by tag + name with a tag:NAMEREGEX query. + + Tag values + Tags can have a value, which is any text after the colon up until a + comma or end of line (with surrounding whitespace removed). Note this + means that hledger tag values can not contain commas. Eg in the fol- + lowing posting, the three tags' values are "value 1", "value 2", and "" + (empty) respectively: + + expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz + + Note that tags can be repeated, and are additive rather than overrid- + ing: when the same tag name is seen again with a new value, the new + name:value pair is added to the tags. (It is not possible to override + a tag's value or remove a tag.) + + You can list a tag's values with hledger tags TAGNAME --values, or + match by tag value with a tag:NAMEREGEX=VALUEREGEX query. + + Directives + Besides transactions, there is something else you can put in a journal + file: directives. These are declarations, beginning with a keyword, + that modify hledger's behaviour. Some directives can have more spe- + cific subdirectives, indented below them. hledger's directives are + similar to Ledger's in many cases, but there are also many differences. + Directives are not required, but can be useful. Here are the main di- + rectives: + + purpose directive + -------------------------------------------------------------------------- + READING DATA: + Rewrite account names alias + Comment out sections of the file comment + Declare file's decimal mark, to help decimal-mark + parse amounts accurately + Include other data files include + GENERATING DATA: + Generate recurring transactions or bud- ~ + get goals + Generate extra postings on existing = + transactions + CHECKING FOR ERRORS: + Define valid entities to provide more account, commodity, payee, tag + error checking + REPORTING: + Declare accounts' type and display order account + Declare commodity display styles commodity + Declare market prices P + + Directives and multiple files + Directives vary in their scope, ie which journal entries and which in- + put files they affect. Most often, a directive will affect the follow- + ing entries and included files if any, until the end of the current + file - and no further. You might find this inconvenient! For example, + alias directives do not affect parent or sibling files. But there are + usually workarounds; for example, put alias directives in your top-most + file, before including other files. + + The restriction, though it may be annoying at first, is in a good + cause; it allows reports to be stable and deterministic, independent of + the order of input. Without it, reports could show different numbers + depending on the order of -f options, or the positions of include di- + rectives in your files. + + Directive effects + Here are all hledger's directives, with their effects and scope sum- + marised - nine main directives, plus four others which we consider non- + essential: + + di- what it does ends + rec- at + tive file + end? + -------------------------------------------------------------------------------------- + ac- Declares an account, for checking all entries in all files; and N + count its display order and type. Subdirectives: any text, ignored. + alias Rewrites account names, in following entries until end of cur- Y + rent file or end aliases. Command line equivalent: --alias + com- Ignores part of the journal file, until end of current file or Y + ment end comment. + com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N + mod- all amounts in all files 2. the decimal mark for parsing + ity amounts of this commodity, in the following entries until end of + current file (if there is no decimal-mark directive) 3. and the + display style for amounts of this commodity 4. which is also + the precision to use for balanced-transaction checking in this + commodity. Takes precedence over D. Subdirectives: format + (Ledger-compatible syntax). Command line equivalent: -c/--com- + modity-style + deci- Declares the decimal mark, for parsing amounts of all commodi- Y + mal- ties in following entries until next decimal-mark or end of cur- + mark rent file. Included files can override. Takes precedence over + commodity and D. + in- Includes entries and directives from another file, as if they N + clude were written inline. Command line alternative: multiple + -f/--file + payee Declares a payee name, for checking all entries in all files. N + P Declares the market price of a commodity on some date, for value N + reports. + ~ Declares a periodic transaction rule that generates future N + (tilde) transactions with --forecast and budget goals with balance + --budget. + Other + syntax: + apply Prepends a common parent account to all account names, in fol- Y + account lowing entries until end of current file or end apply account. + D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no commodity directive for this commodity: its decimal + mark, balancing precision, and display style, as above. + Y Sets a default year to use for any yearless dates, in following Y + entries until end of current file. + = Declares an auto posting rule that generates extra postings on partly + (equals) matched transactions with --auto, in current, parent, and child + files (but not sibling files, see #1212). + Other Other directives from Ledger's file format are accepted but ig- + Ledger nored. + direc- + tives + + account directive + 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 In strict mode, they restrict which accounts may be posted to by + transactions, which helps detect typos. + + o They control account display order in reports, allowing non-alpha- + betic sorting (eg Revenues to appear above Expenses). + + o They help with account name completion (in hledger add, hledger-web, + hledger-iadd, ledger-mode, etc.) + + o They can store additional account information as comments, or as tags + which can be used to filter or pivot reports. + + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), affecting reports like balancesheet and + incomestatement. + + They are written as the word account followed by a hledger-style ac- + count name, eg: + + account assets:bank:checking + + Note, however, that accounts declared in account directives are not al- + lowed to have surrounding brackets and parentheses, unlike accounts + used in postings. So the following journal will not parse: + + account (assets:bank:checking) + + Account comments + Text following two or more spaces and ; at the end of an account direc- + tive line, and/or following ; on indented lines immediately below it, + form comments for that account. They are ignored except they may con- + tain tags, which are not ignored. + + The two-space requirement for same-line account comments is because ; + is allowed in account names. + + account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + Account subdirectives + Ledger-style indented subdirectives are also accepted, but currently + ignored: + + account assets:bank:checking + format subdirective is ignored + + Account error checking + By default, accounts need not be declared; they come into existence + when a posting references them. This is convenient, but it means + hledger can't warn you when you mis-spell an account name in the jour- + nal. Usually you'll find that error later, as an extra account in bal- + ance 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 de- + clared 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 ac- + count 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 in- + cluded files of all types. + + o It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + Account display order + The order in which account directives are written influences the order + in which accounts appear in reports, hledger-ui, hledger-web etc. By + default accounts appear in alphabetical order, but if you add these ac- + count directives to the journal file: + + account assets + account liabilities + account equity + account revenues + account expenses + + those accounts will be displayed in declaration order: + + $ hledger accounts -1 + assets + liabilities + equity + revenues + expenses + + Any undeclared accounts are displayed last, in alphabetical order. + + Sorting is done at each level of the account tree, within each group of + sibling accounts under the same parent. And currently, this directive: + + account other:zoo + + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: + + o you will sometimes declare parent accounts (eg account other above) + that you don't intend to post to, just to customize their display or- + der + + o sibling accounts stay together (you couldn't display x:y in between + a:b and a:c). + + 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 (de- + scribed below). But generally we recommend you declare types explic- + itly, by adding a type: tag to your top-level account directives. Sub- + accounts 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 Cost re- + porting).) + + 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. + + 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 ac- + count for all of the account types, 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] + + alias directive + You can define account alias rules which rewrite your account names, or + parts of them, before generating reports. This can be useful for: + + 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 re- + place any occurrence of the old account name with the new one. Subac- + counts 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 ex- + pression.) + + Eg: + + alias /REGEX/ = REPLACEMENT + + or: + + $ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by RE- + PLACEMENT. 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. In- + cluding the aliases doesn't work either: + + include a.aliases + + 2023-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 + + 2023-01-01 ; affected by aliases above + foo 1 + bar + + include c.journal ; also affected + + end aliases directive + 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 ef- + fect. + + 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 + + commodity directive + The commodity directive performs several functions: + + 1. It declares which commodity symbols may be used in the journal, en- + abling useful error checking with strict mode or the check command. + (See Commodity error checking below.) + + 2. It declares the precision with which this commodity's amounts should + be compared when checking for balanced transactions. + + 3. It declares how this commodity's amounts should be displayed, eg + their symbol placement, digit group mark if any, digit group sizes, + decimal mark (period or comma), and the number of decimal places. + (See Commodity display style above.) + + 4. It sets which decimal mark (period or comma) to expect when parsing + subsequent amounts in this commodity (if there is no decimal-mark + directive in effect. See Decimal marks, digit group marks above. + For related dev discussion, see #793.) + + Declaring commodities solves several common parsing/display problems, + so we recommend it. Generally you should put commodity directives at + the top of your journal file (because function 4 is position-sensi- + tive). + + Commodity directive syntax + A commodity directive is normally the word commodity followed by a sam- + ple amount (and optionally a comment). Only the amount's symbol and + format is significant. Eg: + + commodity $1000.00 + commodity 1.000,00 EUR + commodity 1 000 000.0000 ; the no-symbol commodity + + Commodities do not have tags (tags in the comment will be ignored). + + A commodity directive's sample amount must always include a period or + comma decimal mark (this rule helps disambiguate decimal marks and + digit group marks). If you don't want to show any decimal digits, + write the decimal mark at the end: + + commodity 1000. AAAA ; show AAAA with no decimals + + Commodity symbols containing spaces, numbers, or punctuation must be + enclosed in double quotes, as usual: + + commodity 1.0000 "AAAA 2023" + + Commodity directives normally include a sample amount, but can declare + only a symbol (ie, just function 1 above): + + commodity $ + commodity INR + commodity "AAAA 2023" + commodity "" ; the no-symbol commodity + + Commodity directives may also be written with an indented format subdi- + rective, as in Ledger. The symbol is repeated and must be the same in + both places. Other subdirectives are currently ignored: + + ; 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 + an unsupported subdirective ; ignored by hledger + + Commodity error checking + In strict mode (-s/--strict) (or when you run hledger check commodi- + ties), hledger will report an error if an undeclared commodity symbol + is used. (With one exception: zero amounts are always allowed to have + no commodity symbol.) It works like account error checking (described + above). + + decimal-mark directive + You can use a decimal-mark directive - usually one per file, at the top + of the file - to declare which character represents a decimal mark when + parsing amounts in this file. It can look like + + decimal-mark . + + or + + decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we + recommend it, especially if the file contains digit group marks (eg + thousands separators). + + include directive + You can pull in the content of additional files by writing an include + directive, like this: + + include FILEPATH + + Only journal files can include, and only journal, timeclock or timedot + files can be included (not CSV files, currently). + + If the file path does not begin with a slash, it is relative to the + current file's folder. + + A tilde means home directory, eg: include ~/main.journal. + + The path may contain glob patterns to match multiple files, eg: include + *.journal. + + There is limited support for recursive wildcards: **/ (the slash is re- + quired) 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 Data formats): include time- + dot:~/notes/2023*.md. + + P directive + The P directive declares a market price, which is a conversion rate be- + tween two commodities on a certain date. This allows value reports to + convert amounts of one commodity to their value in another, on or after + that date. These prices are often obtained from a stock exchange, + cryptocurrency exchange, the or foreign exchange market. + + The format is: + + P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity + being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) + of commodity 2 that one unit of commodity 1 is worth on this date. Ex- + amples: + + # 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 Value reporting. + + payee directive + payee PAYEE NAME + + This directive can be used to declare a limited set of payees which may + appear in transaction descriptions. The "payees" check will report an + error if any transaction refers to a payee that has not been declared. + Eg: + + payee Whole Foods ; a comment + + Payees do not have tags (tags in the comment will be ignored). + + To declare the empty payee name, use "". + + payee "" + + Ledger-style indented subdirectives, if any, are currently ignored. + + tag directive + tag TAGNAME + + This directive can be used to declare a limited set of tag names al- + lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + + tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is + used. It is quite easy to accidentally create a tag through normal use + of colons in comments(#comments]; if you want to prevent this, you can + declare and check your tags . + + Periodic transactions + The ~ directive declares recurring transactions. Such directives allow + hledger to generate temporary future transactions (visible in reports, + not in the journal file) to help with forecasting or budgeting. + + Periodic transactions can be a little tricky, so before you use them, + read this whole section, or at least these tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast + tag:generated. + + 3. Forecasted transactions will begin only after the last non-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 im- + provement, 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 + 2023/01, which is equivalent to ~ every 10th day of month from + 2023/01/01, will be adjusted to start on 2019/12/10. + + Periodic rule syntax + A periodic transaction rule looks like a normal journal entry, with the + date replaced by a tilde (~) followed by a period expression (mnemonic: + ~ looks like a recurring sine wave.): + + # every first of month + ~ monthly + expenses:rent $2000 + assets:bank:checking + + # every 15th of month in 2023's first quarter: + ~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying multi-pe- + riod reports, just interpreted differently; there, it specifies report + periods; here it specifies recurrence dates (the periods' start dates). + + 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 re- + sults 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 2023" + ; || + ; vv + ~ every 2 months in 2023, 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 ex- + pression. + + Auto postings + The = directive declares a rule for generating temporary extra postings + on transactions. Wherever the rule matches an existing posting, it can + add one or more companion postings below that one, optionally influ- + enced by the matched posting's amount. This can be useful for generat- + ing tax postings with a standard percentage, for example. + + Note that depending on generated data is not ideal for financial + records (it's less portable, less future-proof, less auditable by oth- + ers, and less robust, since other features like balance assertions will + depend on using or not using --auto). + + 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". + + Auto postings on forecast transactions only + Tip: you can can make auto postings that will apply to forecast trans- + actions but not recorded transactions, by adding tag:_generated-trans- + action to their QUERY. This can be useful when generating new journal + entries to be saved in the journal. + + Other syntax + hledger journal format supports quite a few other features, mainly to + make interoperating with or converting from Ledger easier. Note some + of the features below are powerful and can be useful in special cases, + but in general, features in this section are considered less important + or even not recommended for most users. Downsides are mentioned to + help you decide if you want to use them. + + 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). + + Downsides: using balance assignments makes your journal less explicit; + to know the exact amount posted, you have to run hledger or do the cal- + culations yourself, instead of just reading it. Also balance assign- + ments' forcing of balances can hide errors. These things make your fi- + nancial data less portable, less future-proof, and less trustworthy in + an audit. + + Balance assignments and prices + A cost in a balance assignment will cause the calculated amount to have + that price attached: + + 2019/1/1 + (a) = $1 @ 2 + + $ hledger print --explicit + 2019-01-01 + (a) $1 @ 2 = $1 @ 2 + + Balance assignments and multiple files + Balance assignments handle multiple files like balance assertions. + They see balance from other files previously included from the current + file, but not from previous sibling or parent files. + + Bracketed posting dates + For setting posting dates and secondary posting dates, Ledger's brack- + eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in + posting comments. hledger will attempt to parse any square-bracketed + sequence of the 0123456789/-.= characters in this way. With this syn- + tax, DATE infers its year from the transaction and DATE2 infers its + year from DATE. + + Downsides: another syntax to learn, redundant with hledger's + date:/date2: tags, and confusingly similar to Ledger's lot date syntax. + + D directive + D AMOUNT + + This directive sets a default commodity, to be used for any subsequent + commodityless amounts (ie, plain numbers) seen while parsing the 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 di- + rective (setting the commodity's decimal mark for parsing and display + style for output). So its argument is not just a commodity symbol, but + a full amount demonstrating the style. The amount must include a deci- + mal mark (either period or comma). Eg: + + ; commodity-less amounts should be treated as dollars + ; (and displayed with the dollar sign on the left, thousands separators and two decimal places) + D $1,000.00 + + 1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity's display style, a commodity directive has + highest priority, then a D directive. + + For detecting a commodity's decimal mark during parsing, decimal-mark + has highest priority, then commodity, then D. + + For checking commodity symbols with the check command, a commodity di- + rective is required (hledger check commodities ignores D directives). + + Downsides: omitting commodity symbols makes your financial data less + explicit, less portable, and less trustworthy in an audit. It is usu- + ally an unsustainable shortcut; sooner or later you will want to track + multiple commodities. D is overloaded with functions redundant with + commodity and decimal-mark. And it works differently from Ledger's D. + + apply account directive + This directive sets a default parent account, which will be prepended + to all accounts in following entries, until an end apply account direc- + tive or end of current file. Eg: + + apply account home + + 2010/1/1 + food $10 + cash + + end apply account + + is equivalent to: + + 2010/01/01 + home:food $10 + home:cash $-10 + + account directives are also affected, and so is any included content. + + Account names entered via hledger add or hledger-web are not affected. + + Account aliases, if any, are applied after the parent account is + prepended. + + Downsides: this can make your financial data less explicit, less + portable, and less trustworthy in an audit. + + Y directive + Y YEAR + + or (deprecated backward-compatible forms): + + year YEAR apply year YEAR + + The space is optional. This sets a default year to be used for subse- + quent dates which don't specify a year. Eg: + + Y2009 ; set default year to 2009 + + 12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + + year 2010 ; change default year to 2010 + + 2009/1/30 ; specifies the year, not affected + expenses 1 + assets + + 1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at least) + makes your financial data less explicit, less portable, and less trust- + worthy in an audit. Such dates can get separated from their corre- + sponding Y directive, eg when evaluating a region of the journal in + your editor. A missing Y directive makes reports dependent on today's + date. + + Secondary dates + A secondary date is written after the primary date, following an equals + sign. If the year is omitted, the primary date's year is assumed. + When running reports, the primary (left) date is used by default, but + with the --date2 flag (or --aux-date or --effective), the secondary + (right) date will be used instead. + + The meaning of secondary dates is up to you, but it's best to follow a + consistent rule. Eg "primary = the bank's clearing date, secondary = + date the transaction was initiated, if different". + + Downsides: makes your financial data more complicated, less portable, + and less trustworthy in an audit. Keeping the meaning of the two dates + consistent requires discipline, and you have to remember which report- + ing mode is appropriate for a given report. Posting dates are simpler + and better. + + Star comments + Lines beginning with * (star/asterisk) are also comment lines. This + feature allows Emacs users to insert org headings in their journal, al- + lowing them to fold/unfold/navigate it like an outline when viewed with + org mode. + + Downsides: another, unconventional comment syntax to learn. Decreases + your journal's portability. And switching to Emacs org mode just for + folding/unfolding meant losing the benefits of ledger mode; nowadays + you can add outshine mode to ledger mode to get folding without losing + ledger mode's features. + + Valuation expressions + Ledger allows a valuation function or value to be written in double + parentheses after an amount. hledger ignores these. + + Virtual postings + A posting with parentheses around the account name ((some:account)) is + called a unbalanced virtual posting. Such postings do not participate + in transaction balancing. (And if you write them without an amount, a + zero amount is always inferred.) These can occasionally be convenient + for special circumstances, but they violate double entry bookkeeping + and make your data less portable across applications, so many people + avoid using them at all. + + A posting with brackets around the account name ([some:account]) is + called a balanced virtual posting. The balanced virtual postings in a + transaction must add up to zero, just like ordinary postings, but sepa- + rately from them. These are not part of double entry bookkeeping ei- + ther, but they are at least balanced. An example: + + 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Ordinary postings, whose account names are neither parenthesised nor + bracketed, are called real postings. You can exclude virtual postings + from reports with the -R/--real flag or a real:1 query. + + Other Ledger directives + These other Ledger directives are currently accepted but ignored. This + allows hledger to read more Ledger files, but be aware that hledger's + reports may differ from Ledger's if you use these. + + apply fixed COMM AMT + apply tag TAG + assert EXPR + bucket / A ACCT + capture ACCT REGEX + check EXPR + define VAR=EXPR + end apply fixed + end apply tag + end apply year + end tag + eval / expr EXPR + python + PYTHONCODE + tag NAME + value EXPR + --command-line-flags + + See also https://hledger.org/ledger.html for a detailed hledger/Ledger + syntax comparison. + +CSV + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records, automatically converting + each record into a transaction. + + (To learn about writing CSV, see CSV output.) + + For best error messages when reading CSV/TSV/SSV files, make sure they + have a corresponding .csv, .tsv or .ssv file extension or use a hledger + file prefix (see File Extension below). + + Each CSV file must be described by a corresponding rules file. + This contains rules describing the CSV data (header line, fields lay- + out, date format etc.), how to construct hledger transactions from it, + and how to categorise transactions based on description or other at- + tributes. + + By default hledger looks for a rules file named like the CSV file with + an extra .rules extension, in the same directory. Eg when asked to + read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec- + ify a different rules file with the --rules-file option. If no rules + file is found, hledger will create a sample rules file, which you'll + need to adjust. + + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines + there are. Here's a simple CSV file and a rules file for it: + + Date, Description, Id, Amount + 12/11/2019, Foo, 123, 10.23 + + # basic.csv.rules + skip 1 + fields date, description, , amount + date-format %d/%m/%Y + + $ hledger print -f basic.csv + 2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There's an introductory Importing CSV data tutorial on hledger.org, and + more CSV rules examples below, and a larger collection at + https://github.com/simonmichael/hledger/tree/master/examples/csv. + + CSV rules cheatsheet + The following kinds of rule can appear in the rules file, in any order. + (Blank lines and lines beginning with # or ; or * are ignored.) + + source optionally declare which file to read data + from + separator declare the field separator, instead of rely- + ing on file extension + skip skip one or more header lines at start of file + date-format declare how to parse CSV dates/date-times + timezone declare the time zone of ambiguous CSV date- + times + newest-first improve txn order when: there are multiple + records, newest first, all with the same date + intra-day-reversed improve txn order when: same-day txns are in + opposite order to the overall file + decimal-mark declare the decimal mark used in CSV amounts, + when ambiguous + fields list name CSV fields for easy reference, and op- + tionally assign their values to hledger fields + Field assignment assign a CSV value or interpolated text value + to a hledger field + if block conditionally assign values to hledger fields, + or skip a record or end (skip rest of file) + if table conditionally assign values to hledger fields, + using compact syntax + balance-type select which type of balance assertions/as- + signments to generate + include inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are + evaluated. + + source + If you tell hledger to read a csv file with -f foo.csv, it will look + for rules in foo.csv.rules. Or, you can tell it to read the rules + file, with -f foo.csv.rules, and it will look for data in foo.csv + (since 1.30). + + These are mostly equivalent, but the second method provides some extra + features. For one, the data file can be missing, without causing an + error; it is just considered empty. And, you can specify a different + data file by adding a "source" rule: + + source ./Checking1.csv + + If you specify just a file name with no path, hledger will look for it + in your system's downloads directory (~/Downloads, currently): + + source Checking1.csv + + And if you specify a glob pattern, hledger will read the most recent of + the matched files (useful with repeated downloads): + + source Checking1*.csv + + See also "Working with CSV > Reading files specified by rule". + + 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. + + skip + skip N + + The word skip followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines at the start of the input + data. You'll need this whenever your CSV data contains header lines. + Note, empty and blank lines are skipped automatically, so you don't + need to count those. + + skip has a second meaning: it can be used inside if blocks (described + below), to skip one or more records whenever the condition is true. + Records skipped in this way are ignored, except they are still required + to be valid CSV. + + date-format + date-format DATEFMT + + This is a helper for the date (and date2) fields. If your CSV dates + are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll + need to add a date-format rule describing them with a strptime-style + date parsing pattern - see https://hackage.haskell.org/pack- + age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must + parse the CSV date value completely. Some examples: + + # MM/DD/YY + date-format %m/%d/%y + + # D/M/YYYY + # The - makes leading zeros optional. + date-format %-d/%-m/%Y + + # YYYY-Mmm-DD + date-format %Y-%h-%d + + # M/D/YYYY HH:MM AM some other junk + # Note the time and junk must be fully parsed, though only the date is used. + date-format %-m/%-d/%Y %l:%M %p some other junk + + timezone + timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone + other than yours, but containing no explicit time zone information, you + can use this rule to declare the CSV's native time zone, which helps + prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don't + need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see + the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware conversion, + localising the CSV date-times to your current system time zone. If you + prefer to localise to some other time zone, eg for reproducibility, you + can (on unix at least) set the output timezone with the TZ environment + variable, eg: + + $ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + timezone currently does not understand timezone names, except "UTC", + "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For + others, use numeric format: +HHMM or -HHMM. + + newest-first + hledger tries to ensure that the generated transactions will be ordered + chronologically, including same-day transactions. Usually it can auto- + detect how the CSV records are ordered. But if it encounters CSV where + all records are on the same date, it assumes that the records are old- + est first. If in fact the CSV's records are normally newest first, + like: + + 2022-10-01, txn 3... + 2022-10-01, txn 2... + 2022-10-01, txn 1... + + you can add the newest-first rule to help hledger generate the transac- + tions in correct order. + + # same-day CSV records are newest first + newest-first + + intra-day-reversed + If CSV records within a single day are ordered opposite to the overall + record order, you can add the intra-day-reversed rule to improve the + order of journal entries. Eg, here the overall record order is newest + first, but same-day records are oldest first: + + 2022-10-02, txn 3... + 2022-10-02, txn 4... + 2022-10-01, txn 1... + 2022-10-01, txn 2... + + # transactions within each day are reversed with respect to the overall date order + intra-day-reversed + + 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. + + fields list + fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word fields followed by comma-separated field names) + is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say %SomeField + instead of remembering %13. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and + build a transaction. + + Here's an example that says "use the 1st, 2nd and 4th fields as the + transaction's date, description and amount; name the last two fields + for later reference; and ignore the others": + + fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to the + CSV file's separator. Also: + + o 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 Fields you don't care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it's convenient to use these for + your field names, suitably modified (eg lower-cased with spaces re- + placed by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning to + a hledger field with the same name. Eg you could call the CSV's "bal- + ance" field balance_ to avoid directly setting hledger's balance field + (and generating a balance assertion). + + Field assignment + HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to + hledger fields. They can be used instead of or in addition to a fields + list (see above). + + To assign a value to a hledger field, write the field name (any of the + standard hledger field/pseudo-field names, defined below), a space, + followed by a text value on the same line. This text value may inter- + polate CSV fields, referenced either by their 1-based position in the + CSV record (%N) or by the name they were given in the fields list + (%CSVFIELD), and regular expression match groups (\N). + + 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 " be- + comes 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 + Note the two kinds of field names mentioned here, and used only in + hledger CSV rules files: + + 1. CSV field names (CSVFIELD in these docs): you can optionally name + the CSV columns for easy reference (since hledger doesn't yet auto- + matically recognise column headings in a CSV file), by writing arbi- + trary names in a fields list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special hledger field names (HLEDGERFIELD in these docs): you must + set at least some of these to generate the hledger transaction from + a CSV record, by writing them as the left hand side of a field as- + signment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a fields list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what hap- + pens when you assign values to them: + + 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. + + 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. + + account field + Assigning to accountN, where N is 1 to 99, sets the account name of the + Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you'll want to set account1 and + account2. Typically account1 is associated with the CSV file, and is + set once with a top-level assignment, while account2 is set based on + each transaction's description, in conditional rules. + + If a posting's account name is left unset but its amount is set (see + below), a default account name will be chosen (like "expenses:unknown" + or "income:unknown"). + + amount field + There are several ways to set posting amounts from CSV, useful in dif- + ferent situations. + + 1. amount is the oldest and simplest. Assigning to this sets the + amount of the first and second postings. In the second posting, the + amount will be negated; also, if it has a cost attached, it will be + converted to cost. + + 2. amount-in and amount-out work exactly like the above, but should be + used when the CSV has two amount fields (such as "Debit" and + "Credit", or "Inflow" and "Outflow"). Whichever field has a non- + zero value will be used as the amount of the first and second post- + ings. Here are some tips to avoid confusion: + + o It's not "amount-in for posting 1 and amount-out for posting 2", + it is "extract a single amount from the amount-in or amount-out + field, and use that for posting 1 and (negated) for posting 2". + + o Don't use both amount and amount-in/amount-out in the same rules + file; choose based on whether the amount is in a single CSV field + or spread across two fields. + + o In each record, at most one of the two CSV fields should contain + a non-zero amount; the other field must contain a zero or noth- + ing. + + o hledger assumes both CSV fields contain unsigned numbers, and it + automatically negates the amount-out values. + + o If the data doesn't fit these requirements, you'll probably need + an if rule (see below). + + 3. amountN (where N is a number from 1 to 99) sets the amount of only a + single posting: the Nth posting in the transaction. You'll usually + need at least two such assignments to make a balanced transaction. + You can also generate more than two postings, to represent more com- + plex transactions. The posting numbers don't have to be consecu- + tive; with if rules, higher posting numbers can be useful to ensure + a certain order of postings. + + 4. amountN-in and amountN-out work exactly like the above, but should + be used when the CSV has two amount fields. This is analogous to + amount-in and amount-out, and those tips also apply here. + + 5. Remember that a fields list can also do assignments. So in a fields + list if you name a CSV field "amount", that counts as assigning to + amount. (If you don't want that, call it something else in the + fields list, like "amount_".) + + 6. The above don't handle every situation; if you need more flexibil- + ity, use an if rule to set amounts conditionally. See "Working with + CSV > Setting amounts" below for more on this and on amount-setting + generally. + + 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. + + if block + Rules can be applied conditionally, depending on patterns in the CSV + data. This allows flexibility; in particular, it is how you can cate- + gorise transactions, selecting an appropriate account name based on + their description (for example). There are two ways to write condi- + tional rules: "if blocks", described here, and "if tables", described + below. + + An if block is the word if and one or more "matcher" expressions (can + be a word or phrase), one per line, starting either on the same or next + line; followed by one or more indented rules. Eg, + + if MATCHER + RULE + + or + + if + MATCHER + MATCHER + MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be ap- + plied. They are usually field assignments, but the following special + rules may also be used within an if block: + + o skip - skips the matched CSV record (generating no transaction from + it) + + o end - skips the rest of the current CSV file. + + Some examples: + + # if the record contains "groceries", set account2 to "expenses:groceries" + if groceries + account2 expenses:groceries + + # if the record contains any of these phrases, set account2 and a transaction comment as shown + if + monthly service fee + atm transaction fee + banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + # if an empty record is seen (assuming five fields), ignore the rest of the CSV file + if ,,,, + end + + Matchers + There are two kinds: + + 1. A record matcher is a word or single-line text fragment or regular + expression (REGEX), which hledger will try to match case-insensi- + tively anywhere within the CSV record. + Eg: whole foods + + 2. A field matcher is preceded with a percent sign and CSV field name + (%CSVFIELD REGEX). hledger will try to match these just within the + named CSV field. + Eg: %date 2023 + + The regular expression is (as usual in hledger) a POSIX extended regu- + lar expression, that also supports GNU word boundaries (\b, \B, \<, + \>), and nothing else. If you have trouble, see "Regular expressions" + in the hledger manual (https://hledger.org/hledger.html#regular-expres- + sions). + + What matchers match + With record matchers, it's important to know that the record matched is + not the original CSV record, but a modified one: separators will be + converted to commas, and enclosing double quotes (but not enclosing + whitespace) are removed. So for example, when reading an SSV file, if + the original record was: + + 2023-01-01; "Acme, Inc."; 1,000 + + the regex would see, and try to match, this modified record text: + + 2023-01-01,Acme, Inc., 1,000 + + Combining matchers + When an if block has multiple matchers, they are combined as follows: + + o By default they are OR'd (any one of them can match) + + o When a matcher is preceded by ampersand (&) it will be AND'ed with + the previous matcher (both of them must match) + + o When a matcher is preceded by an exclamation mark (!), the matcher is + negated (it may not match). + + Currently there is a limitation: you can't use both & and ! on the same + line (you can't AND a negated matcher). + + Match groups + Matchers can define match groups: parenthesised portions of the regular + expression which are available for reference in field assignments. + Groups are enclosed in regular parentheses (( and )) and can be nested. + Each group is available in field assignments using the token \N, where + N is an index into the match groups for this conditional block (e.g. + \1, \2, etc.). + + Example: Warp credit card payment postings to the beginning of the + billing period (Month start), to match how they are presented in state- + ments, using posting dates: + + if %date (....-..)-.. + comment2 date:\1-01 + + Another example: Read the expense account from the CSV field, but throw + away a prefix: + + if %account1 liabilities:family:(expenses:.*) + account1 \1 + + if table + "if tables" are an alternative to if blocks; they can express many + matchers and field assignments in a more compact tabular format, like + this: + + if,HLEDGERFIELD1,HLEDGERFIELD2,... + MATCHERA,VALUE1,VALUE2,... + MATCHERB,VALUE1,VALUE2,... + MATCHERC,VALUE1,VALUE2,... + + + The first character after if is taken to be this if table's field sepa- + rator. It is unrelated to the separator used in the CSV file. It + should be a non-alphanumeric character like , or | that does not appear + anywhere else in the table (it should not be used in field names or + matchers or values, and it cannot be escaped with a backslash). + + Each line must contain the same number of separators; empty values are + allowed. Whitespace can be used in the matcher lines for readability + (but not in the if line, currently). The table must be terminated by + an empty line (or end of file). + + An if table like the above is interpreted as follows: try all of the + matchers; whenever a matcher succeeds, assign all of the values on that + line to the corresponding hledger fields; later lines can overrider + earlier ones. It is equivalent to this sequence of if blocks: + + if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + if MATCHERB + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + if MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + + if,account2,comment + atm transaction fee,expenses:business:banking,deductible? check it + %description groceries,expenses:groceries, + 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + 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 + + 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 + + Working with CSV + Some 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 + Note that hledger will only accept valid CSV conforming to RFC 4180, + and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or + tab as separators). This means, eg: + + o Values may be enclosed in double quotes, or not. Enclosing in single + quotes is not allowed. (Eg 'A','B' is rejected.) + + o When values are enclosed in double quotes, spaces outside the quotes + are not allowed. (Eg "A", "B" is rejected.) + + o When values are not enclosed in quotes, they may not contain double + quotes. (Eg A"A, B is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- + form it before reading with hledger. Try using sed, or a more permis- + sive CSV parser like python's csv lib. + + File Extension + To help hledger choose the CSV file reader and show the right error + messages (and choose the right field separator character by default), + it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv + filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV + reader (and the default field separator) by prefixing the file path + with csv:, ssv: or tsv:: Eg: + + $ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator rule + if needed. + + Reading CSV from standard input + You'll need the file format prefix when reading CSV from stdin also, + since hledger assumes journal format by default. Eg: + + $ cat foo.dat | hledger -f ssv:- print + + 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. + + Reading files specified by rule + Instead of specifying a CSV file in the command line, you can specify a + rules file, as in hledger -f foo.csv.rules CMD. By default this will + read data from foo.csv in the same directory, but you can add a source + rule to specify a different data file, perhaps located in your web + browser's download directory. + + This feature was added in hledger 1.30, so you won't see it in most CSV + rules examples. But it helps remove some of the busywork of managing + CSV downloads. Most of your financial institutions's default CSV file- + names are different and can be recognised by a glob pattern. So you + can put a rule like source Checking1*.csv in foo-checking.csv.rules, + and then periodically follow a workflow like: + + 1. Download CSV from Foo's website, using your browser's defaults + + 2. Run hledger import foo-checking.csv.rules to import any new transac- + tions + + After import, you can: discard the CSV, or leave it where it is for a + while, or move it into your archives, as you prefer. If you do noth- + ing, next time your browser will save something like Checking1-2.csv, + and hledger will use that because of the * wild card and because it is + the most recent. + + 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 as- + sertions 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 + Continuing from amount field above, here are more tips for amount-set- + ting: + + 1. If the amount is in a single CSV field: + a. If its sign indicates direction of flow: + Assign it to amountN, to set the Nth posting's amount. N is usu- + ally 1 or 2 but can go up to 99. + + b. If another field indicates direction of flow: + Use one or more conditional rules to set the appropriate amount + sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. If the amount is in two CSV fields (such as Debit and Credit, or In + and Out): + a. If both fields are unsigned: + Assign one field to amountN-in and the other to amountN-out. + hledger will automatically negate the "out" field, and will use + whichever field value is non-zero as posting N's amount. + + b. If either field is signed: + You will probably need to override hledger's sign for one or the + other field, as in the following example: + + # Negate the -out value, but only if it is not empty: + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. If both fields can contain a non-zero value (or both can be + empty): + The -in/-out rules normally choose the value which is non-zero/non- + empty. Some value pairs can be ambiguous, such as 1 and none. For + such cases, use conditional rules to help select the amount. Eg, + to handle the above you could select the value containing non-zero + digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. If you want posting 2's amount converted to cost: + Use the unnumbered amount (or amount-in and amount-out) syntax. + + 4. If the CSV has only balance amounts, not transaction amounts: + Assign to balanceN, to set a balance assignment on the Nth posting, + causing the posting's amount to be calculated automatically. balance + with no number is equivalent to balance1. In this situation hledger is + more likely to guess the wrong default account name, so you may need to + set that explicitly. + + Amount signs + There is some special handling making it easier to parse and to reverse + amount signs. (This only works for whole amounts, not for cost amounts + such as COST in amount1 AMT @ COST): + + 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 + "". + + It's not possible (without preprocessing the CSV) to set an amount to + its absolute value, ie discard its sign. + + Setting currency/commodity + If the currency/commodity symbol is included in the CSV's amount + field(s): + + 2023-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 + + 2023-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + + 2023-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 + + 2023-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 + + 2023-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 re- + peated, 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 re- + maining 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 as- + signed to it (and interpolate the %CSVFIELD references), or a default + + o generate a hledger transaction (journal entry) from these values. + + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the + user specified. + + Well factored rules + Some things than can help reduce duplication and complexity in rules + files: + + o Extracting common rules usable with multiple CSV files into a com- + mon.rules, and adding include common.rules to each CSV's rules file. + + o Splitting if blocks into smaller if blocks, extracting the frequently + used parts. + + CSV rules examples + 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. + + Coinbase + A simple example with some CSV from Coinbase. The spot price is + recorded using cost notation. The legacy amount field name conve- + niently sets amount 2 (posting 2's amount) to the total cost. + + # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes + # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + + # coinbase.csv.rules + skip 1 + fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes + date %Timestamp + date-format %Y-%m-%dT%T%Z + description %Notes + account1 assets:coinbase:cc + amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + + $ hledger print -f coinbase.csv + 2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + 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: + +Timeclock + The time logging format of timeclock.el, as read by hledger. + + hledger can read time logs in timeclock format. As with Ledger, these + are (a subset of) timeclock.el's format, containing clock-in and clock- + out entries as in the example below. The date is a simple date. The + time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. + The timezone, if present, must be four digits and is ignored (currently + the time is always interpreted as a local time). Lines beginning with + # or ; or *, and blank lines, are ignored. + + i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: + 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 2 spaces ; optional comment, tags: + (some account) 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 + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is more convenient for quick, approxi- + mate, and retroactive time logging, and more human-readable (you can + see at a glance where time was spent). A quick example: + + 2023-05-01 + hom:errands .... .... ; two hours; the space is ignored + fos:hledger:timedot .. ; half an hour + per:admin:finance ; no time spent yet + + hledger reads this as a transaction on this day with three (unbalanced) + postings, where each dot represents "0.25". No commodity symbol is as- + sumed, but we typically interpret it as hours. + + $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required + 2023-05-01 * + (hom:errands) 2.00 ; two hours + (fos:hledger:timedot) 0.50 ; half an hour + (per:admin:finance) 0 + + A timedot file contains a series of transactions (usually one per day). + Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be + followed on the same line by a transaction description, and/or a trans- + action comment following a semicolon. + + After the date line are zero or more time postings, consisting of: + + o An account name - any hledger-style account name, optionally in- + dented. + + o Two or more spaces - required if there is an amount (as in journal + format). + + o A timedot amount, which can be + + o empty (representing zero) + + o a number, optionally followed by a unit s, m, h, d, w, mo, or y, + representing a precise number of seconds, minutes, hours, days + weeks, months or years (hours is assumed by default), which will be + converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = + 1w, 30d = 1mo, 365d = 1y. + + o one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can be + used for grouping/alignment. + + o one or more letters. These are like dots but they also generate a + tag t: (short for "type") with the letter as its value, and a sepa- + rate posting for each of the values. This provides a second dimen- + sion of categorisation, viewable in reports with --pivot t. + + o An optional comment following a semicolon (a hledger-style posting + comment). + + There is some flexibility to help with keeping time log data and notes + in the same file: + + o Blank lines and lines beginning with # or ; are ignored. + + o After the first date line, lines which do not contain a double space + are parsed as postings with zero amount. (hledger's register reports + will show these if you add -E). + + o Before the first date line, lines beginning with * (eg org headings) + are ignored. And from the first date line onward, Emacs org mode + heading prefixes at the start of lines (one or more *'s followed by a + space) will be ignored. This means the time log can also be a org + outline. + + Timedot examples + Numbers: + + 2016/2/3 + inc:client1 4 + fos:hledger 3h + biz:research 60m + + Dots: + + # 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 . + + $ 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 + + Letters: + + # Activity types: + # c cleanup/catchup/repair + # e enhancement + # s support + # l learning/research + + 2023-11-01 + work:adm ccecces + + $ hledger -f a.timedot print + 2023-11-01 + (work:adm) 1 ; t:c + (work:adm) 0.5 ; t:e + (work:adm) 0.25 ; t:s + + $ hledger -f a.timedot bal + 1.75 work:adm + -------------------- + 1.75 + + $ hledger -f a.timedot bal --pivot t + 1.00 c + 0.50 e + 0.25 s + -------------------- + 1.75 + + Org: + + * 2023 Work Diary + ** Q1 + *** 2023-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 + + Using . as account name separator: + + 2016/2/4 + fos.hledger.timedot 4h + fos.ledger .. + + $ hledger -f a.timedot --alias '/\./=:' bal -t + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger + -------------------- + 4.50 + +PART 3: REPORTING CONCEPTS +Amount formatting, parseability + If you're wondering why your print report sometimes shows trailing dec- + imal marks, with no decimal digits; it does this when showing amounts + that have digit group marks but no decimal digits, to disambiguate them + and allow them to be re-parsed reliably (see also Decimal marks, digit + group marks. Eg: + + commodity $1,000.00 + + 2023-01-02 + (a) $1000 + + $ hledger print + 2023-01-02 + (a) $1,000. + + If this is a problem (eg when exporting to Ledger), you can avoid it by + disabling digit group marks, eg with -c/--commodity (for each affected + commodity): + + $ hledger print -c '$1000.00' + 2023-01-02 + (a) $1000 + + or by forcing print to always show decimal digits, with --round: + + $ hledger print -c '$1,000.00' --round=soft + 2023-01-02 + (a) $1,000.00 + + More generally: hledger output falls into three rough categories, which + format amounts a little bit differently to suit different consumers: + + 1. "hledger-readable output" - should be readable by hledger (and by + humans) + + o This is produced by reports that show full journal entries: print, + import, close, rewrite etc. + + o It shows amounts with their original journal precisions, which may + not be consistent. + + o It adds a trailing decimal mark when needed to avoid showing ambigu- + ous amounts. + + o It can be parsed reliably (by hledger and ledger2beancount at least, + but perhaps not by Ledger..) + + 2. "human-readable output" - usually for humans + + o This is produced by all other reports. + + o It shows amounts with standard display precisions, which will be con- + sistent within each commodity. + + o It shows ambiguous amounts unmodified. + + o It can be parsed reliably in the context of a known report (when you + know decimals are consistently not being shown, you can assume a sin- + gle mark is a digit group mark). + + 3. "machine-readable output" - usually for other software + + o This is produced by all reports when an output format like csv, tsv, + json, or sql is selected. + + o It shows amounts as 1 or 2 do, but without digit group marks. + + o It can be parsed reliably (if needed, the decimal mark can be changed + with -c/--commodity-style). + +Time periods + Report start & end date + By default, most hledger reports will show the full span of time repre- + sented by the journal. The report start date will be the earliest + transaction or posting date, and the report end date will be the latest + transaction, posting, or market price date. + + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, + -e/--end, -p/--period or a date: query (described below). All of these + accept the smart date syntax (below). + + Some notes: + + 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 In some cases a report interval will adjust start/end dates to fall + on interval boundaries (see below). + + 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 re- + placed with -) + date:..12/1 + date:thismonth.. + date:thismonth + + Smart dates + hledger's user interfaces accept a "smart date" syntax for added conve- + nience. Smart dates optionally can be relative to today's date, be + written with english words, and have less-significant parts omitted + (missing parts are inferred as 1). Some examples: + + 2004/10/1, 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 + + Some counterexamples - malformed digit sequences might give surprising + results: + + 201813 6 digits with an invalid month is parsed as start of + 6-digit year + 20181301 8 digits with an invalid month is parsed as start of + 8-digit year + 20181232 8 digits with an invalid day gives an error + 201801012 9+ digits beginning with a valid YYYYMMDD gives an error + + "Today's date" can be overridden with the --today option, in case it's + needed for testing or for recreating old reports. (Except for periodic + transaction rules, which are not affected by --today.) + + Report intervals + A report interval can be specified so that reports like register, bal- + ance or activity become multi-period, showing each subperiod as a sepa- + rate row or column. + + The following standard intervals can be enabled with command-line + flags: + + o -D/--daily + + o -W/--weekly + + o -M/--monthly + + o -Q/--quarterly + + o -Y/--yearly + + More complex intervals can be specified using -p/--period, described + below. + + Date adjustment + When there is a report interval (other than daily), report start/end + dates which have been inferred, eg from the journal, are automatically + adjusted to natural period boundaries. This is convenient for produc- + ing simple periodic reports. More precisely: + + o an inferred start date will be adjusted earlier if needed to fall on + a natural period boundary + + o an inferred end date will be adjusted later if needed to make the + last period the same length as the others. + + By contrast, start/end dates which have been specified explicitly, with + -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This + makes it possible to specify non-standard report periods, but it also + means that if you are specifying a start date, you should pick one + that's on a period boundary if you want to see simple report period + headings. + + Period expressions + The -p/--period option specifies a period expression, which is a com- + pact way of expressing a start date, end date, and/or report interval. + + Here's a period expression with a start and end date (specifying the + first quarter of 2009): + + -p "from 2009/1/1 to 2009/4/1" + + Several keywords like "from" and "to" are supported for readability; + these are optional. "to" can also be written as ".." or "-". The + spaces are also optional, as long as you don't run two dates together. + So the following are equivalent to the above: + + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1..2009/4/1 + + Dates are smart dates, so if the current year is 2009, these are also + equivalent to the above: + + -p "1/1 4/1" + -p "jan-apr" + -p "this year to 4/1" + + If you specify only one date, the missing start or end date will be the + earliest or latest transaction date in the journal: + + -p "from 2009/1/1" everything after january + 1, 2009 + -p "since 2009/1" the same, since is a syn- + onym + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 + + You can also specify a period by writing a single partial or full date: + + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to + 2009/1/2" + + or by using the "Q" quarter-year syntax (case insensitive): + + -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to + 2009/4/1" + -p "q4" fourth quarter of the current year + + Period expressions with a report interval + A period expression can also begin with a report interval, separated + from the start/end dates (if any) by a space or the word in: + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "quarterly" + + More complex report intervals + Some more complex intervals can be specified within period expressions, + such as: + + o biweekly (every two weeks) + + o fortnightly + + o bimonthly (every two months) + + o every day|week|month|quarter|year + + o every N days|weeks|months|quarters|years + + Weekly on a 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 a custom day: + + o every Nth day [of month] + + o every Nth WEEKDAYNAME [of month] + + Yearly on a 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 "bimonthly from 2008" + -p "every 2 weeks" + -p "every 5 months from + 2009/03" + -p "every 2nd day of week" periods will go from Tue to Tue + -p "every Tue" same + -p "every 15th day" period boundaries will be on 15th of each + month + -p "every 2nd Monday" period boundaries will be on second Monday + of each month + -p "every 11/05" yearly periods with boundaries on 5th of + 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" + + Multiple weekday intervals + This special form is also supported: + + o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- + day names, case insensitive) + + Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and + sat,sun. + + This is mainly intended for use with --forecast, to generate periodic + transactions on arbitrary days of the week. It may be less useful with + -p, since it divides each week into subperiods of unequal length, which + is unusual. (Related: #1632) + + Examples: + + -p "every dates will be Mon, Wed, Fri; periods will be Mon- + 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), reports will show ac- + counts only to the specified depth, hiding deeper subaccounts. Use + this when you want a summary with less detail. This flag has the same + effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- + lent. + +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 ac- + count 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:202312- + status: + desc:amazon + cur:USD + "amt:>0" + + o Add a not: prefix to negate: + + not:cur:USD + + o Multiple unlike terms are AND-ed, multiple like terms are OR-ed + + date:2022 desc:amazon desc:amzn + (all transactions with "amazon" or "amzn" in description during 2022) + + 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 es- + caping. 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 in- + terval. 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. + + expr:"TERM AND NOT (TERM OR TERM)" (eg) + Match with a boolean combination of queries (which must be enclosed in + quotes). See Combining query terms below. + + 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 + When given multiple space-separated 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. + + The print command is a little different, showing 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. + + We also support more complex boolean queries with the 'expr:' prefix. + This allows one to combine queries using one of three operators: AND, + OR, and NOT, where NOT is different syntax for 'not:'. + + Examples of such queries are: + + o Match transactions with 'cool' in the description AND with the 'A' + tag + + expr:"desc:cool AND tag:A" + + o Match transactions NOT to the 'expenses:food' account OR with the 'A' + tag + + expr:"NOT expenses:food OR tag:A" + + o Match transactions NOT involving the 'expenses:food' account OR with + the 'A' tag AND involving the 'expenses:drink' account. (the AND is + implicitly added by space-separation, following the rules above) + + expr:"expenses:food OR (tag:A expenses:drink)" + + Queries and command options + Some queries can also be expressed as command-line options: depth:2 is + equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When + you mix command options and query arguments, generally the resulting + query is their intersection. + + Queries and valuation + When amounts are converted to other commodities in cost or value re- + ports, 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 re- + versed, 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 re- + ports, 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. + +Pivoting + Normally, hledger groups and sums amounts within each account. The + --pivot FIELD option substitutes some other transaction field for ac- + count names, causing amounts to be grouped and summed by that field's + value instead. FIELD can be any of the transaction fields acct, sta- + tus, code, desc, payee, note, or a tag name. When pivoting on a tag + and a posting has multiple values of that tag, only the first value is + displayed. Values containing colon:separated:parts will be displayed + hierarchically, like account names. Multiple, colon-delimited fields + can be pivoted simultaneously, generating a hierarchical account name. + + Some examples: + + 2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe, kind: Lifetime + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + + Hierarchical reports can be generated with multiple pivots: + + $ hledger balance Income:Dues --pivot kind:member + -2 EUR Lifetime:John Doe + -------------------- + -2 EUR + +Generating data + hledger has several features for generating data, such as: + + o Periodic transaction rules can generate single or repeating transac- + tions following a template. These are usually dated in the future, + eg to help with forecasting. They are activated by the --forecast + option. + + o The balance command's --budget option uses these same periodic rules + to generate goals for the budget report. + + o Auto posting rules can generate extra postings on certain matched + transactions. They are always applied to forecast transactions; with + the --auto flag they are applied to transactions recorded in the + journal as well. + + o The --infer-equity flag infers missing conversion equity postings + from @/@@ costs. And the inverse --infer-costs flag infers missing + @/@@ costs from conversion equity postings. + + Generated data of this kind is temporary, existing only at report time. + But you can see it in the output of hledger print, and you can save + that to your journal, in effect converting it from temporary generated + data to permanent recorded data. This could be useful as a data entry + aid. + + If you are wondering what data is being generated and why, add the + --verbose-tags flag. In hledger print output you will see extra tags + like generated-transaction, generated-posting, and modified on gener- + ated/modified data. Also, even without --verbose-tags, generated data + always has equivalen hidden tags (with an underscore prefix), so eg you + could match generated transactions with tag:_generated-transaction. + +Forecasting + Forecasting, or speculative future reporting, can be useful for esti- + mating future balances, or for exploring different future scenarios. + + The simplest and most flexible way to do it with hledger is to manually + record a bunch of future-dated transactions. You could keep these in a + separate future.journal and include that with -f only when you want to + see them. + + --forecast + There is another way: with the --forecast option, hledger can generate + temporary "forecast transactions" for reporting purposes, according to + periodic transaction rules defined in the journal. Each rule can gen- + erate multiple recurring transactions, so by changing one rule you can + change many forecasted transactions. (These same rules can also gener- + ate budget goals, described in Budgeting.) + + Forecast transactions usually start after ordinary transactions end. + By default, they begin after your latest-dated ordinary transaction, or + today, whichever is later, and they end six months from today. (The + exact rules are a little more complicated, and are given below.) + + This is the "forecast period", which need not be the same as the report + period. You can override it - eg to forecast farther into the future, + or to force forecast transactions to overlap your ordinary transactions + - by giving the --forecast option a period expression argument, like + --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- + quired. + + Inspecting forecast transactions + print is the best command for inspecting and troubleshooting forecast + transactions. Eg: + + ~ monthly from 2022-12-20 rent + assets:bank:checking + expenses:rent $1000 + + $ hledger print --forecast --today=2023/4/21 + 2023-05-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-06-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-07-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-08-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-09-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + Here there are no ordinary transactions, so the forecasted transactions + begin on the first occurence after today's date. (You won't normally + use --today; it's just to make these examples reproducible.) + + Forecast reports + Forecast transactions affect all reports, as you would expect. Eg: + + $ hledger areg rent --forecast --today=2023/4/21 + Transactions in expenses:rent and subaccounts: + 2023-05-20 rent as:ba:checking $1000 $1000 + 2023-06-20 rent as:ba:checking $1000 $2000 + 2023-07-20 rent as:ba:checking $1000 $3000 + 2023-08-20 rent as:ba:checking $1000 $4000 + 2023-09-20 rent as:ba:checking $1000 $5000 + + $ hledger bal -M expenses --forecast --today=2023/4/21 + Balance changes in 2023-05-01..2023-09-30: + + || May Jun Jul Aug Sep + ===============++=================================== + expenses:rent || $1000 $1000 $1000 $1000 $1000 + ---------------++----------------------------------- + || $1000 $1000 $1000 $1000 $1000 + + Forecast tags + Forecast transactions generated by --forecast have a hidden tag, _gen- + erated-transaction. So if you ever need to match forecast transac- + tions, you could use tag:_generated-transaction (or just tag:generated) + in a query. + + For troubleshooting, you can add the --verbose-tags flag. Then, visi- + ble generated-transaction tags will be added also, so you can view them + with the print command. Their value indicates which periodic rule was + responsible. + + Forecast period, in detail + Forecast start/end dates are chosen so as to do something useful by de- + fault in almost all situations, while also being flexible. Here are + (with luck) the exact rules, to help with troubleshooting: + + The forecast period starts on: + + o the later of + + o the start date in the periodic transaction rule + + o the start date in --forecast's argument + + o otherwise (if those are not available): the later of + + o the report start date specified with -b/-p/date: + + o the day after the latest ordinary transaction in the journal + + o otherwise (if none of these are available): today. + + The forecast period ends on: + + o the earlier of + + o the end date in the periodic transaction rule + + o the end date in --forecast's argument + + o otherwise: the report end date specified with -e/-p/date: + + o otherwise: 180 days (~6 months) from today. + + Forecast troubleshooting + When --forecast is not doing what you expect, one of these tips should + help: + + o Remember to use the --forecast option. + + o Remember to have at least one periodic transaction rule in your jour- + nal. + + o Test with print --forecast. + + o Check for typos or too-restrictive start/end dates in your periodic + transaction rule. + + o Leave at least 2 spaces between the rule's period expression and de- + scription fields. + + o Check for future-dated ordinary transactions suppressing forecasted + transactions. + + o Try setting explicit report start and/or end dates with -b, -e, -p or + date: + + o Try adding the -E flag to encourage display of empty periods/zero + transactions. + + o Try setting explicit forecast start and/or end dates with --fore- + cast=START..END + + o Consult Forecast period, in detail, above. + + o Check inside the engine: add --debug=2 (eg). + +Budgeting + With the balance command's --budget report, each periodic transaction + rule generates recurring budget goals in specified accounts, and goals + and actual performance can be compared. See the balance command's doc + below. + + You can generate budget goals and forecast transactions at the same + time, from the same or different periodic transaction rules: hledger + bal -M --budget --forecast ... + + See also: Budgeting and Forecasting. + +Cost reporting + In some transactions - for example a currency conversion, or a purchase + or sale of stock - one commodity is exchanged for another. In these + transactions there is a conversion rate, also called the cost (when + buying) or selling price (when selling). In hledger docs we just say + "cost", for convenience; feel free to mentally translate to "conversion + rate" or "selling price" if helpful. + + Recording costs + We'll explore several ways of recording transactions involving costs. + These are also summarised at hledger Cookbook > Cost notation. + + Costs can be recorded explicitly in the journal, using the @ UNITCOST + or @@ TOTALCOST notation described in Journal > Costs: + + Variant 1 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 @ $1.35 ; $1.35 per euro (unit cost) + + Variant 2 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 @@ $135 ; $135 total cost + + Typically, writing the unit cost (variant 1) is preferable; it can be + more effort, requiring more attention to decimal digits; but it reveals + the per-unit cost basis, and makes stock sales easier. + + Costs can also be left implicit, and hledger will infer the cost that + is consistent with a balanced transaction: + + Variant 3 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 + + Here, hledger will attach a @@ 100 cost to the first amount (you can + see it with hledger print -x). This form looks convenient, but there + are downsides: + + o It sacrifices some error checking. For example, if you accidentally + wrote 10 instead of 100, hledger would not be able to detect the mis- + take. + + o It is sensitive to the order of postings - if they were reversed, a + different entry would be inferred and reports would be different. + + o The per-unit cost basis is not easy to read. + + So generally this kind of entry is not recommended. You can make sure + you have none of these by using -s (strict mode), or by running hledger + check balanced. + + Reporting at cost + Now when you add the -B/--cost flag to reports ("B" is from Ledger's + -B/--basis/--cost flag), any amounts which have been annotated with + costs will be converted to their cost's commodity (in the report out- + put). Ie they will be displayed "at cost" or "at sale price". + + Some things to note: + + o Costs are attached to specific posting amounts in specific transac- + tions, and once recorded they do not change. This contrasts with + market prices, which are ambient and fluctuating. + + o Conversion to cost is performed before conversion to market value + (described below). + + Equity conversion postings + There is a problem with the entries above - they are not conventional + Double Entry Bookkeeping (DEB) notation, and because of the "magical" + transformation of one commodity into another, they cause an imbalance + in the Accounting Equation. This shows up as a non-zero grand total in + balance reports like hledger bse. + + For most hledger users, this doesn't matter in practice and can safely + be ignored ! But if you'd like to learn more, keep reading. + + Conventional DEB uses an extra pair of equity postings to balance the + transaction. Of course you can do this in hledger as well: + + Variant 4 + + 2022-01-01 + assets:dollars $-135 + assets:euros 100 + equity:conversion $135 + equity:conversion -100 + + Now the transaction is perfectly balanced according to standard DEB, + and hledger bse's total will not be disrupted. + + And, hledger can still infer the cost for cost reporting, but it's not + done by default - you must add the --infer-costs flag like so: + + $ hledger print --infer-costs + 2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 @@ 100 + assets:euros 100 + equity:conversion $135 + equity:conversion -100 + + $ hledger bal --infer-costs -B + -100 assets:dollars + 100 assets:euros + -------------------- + 0 + + Here are some downsides of this kind of entry: + + o The per-unit cost basis is not easy to read. + + o Instead of -B you must remember to type -B --infer-costs. + + o --infer-costs works only where hledger can identify the two eq- + uity:conversion postings and match them up with the two non-equity + postings. So writing the journal entry in a particular format be- + comes more important. More on this below. + + Inferring equity conversion postings + Can we go in the other direction ? Yes, if you have transactions writ- + ten with the @/@@ cost notation, hledger can infer the missing equity + postings, if you add the --infer-equity flag. Eg: + + 2022-01-01 + assets:dollars -$135 + assets:euros 100 @ $1.35 + + $ hledger print --infer-equity + 2022-01-01 + assets:dollars $-135 + assets:euros 100 @ $1.35 + equity:conversion:$-: -100 + equity:conversion:$-:$ $135.00 + + The equity account names will be "equity:conversion:A-B:A" and "eq- + uity:conversion:A-B:B" where A is the alphabetically first commodity + symbol. You can customise the "equity:conversion" part by declaring an + account with the V/Conversion account type. + + Combining costs and equity conversion postings + Finally, you can use both the @/@@ cost notation and equity postings at + the same time. This in theory gives the best of all worlds - preserv- + ing the accounting equation, revealing the per-unit cost basis, and + providing more flexibility in how you write the entry: + + Variant 5 + + 2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion -100 + assets:euros 100 @ $1.35 + + All the other variants above can (usually) be rewritten to this final + form with: + + $ hledger print -x --infer-costs --infer-equity + + Downsides: + + o This was added in hledger-1.29 and is still somewhat experimental. + + o The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it + will give a transaction balancing error. + + o The add command does not yet accept this kind of entry (#2056). + + o This is the most verbose form. + + Requirements for detecting equity conversion postings + --infer-costs has certain requirements (unlike --infer-equity, which + always works). It will infer costs only in transactions with: + + o Two non-equity postings, in different commodities. Their order is + significant: the cost will be added to the first of them. + + o Two postings to equity conversion accounts, next to one another, + which balance the two non-equity postings. This balancing is checked + to the same precision (number of decimal places) used in the conver- + sion posting's amount. Equity conversion accounts are: + + o any accounts declared with account type V/Conversion, or their sub- + accounts + + o otherwise, accounts named equity:conversion, equity:trade, or eq- + uity:trading, or their subaccounts. + + And multiple such four-posting groups can coexist within a single + transaction. When --infer-costs fails, it does not infer a cost in + that transaction, and does not raise an error (ie, it infers costs + where it can). + + Reading variant 5 journal entries, combining cost notation and equity + postings, has all the same requirements. When reading such an entry + fails, hledger raises an "unbalanced transaction" error. + + Infer cost and equity by default ? + Should --infer-costs and --infer-equity be enabled by default ? Try + using them always, eg with a shell alias: + + alias h="hledger --infer-equity --infer-costs" + + and let us know what problems you find. + +Value reporting + 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] op- + tion, 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 + Market prices can change from day to day. hledger will use the prices + on a particular valuation date (or on more than one date). By default + hledger uses "end" dates for valuation. More specifically: + + o For single period reports (including normal print and register re- + ports): + + o If an explicit report end date is specified, that is used + + o Otherwise the latest transaction date or P directive date is used + (even if it's in the future) + + o For multiperiod reports, each period is valued on its last day. + + This can be customised with the --value option described below, which + can select either "then", "end", "now", or "custom" dates. (Note, this + has a bug in hledger-ui <=1.31: turning on valuation with the V key al- + ways resets it to "end".) + + Finding market price + To convert a commodity A to its market value in another commodity B, + hledger looks for a suitable market price (exchange rate) as follows, + in this order of preference: + + 1. A declared market price or inferred market price: A's latest market + price in B on or before the valuation date as declared by a P direc- + tive, or (with the --infer-market-prices flag) inferred from costs. + + 2. A reverse market price: the inverse of a declared or inferred market + price from B to A. + + 3. A forward chain of market prices: a synthetic price formed by 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 costs as additional market prices (as + Ledger does) ? Adding the --infer-market-prices flag to -V, -X or + --value enables this. + + So for example, hledger bs -V --infer-market-prices will get market + prices both from P directives and from transactions. If both occur on + the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in confus- + ing/undesired ways by your journal entries. If this happens to you, + read all of this Value reporting 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 multicommodity transactions with equity postings, if cost is inferred + with --infer-costs. + + There is a limitation (bug) currently: when a valuation commodity is + not specified, prices inferred with --infer-market-prices do not help + select a default valuation commodity, as P prices would. So conversion + might not happen because no valuation commodity was detected (--debug=2 + will show this). To be safe, specify the valuation commmodity, eg: + + 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 + + Signed costs and market prices can be confusing. For reference, here + is the current behaviour, since hledger 1.25. (If you think it should + work differently, see #1870.) + + 2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + + 2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + + 2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + + 2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + + 2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + + 2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each day, + the two transactions are considered equivalent). Here are the market + prices inferred for B: + + $ hledger -f- --infer-market-prices prices + P 2022-01-01 B A 1 + P 2022-01-01 B A 1.0 + P 2022-01-02 B A -1 + P 2022-01-02 B A -1.0 + P 2022-01-03 B A -1 + P 2022-01-03 B A -1.0 + + 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, + costs 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 $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 + + --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 + + 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. Re- + lated: #329, #1083. + + Report -B, --cost -V, -X --value=then --value=end --value=DATE, + type --value=now + -------------------------------------------------------------------------------------------- + print + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today + today journal end + balance unchanged unchanged unchanged unchanged unchanged + asser- + tions/as- + signments + + register + starting cost value at re- valued at day value at re- value at + balance port or each historical port or DATE/today + (-H) journal end posting was made journal end + starting cost value at day valued at day value at day value at + balance before re- each historical before re- DATE/today + (-H) with port or posting was made port or + report journal journal + interval start start + posting cost value at re- value at posting value at re- value at + amounts port or date port or DATE/today + journal end journal end + summary summarised value at pe- sum of postings value at pe- value at + posting cost riod ends in interval, val- riod ends DATE/today + amounts ued at interval + with re- start + port in- + terval + running sum/average sum/average sum/average of sum/average sum/average + total/av- of displayed of displayed displayed values of displayed of displayed + erage values values values values + + balance + (bs, bse, + cf, is) + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of + 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 + (--bud- + get) + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + tal played val- played val- valued played val- played values + ues ues ues + + balance + (bs, bse, + cf, is) + with re- + port in- + terval + starting sums of value at re- sums of values of value at re- sums of post- + balances costs of port start postings before port start ings before + (-H) postings be- of sums of report start at of sums of report start + fore report all postings respective post- all postings + start before re- ing dates before re- + port start port start + balance sums of same as sums of values of balance value at + changes costs of --value=end postings in pe- change in DATE/today of + (bal, is, postings in riod at respec- each period, sums of post- + bs period tive posting valued at ings + --change, dates period ends + cf + --change) + end bal- sums of same as sums of values of period end value at + ances costs of --value=end postings from be- balances, DATE/today of + (bal -H, postings fore period start valued at sums of post- + is --H, from before to period end at period ends ings + bs, cf) report start respective post- + to period ing dates + end + budget like balance like balance like balance like bal- like balance + amounts changes/end changes/end changes/end bal- ances changes/end + (--bud- balances balances ances balances + get) + row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + averages played val- played val- played val- played values + (-T, -A) ues ues ues + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + totals played val- played val- values played val- played values + ues ues ues + grand to- sum, average sum, average sum, average of sum, average sum, average + tal, of column of column column totals of column of column to- + grand av- totals totals totals tals + erage + + + --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). + +PART 4: COMMANDS + Commands overview + Here are the built-in commands: + + DATA ENTRY + These data entry commands are the only ones which can modify your jour- + nal file. + + o add - add transactions using terminal prompts + + o import - add new transactions from other files, eg CSV files + + DATA CREATION + o close - generate balance-zeroing/restoring transactions + + o rewrite - generate auto postings, like print --auto + + DATA MANAGEMENT + o check - check for various kinds of error in the data + + o diff - compare account transactions in two journal files + + REPORTS, FINANCIAL + 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 + + REPORTS, VERSATILE + o balance (bal) - show balance changes, end balances, budgets, gains.. + + o print - show transactions or export journal data + + o register (reg) - show postings in one or more accounts & running to- + tal + + o roi - show return on investments + + REPORTS, BASIC + o accounts - show account names + + o activity - show bar charts of posting counts per period + + o codes - show transaction codes + + o commodities - show commodity/currency symbols + + o descriptions - show transaction descriptions + + o files - show input file paths + + o notes - show note parts of transaction descriptions + + o payees - show payee parts of transaction descriptions + + o prices - show market prices + + o stats - show journal statistics + + o tags - show tag names + + o test - run self tests + + HELP + o help - show the hledger manual with info/man/pager + + o demo - show small hledger demos in the terminal + + ADD-ONS + And here are some typical add-on commands. Some of these are installed + by the hledger-install script. If installed, they will appear in + hledger's commands list: + + o ui - run hledger's terminal UI + + o web - run hledger's web UI + + o iadd - add transactions using a TUI (currently hard to build) + + o interest - generate interest transactions + + o stockquotes - download market prices from AlphaVantage + + o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move, + pijul, plot, and more.. + + Next, each command is described in detail, in alphabetical order. + + accounts + Show account names. + + This command lists account names. By default it shows all known ac- + counts, either used in transactions or declared with account direc- + tives. + + With query arguments, only matched account names and account names ref- + erenced by matched postings are shown. + + Or it can show just the used accounts (--used/-u), the declared ac- + counts (--declared/-d), the accounts declared but not used (--unused), + the accounts used but not declared (--undeclared), or the first account + matched by an account name pattern, if any (--find). + + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. In flat mode you can add --drop N to omit + the first few account name components. Account names can be depth- + clipped with depth:N or --depth N or -N. + + With --types, it also shows each account's type, if it's known. (See + Declaring accounts > Account types.) + + With --positions, it also shows the file and line number of each ac- + count's declaration, if any, and the account's overall declaration or- + der; these may be useful when troubleshooting account display order. + + With --directives, it adds the account keyword, showing valid account + directives which can be pasted into a journal file. This is useful to- + gether with --undeclared when updating your account declarations to + satisfy hledger check accounts. + + The --find flag can be used to look up a single account name, in the + same way that the aregister command does. It returns the alphanumeri- + cally-first matched account name, or if none can be found, it fails + with a non-zero exit code. + + Examples: + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + $ hledger accounts --undeclared --directives >> $LEDGER_FILE + $ hledger check accounts + + 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 + 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 de- + scription) 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, pay- + ees/descriptions, 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 https://hledger.org/add.html for a detailed tutorial): + + $ hledger add + Adding transactions to journal file /src/hledger/examples/sample.journal + Any command line arguments will be used as defaults. + Use tab key to complete, readline keys to edit, enter to accept defaults. + An optional (CODE) may follow transaction dates. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to go one step backward. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2015/05/22]: + Description: supermarket + Account 1: expenses:food + Amount 1: $10 + Account 2: assets:checking + Amount 2 [$-10.0]: + Account 3 (or . or enter to finish this transaction): . + 2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2015/05/22]: $ + + On Microsoft Windows, the add command makes sure that no part of the + file path ends with a period, as that would cause problems (#1056). + + aregister + (areg) + + Show the transactions and running historical balance of a single ac- + count, 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 in- + cluded 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 ex- + pression which will select the alphabetically first matched account. + + When there are multiple matches, the alphabetically-first choice can be + surprising; eg if you have assets:per:checking 1 and assets:biz:check- + ing 2 accounts, hledger areg checking would select assets:biz:checking + 2. It's just a convenience to save typing, so if in doubt, write the + full account name, or a distinctive substring that matches uniquely. + + Transactions involving subaccounts of this account will also be shown. + aregister ignores depth limits, so its final total will always match a + balance report with similar arguments. + + Any additional arguments form a query which will filter the 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 op- + tions. The output formats supported are txt, csv, tsv, and json. + + aregister and posting dates + aregister always shows one line (and date and amount) per transaction. + But sometimes transactions have postings with different dates. Also, + not all of a transaction's postings may be within the report period. + To resolve this, aregister shows the earliest of the transaction's date + and posting dates that is in-period, and the sum of the in-period post- + ings. In other words it will show a combined line item with just the + earliest date, and the running balance will (temporarily, until the + transaction's last posting) be inaccurate. Use register -H if you need + to see the individual postings. + + There is also a --txn-dates flag, which filters strictly by transaction + date, ignoring posting dates. This too can cause an inaccurate running + 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) + + o or postings count (--count) + + ..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 (--in- + vert) + + 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, tsv, 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. ("Simple" here + means just one column of numbers, covering a single period. You can + also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end bal- + ance 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 (re- + vealing 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. + + Balance report line format + For single-period balance reports displayed in the terminal (only), you + can use --format FMT to customise the format and content of each line. + Eg: + + $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 + --------------------------------- + 0 + + The FMT format string specifies the formatting applied to each ac- + count/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 ef- + fect, 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 + + 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 + + Showing declared accounts + With --declared, accounts which have been declared with an account di- + rective 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 re- + port, even when you don't have transactions in all of your declared ac- + counts yet. + + 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 + biggest averaged monthly expenses first. When more than one commodity + is present, they will be sorted by the alphabetically earliest commod- + ity 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 --in- + vert 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. + + 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: + + 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 + + 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 ac- + count 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 + The balance command is quite flexible; here is the full detail on how + to control what it reports. If the following seems complicated, don't + worry - this is for advanced reporting, and it does take time and ex- + perimentation to get familiar with all the report modes. + + There are three important option groups: + + hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] + ... + + Calculation type + The basic calculation to perform for each table cell. It is one of: + + o --sum : sum the posting amounts (default) + + o --budget : sum the amounts, but also show the budget goal amount (for + each account/period) + + 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) + + o --count : show the count of postings + + Accumulation type + How amounts should accumulate across report periods. Another way to + say it: which time period's postings should contribute to each cell's + calculation. It is one of: + + o --change : calculate with postings from column start to column end, + ie "just this column". Typically used to see revenues/expenses. + (default for balance, incomestatement) + + o --cumulative : calculate with postings from report start to column + end, ie "previous columns plus this column". Typically used to show + changes accumulated since the report's start date. Not often used. + + o --historical/-H : calculate with postings from journal start to col- + umn end, ie "all postings from before report start date until this + column's end". Typically used to see historical end balances of as- + sets/liabilities/equity. (default for balancesheet, balancesheete- + quity, cashflow) + + Valuation type + Which kind of value or cost conversion should be applied, if any, be- + fore displaying the report. It is one of: + + o no valuation type : don't convert to cost or value (default) + + o --value=cost[,COMM] : convert amounts to cost (then optionally to + some other commodity) + + o --value=then[,COMM] : convert amounts to market value on transaction + dates + + o --value=end[,COMM] : convert amounts to market value on period end + date(s) + (default with --valuechange, --gain) + + o --value=now[,COMM] : convert amounts to market value on today's date + + o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- + other date + + or one of the equivalent simpler flags: + + o -B/--cost : like --value=cost (though, note --cost and --value are + independent options which can both be used at once) + + o -V/--market : like --value=end + + o -X COMM/--exchange COMM : like --value=end,COMM + + See Cost reporting and Value reporting for more about these. + + Combining balance report types + Most combinations of these options should produce reasonable reports, + but if you find any that seem wrong or misleading, let us know. The + following restrictions are applied: + + 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 pe- + ues in period in period riod + --cumu- change from re- sum of posting- period-end DATE-value of + lative port 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 + + Budget report + The --budget report type activates extra columns showing any budget + goals for each account and period. The budget goals are defined by pe- + riodic transactions. This is useful for comparing planned and actual + income, expenses, time usage, etc. + + For example, you can take average monthly expenses in the common ex- + pense 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. Cur- + rently: + + o Accounts with budget goals during the report period, and their par- + ents, are shown. + + o Their subaccounts are not shown (regardless of the depth setting). + + o Accounts without budget goals, if any, are aggregated and shown as + "". + + o Amounts are always inclusive (subaccount-including), even in list + mode. + + o After each actual amount, the corresponding goal amount and percent- + age of goal reached are also shown, in square brackets. + + This means that the numbers displayed will not always add up! Eg + above, the expenses actual amount includes the gifts and supplies + transactions, but the expenses:gifts and expenses:supplies accounts are + not shown, as they have no budget amounts declared. + + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted + ones, giving the full picture. Eg: + + $ hledger balance -M --budget --empty + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + You can roll over unspent budgets to next period with --cumulative: + + $ hledger balance -M --budget --cumulative + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] + + It's common to limit budgets/budget reports to just expenses + + hledger bal -M --budget expenses + + or just revenues and expenses (eg, using account types): + + hledger bal -M --budget type:rx + + It's also common to limit or convert them to a single currency + (cur:COMM or -X COMM [--infer-market-prices]). If showing multiple + currencies, --layout bare or --layout tall can help. + + For more examples and notes, see Budgeting. + + 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 to- + wards 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: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 ac- + count in each report subperiod. When troubleshooting, you can use + print --forecast to show these as forecasted transactions: + + $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated + + By default, the budget report uses all available periodic transaction + rules to generate goals. This includes rules with a different report + interval from your report. Eg if you have daily, weekly and monthly + periodic rules, all of these will contribute to the goals in a monthly + budget report. + + You can select a subset of periodic rules by providing an argument to + the --budget flag. --budget=DESCPAT will match all periodic rules + whose description contains DESCPAT, a case-insensitive substring (not a + regular expression or query). This means you can give your periodic + rules descriptions (remember that two spaces are needed), and then se- + lect from multiple budgets defined in your journal. + + Budget vs forecast + hledger --forecast ... and hledger balance --budget ... are separate + features, though both of them use the periodic transaction rules de- + fined in the journal, and both of them generate temporary transactions + for reporting purposes ("forecast transactions" and "budget goal trans- + actions", respectively). You can use both features at the same time if + you want. Here are some differences between them, as of hledger 1.29: + + CLI: + + o --forecast is a general hledger option, usable with any command + + o --budget is a balance command option, usable only with that command. + + Visibility of generated transactions: + + o forecast transactions are visible in any report, like ordinary trans- + actions + + o budget goal transactions are invisible except for the goal amounts + they produce in --budget reports. + + Periodic transaction rules: + + o --forecast uses all available periodic transaction rules + + o --budget uses all periodic rules (--budget) or a selected subset + (--budget=DESCPAT) + + Period of generated transactions: + + o --forecast generates forecast transactions + + o from after the last regular transaction to the end of the report + period (--forecast) + + o or, during a specified period (--forecast=PERIODEXPR) + + o possibly further restricted by a period specified in the periodic + transaction rule + + o and always restricted within the bounds of the report period + + o --budget generates budget goal transactions + + o throughout the report period + + o possibly restricted by a period specified in the periodic transac- + tion rule. + + Balance report layout + The --layout option affects how balance reports show multi-commodity + amounts and commodity symbols, which can improve readability. It can + also normalise the data for easy consumption by other programs. It has + four possible values: + + o --layout=wide[,WIDTH]: commodities are shown on a single line, op- + tionally elided to WIDTH + + o --layout=tall: each commodity is shown on a separate line + + o --layout=bare: commodity symbols are in their own column, amounts are + bare numbers + + o --layout=tidy: data is normalised to easily-consumed "tidy" form, + with one row per data value + + Here are the --layout modes supported by each output format; note only + CSV output supports all of them: + + - txt csv html json sql + ------------------------------------- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y + + Examples: + + 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 for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + + o Note: bare layout will sometimes display an extra row for the no-sym- + bol commodity, because of zero amounts (hledger treats zeroes as com- + modity-less, usually). This can break hledger-bar confusingly + (workaround: add a cur: query to exclude the no-symbol row). + + o Tidy layout produces normalised "tidy data", where every variable has + its own column and each row represents a single data point. See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- + data.html for more. This is the easiest kind of data for other soft- + ware to consume. Here's how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + 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 + + 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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + 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 in- + sensitive, 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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + 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 al- + lowed) + + o whose name contains some variation of cash, bank, checking or saving. + + More precisely: all accounts matching this case insensitive regular ex- + pression: + + ^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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + check + Check for various kinds of errors in your data. + + hledger provides a number of built-in error checks to help prevent + problems in your data. Some of these are run automatically; or, you + can use this check command to run them on demand, with no output and a + zero exit code if all is well. Specify their names (or a prefix) as + argument(s). + + Some examples: + + hledger check # basic checks + hledger check -s # basic + strict checks + hledger check ordereddates payees # basic + two other checks + + If you are an Emacs user, you can also configure flycheck-hledger to + run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available: + + Default checks + These checks are run automatically by (almost) all hledger commands: + + o parseable - data files are in a supported format, with no syntax er- + rors and no invalid include directives. + + o autobalanced - all transactions are balanced, after converting to + cost. Missing amounts and missing costs are inferred automatically + where possible. + + 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 balanced - all transactions are balanced after converting to cost, + without inferring missing costs. If conversion costs are required, + they must be explicit. + + o accounts - all account names used by transactions have been declared + + o commodities - all commodity symbols used have been declared + + 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: + + o ordereddates - transactions are ordered by date within each file + + o payees - all payees used by transactions have been declared + + o recentassertions - all accounts with balance assertions have a bal- + ance assertion within 7 days of their latest posting + + o tags - all tags 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. + + More about specific checks + hledger check recentassertions will complain if any balance-asserted + account has postings more than 7 days after its latest balance asser- + tion. This aims to prevent the situation where you are regularly up- + dating your journal, but forgetting to check your balances against the + real world, then one day must dig back through months of data to find + an error. It assumes that adding a balance assertion requires/reminds + you to check the real-world balance. (That may not be true if you + auto-generate balance assertions from bank data; in that case, I recom- + mend to import transactions uncleared, and when you manually review and + clear them, also check the latest assertion against the real-world bal- + ance.) + + close + (equity) + + Generate transactions which transfer account balances to and/or from + another account (typically equity). This can be useful for migrating + balances to a new journal file, or for merging earnings into equity at + end of accounting period. + + By default, it prints a transaction that zeroes out ALE accounts (as- + set, liability, equity accounts; this requires account types to be con- + figured); or if ACCTQUERY is provided, the accounts matched by that. + + (experimental) + + This command has four main modes, corresponding to the most common use + cases: + + 1. With --close (default), it prints a "closing balances" transaction + that zeroes out ALE (asset, liability, equity) accounts by default + (this requires account types to be inferred or declared); or, the + accounts matched by the provided ACCTQUERY arguments. + + 2. With --open, it prints an opposite "opening balances" transaction + that restores those balances from zero. This is similar to Ledger's + equity command. + + 3. With --migrate, it prints both the closing and opening transactions. + This is the preferred way to migrate balances to a new file: run + hledger close --migrate, add the closing transaction at the end of + the old file, and add the opening transaction at the start of the + new file. The matching closing/opening transactions cancel each + other out, preserving correct balances during multi-file reporting. + + 4. With --retain, it prints a "retain earnings" transaction that trans- + fers RX (revenue and expense) balances to equity:retained earnings. + Businesses traditionally do this at the end of each accounting pe- + riod; it is less necessary with computer-based accounting, but it + could still be useful if you want to see the accounting equation + (A=L+E) satisfied. + + In all modes, the defaults can be overridden: + + o the transaction descriptions can be changed with --close-desc=DESC + and --open-desc=DESC + + o the account to transfer to/from can be changed with --close-acct=ACCT + and --open-acct=ACCT + + o the accounts to be closed/opened can be changed with ACCTQUERY (ac- + count query arguments). + + o the closing/opening dates can be changed with -e DATE (a report end + date) + + By default just one destination/source posting will be used, with its + amount left implicit. With --x/--explicit, the amount will be shown + explicitly, and if it involves multiple commodities, a separate posting + will be generated for each of them (similar to print -x). + + With --show-costs, any amount costs are shown, with separate postings + for each cost. This is currently the best way to view investment lots. + If you have many currency conversion or investment transactions, it can + generate very large journal entries. + + With --interleaved, each individual transfer is shown with source and + destination postings next to each other. This could be useful for + troubleshooting. + + The default closing date is yesterday, or the journal's end date, + whichever is later. You can change this by specifying a report end + date with -e. The last day of the report period will be the closing + date, eg -e 2024 means "close on 2023-12-31". The opening date is al- + ways the day after the closing date. + + close and balance assertions + Balance assertions will be generated, verifying that the accounts have + been reset to zero (and then restored to their previous balances, if + there is an opening transaction). + + These provide useful error checking, but you can ignore them temporar- + ily with -I, or remove them if you prefer. + + You probably should avoid filtering transactions by status or realness + (-C, -R, status:), or generating postings (--auto), with this command, + since the balance assertions would depend on these. + + Note custom posting dates spanning the file boundary will disrupt the + balance assertions: + + 2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve that you can transfer the money to and from a temporary ac- + count, in effect splitting the multi-day transaction into two single- + day transactions: + + ; in 2022.journal: + 2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + + ; in 2023.journal: + 2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + Example: retain earnings + Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- + pending the generated transaction to the journal: + + $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + Note 2022's income statement will now show only zeroes, because rev- + enues and expenses have been moved entirely to equity. To see them + again, you could exclude the retain transaction: + + $ hledger -f 2022.journal is not:desc:'retain earnings' + + Example: migrate balances to a new file + Close assets/liabilities/equity on 2022-12-31 and re-open them on + 2023-01-01: + + $ hledger close --migrate -f 2022.journal -p 2022 + # copy/paste the closing transaction to the end of 2022.journal + # copy/paste the opening transaction to the start of 2023.journal + + Now 2022's balance sheet will show only zeroes, indicating a balanced + accounting equation. (Unless you are using @/@@ notation - in that + case, try adding --infer-equity.) To see the end-of-year balances + again, you could exclude the closing transaction: + + $ hledger -f 2022.journal bs not:desc:'closing balances' + + Example: excluding closing/opening transactions + When combining many files for multi-year reports, the closing/opening + transactions cause some noise in transaction-oriented reports like + print and register. You can exclude them as shown above, but + not:desc:... is not ideal as it depends on consistent descriptions; + also you will want to avoid excluding the very first opening transac- + tion, which could be awkward. Here is one alternative, using tags: + + Add clopen: tags to all opening/closing balances transactions except + the first, like this: + + ; 2021.journal + 2021-06-01 first opening balances + ... + 2021-12-31 closing balances ; clopen:2022 + ... + + ; 2022.journal + 2022-01-01 opening balances ; clopen:2022 + ... + 2022-12-31 closing balances ; clopen:2023 + ... + + ; 2023.journal + 2023-01-01 opening balances ; clopen:2023 + ... + + Now, assuming a combined journal like: + + ; all.journal + include 2021.journal + include 2022.journal + include 2023.journal + + The clopen: tag can exclude all but the first opening transaction. To + show a clean multi-year checking register: + + $ hledger -f all.journal areg checking not:tag:clopen + + And the year values allow more precision. To show 2022's year-end bal- + ance sheet: + + $ hledger -f all.journal bs -e2023 not:tag:clopen=2023 + + codes + List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often + used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty codes + will not be shown by default. With the -E/--empty flag, they will be + printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + + 2022/1/1 (123) Supermarket + Food $5.00 + Checking + + 2022/1/2 (124) Post Office + Postage $8.32 + Checking + + 2022/1/3 Supermarket + Food $11.23 + Checking + + 2022/1/4 (126) Post Office + Postage $3.21 + Checking + + $ hledger codes + 123 + 124 + 126 + + $ hledger codes -E + 123 + 124 + + 126 + + commodities + List all commodity/currency symbols used or declared in the journal. + + demo + Play demos of hledger usage in the terminal, if asciinema is installed. + + Run this command with no argument to list the demos. To play a demo, + write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/--speed SPEED option to set your preferred playback speed, + eg -s4 to play at 4x original speed or -s.5 to play at half speed. The + default speed is 2x. + + Other asciinema options can be added following a double dash, eg -- + -i.1 to limit pauses or -- -h to list asciinema's other options. + + During playback, several keys are available: SPACE to pause/unpause, . + to step forward (while paused), CTRL-c quit. + + Examples: + + $ hledger demo # list available demos + $ hledger demo 1 # play the first demo at default speed (2x) + $ hledger demo install -s4 # play the "install" demo at 4x speed + + 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 + 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 + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + help + Show the hledger user manual in the terminal, with info, man, or a + pager. With a TOPIC argument, open it at that topic if possible. + TOPIC can be any heading in the manual, or a heading prefix, case in- + sensitive. Eg: commands, print, forecast, journal, amount, "auto post- + ings". + + This command shows the hledger manual built in to your hledger version. + It can be useful when offline, or when you prefer the terminal to a web + browser, or when the appropriate hledger manual or viewing tools are + not installed on your system. + + By default it chooses the best viewer found in $PATH, trying (in this + order): info, man, $PAGER, less, more. You can force the use of info, + man, or a pager with the -i, -m, or -p flags, If no viewer can be + found, or the command is run non-interactively, it just prints the man- + ual to stdout. + + If using info, note that version 6 or greater is needed for TOPIC + lookup. If you are on mac you will likely have info 4.8, and should + consider installing a newer version, eg with brew install texinfo + (#1770). + + Examples + + $ hledger help --help # show how the help command works + $ hledger help # show the hledger manual with info, man or $PAGER + $ hledger help journal # show the journal topic in the hledger manual + $ hledger help -m journal # show it with man, even if info is installed + + import + Read new transactions added to each FILE provided as arguments 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' current transactions as imported, without importing them. + + 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 + import does time-based deduplication, to detect only the new transac- + tions since the last successful import. (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 periodi- + cally importing downloaded data, which may overlap with previous down- + loads. Eg if every week (or every day) you download a bank's last + three months of CSV data, you can safely run hledger import thebank.csv + each time and only new transactions will be imported. + + 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.FILE" file in FILE's directory (after a succesful + import). + + Eg when reading finance/bank.csv, it will look for and update the fi- + nance/.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 cer- + tain date. + + Note deduplication (and updating of state files) can also be done by + print --new, but this is less often used. + + Related: CSV > Working with CSV > Deduplicating, importing. + + Import testing + With --dry-run, the transactions that will be imported are printed to + the terminal, without updating your journal or state files. The output + is valid journal format, like the print command, so you can re-parse + it. Eg, to see any importable transactions which CSV rules have not + categorised: + + $ hledger import --dry bank.csv | hledger -f- -I print unknown + + or (live updating): + + $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' + + Note: when importing from multiple files at once, it's currently possi- + ble for some .latest files to be updated successfully, while the actual + import fails because of a problem in one of the files, leaving them out + of sync (and causing some transactions to be missed). To prevent this, + do a --dry-run first and fix any problems before the real import. + + 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 + (is) + + This command displays an income statement, showing revenues and ex- + penses during one or more periods. Amounts are shown with normal posi- + tive 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 op- + tions The output formats supported are txt, csv, tsv, html, and (exper- + imental) json. + + notes + List the unique notes that appear in transactions. + + This command lists the unique notes that appear in transactions, in al- + phabetic 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 + 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 + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With + --show-reverse, also show additional prices inferred by reversing known + prices. + + Price amounts are always displayed with their full precision, except + for reverse prices which are limited to 8 decimal digits. + + Prices can be filtered by a date:, cur: or amt: query. + + Generally if you run this command with --infer-market-prices --show-re- + verse, it will show the same prices used internally to calculate value + reports. But if in doubt, you can inspect those directly by running + the value report with --debug=2. + + 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). + + 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/regenerate your journal you should take care to also copy + over the directives and inter-transaction comments. + + Eg: + + $ hledger print -f examples/sample.journal date:200806 + 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 + + print explicitness + Normally, whether posting amounts are implicit or explicit is pre- + served. For example, when an amount is omitted in the journal, it will + not appear in the output. Similarly, if a conversion cost is implied + but not written, it will not appear in the output. + + You can use the -x/--explicit flag to force explicit display of all + amounts and costs. This can be useful for troubleshooting or for mak- + ing your journal more readable and robust against data entry errors. + -x is also implied by using any of -B,-V,-X,--value. + + The -x/--explicit flag will cause any postings with a multi-commodity + amount (which can arise when a multi-commodity transaction has an im- + plicit amount) to be split into multiple single-commodity postings, + keeping the output parseable. + + print amount style + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can do that with ledger-mode in + Emacs). + + Amounts will be (mostly) normalised to their commodity display style: + their symbol placement, decimal mark, and digit group marks will be + made consistent. By default, decimal digits are shown as they are + written in the journal. + + With the --round option, print will try increasingly hard to display + decimal digits according to the commodity display styles: + + o --round=none show amounts with original precisions (default) + + o --round=soft add/remove decimal zeros in amounts (except costs) + + o --round=hard round amounts (except costs), possibly hiding signifi- + cant digits + + o --round=all round all amounts and costs + + soft is good for non-lossy cleanup, formatting amounts more consis- + tently where it's safe to do so. + + hard and all can cause print to show invalid unbalanced journal en- + tries; they may be useful eg for stronger cleanup, with manual fixups + when needed. + + print parseability + 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 (though the same can be achieved with expr: queries + now): + + # 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 Value reporting affects posting amounts but not balance assertion or + balance 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. + + print, other features + With -B/--cost, amounts with costs are shown converted to cost. + + With --new, print shows 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.) + + With -m DESC/--match=DESC, print shows one recent transaction whose de- + scription is most similar to DESC. DESC should contain at least two + characters. If there is no similar-enough match, no transaction will + be shown and the program exit code will be non-zero. + + print output format + This command also supports the output destination and output format op- + tions The output formats supported are txt, beancount, csv, tsv, json + and sql. + + Experimental: The beancount format tries to produce Beancount-compati- + ble output, as follows: + + o Transaction and postings with unmarked status are converted to + cleared (*) status. + + o Transactions' payee and note are backslash-escaped and double-quote- + escaped and wrapped in double quotes. + + o Transaction tags are copied to Beancount #tag format. + + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency + names. + + o Account name parts are capitalised and unsupported characters are re- + placed with -. If an account name part does not begin with a letter, + or if the first part is not Assets, Liabilities, Equity, Income, or + Expenses, an error is raised. (Use --alias options to bring your ac- + counts into compliance.) + + o An open directive is generated for each account used, on the earliest + transaction date. + + Some limitations: + + o Balance assertions are removed. + + o Balance assignments become missing amounts. + + o Virtual and balanced virtual postings become regular postings. + + o Directives are not converted. + + 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.) + + 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 ac- + count 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 to- + gether with the related account: + + $ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per in- + terval, 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 op- + tion 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 in- + tervals. This ensures that the first and last intervals are full + length and comparable to the others in the report. + + With -m DESC/--match=DESC, register does a fuzzy search for one recent + posting whose description is most similar to DESC. DESC should contain + at least two characters. If there is no similar-enough match, no post- + ing will be shown and the program exit code will be non-zero. + + 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 de- + scription 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 op- + tions The output formats supported are txt, csv, tsv, and (experimen- + tal) json. + + 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 in- + cludes a commodity name, the new posting amount will be in the new com- + modity; otherwise, it will be in the matched posting amount's commod- + ity. + + 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 + 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 ac- + count 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, also known as money-weighted rate of return) and time-weighted + rate of return (TWR) for your investments for the time period re- + quested. IRR is always annualized due to the way it is computed, but + TWR is reported both as a rate over the chosen reporting period and as + an annual rate. + + 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 be- + comes 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 as- + sets, 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 re- + turn. + + 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, and the + time between them. Investment at a particular fixed interest rate is + going to give you more interest than the same amount invested at the + same interest rate, but made later in time. 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, + so your IRR will be smaller. And if you are adding to your investment, + you will receive bigger absolute gains, which will be a bigger percent- + age of your initial investment, so your IRR will be larger. + + 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 ac- + count for the effect of your in-flows and out-flows, but unlike IRR it + will try to compute the true rate of return of the underlying asset, + compensating for the effect that deposits and withdrawas have on the + apparent rate of growth of your investment. + + 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, and make TWR less sensitive than IRR to the effects of + cash in-flows and out-flows. + + References: + + o Explanation of rate of return + + o Explanation of IRR + + o Explanation of TWR + + o IRR vs TWR + + o Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + stats + Show journal and performance statistics. + + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report + for each report period. + + At the end, it shows (in the terminal) the overall run time and number + of transactions processed per second. Note these are approximate and + will vary based on machine, current load, data size, hledger version, + haskell lib versions, GHC version.. but they may be of interest. The + stats command's run time is similar to that of a single-column balance + report. + + Example: + + $ hledger stats -f examples/1000x1000x10.journal + Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal + Included files : + Transactions span : 2000-01-01 to 2002-09-27 (1000 days) + Last transaction : 2002-09-26 (6995 days ago) + Transactions : 1000 (1.0 per day) + Transactions last 30 days: 0 (0.0 per day) + Transactions last 7 days : 0 (0.0 per day) + Payees/descriptions : 1000 + Accounts : 1000 (depth 10) + Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) + Market prices : 1000 (A) + + Run time : 0.12 s + Throughput : 8342 txns/s + + This command supports the -o/--output-file option (but not -O/--output- + format selection). + + 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 + 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). + +PART 5: COMMON TASKS + Here are some quick examples of how to do some basic tasks with + hledger. + + Getting help + Here's how to list commands and view options and command docs: + + $ hledger # show available commands + $ hledger --help # show common options + $ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version's manual in several formats by + using the help command. Eg: + + $ hledger help # show the hledger manual with info, man or $PAGER (best available) + $ hledger help journal # show the journal topic in the hledger manual + $ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit + https://hledger.org. Chat and mail list support and discussion + archives can be found at https://hledger.org/support. + + Constructing command lines + hledger has a flexible command line interface. We strive to keep it + simple and ergonomic, but if you run into one of the sharp edges de- + scribed in OPTIONS, here are some tips that might help: + + o command-specific options must go after the command (it's fine to put + common options there too: 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 line 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 + (see below). 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 2023.journal + $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile + $ source ~/.profile + $ hledger stats + Main file : /Users/simon/finance/2023.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 LEDGER_FILE + How to set LEDGER_FILE permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for + many people; adapt as needed: + + $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile + $ source ~/.profile + + When correctly configured, in a new terminal window env | grep + LEDGER_FILE will show your file, and so will hledger files. + + On mac, this additional step might be helpful for GUI applications + (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- + ment.plist like + + { + "LEDGER_FILE" : "~/finance/2023.journal" + } + + and then run killall Dock in a terminal window (or restart the ma- + chine). + + On Windows, see https://www.java.com/en/download/help/path.html, or try + running these commands in a powershell window (let us know if it per- + sists across a reboot, and if you need to be an Administrator): + + > CD + > MKDIR finance + > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + 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 re- + cent starting date, like today or the start of the week. You can al- + ways 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: + + 2023-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/2023.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 [2023-02-07]: 2023-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): . + 2023-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 [2023-01-01]: . + + If you're using version control, this could be a good time to commit + the journal. Eg: + + $ git commit -m 'initial balances' 2023.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: + + 2023/1/10 * gift received + assets:cash $20 + income:gifts + + 2023.1.12 * farmers market + expenses:food $13 + assets:cash + + 2023-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 al- + ready-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: + + 2023-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 re- + ported by hledger reg checking -C. This will be easier if you gen- + erally record transaction dates quite similar to your bank's clear- + ing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a live-up- + dating register while you edit the journal: hledger-ui --watch --regis- + ter 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 2023-01-15 and paycheck + + If you're using version control, this can be another good time to com- + mit: + + $ git commit -m 'txns' 2023.journal + + Reporting + Here are some basic reports. + + Show all transactions: + + $ hledger print + 2023-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + + 2023-01-10 * gift received + assets:cash $20 + income:gifts + + 2023-01-12 * farmers market + expenses:food $13 + assets:cash + + 2023-01-15 * paycheck + income:salary + assets:bank:checking $1000 + + 2023-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + + $ hledger accounts --tree + assets + bank + checking + savings + cash + equity + opening/closing balances + expenses + food + misc + income + gifts + salary + liabilities + creditcard + + Show all account totals: + + $ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard + -------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to + depth 2: + + $ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard + -------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple + balance sheet: + + $ hledger bs -2 + Balance Sheet 2023-01-16 + + || 2023-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 2023-01-01-2023-01-16 + + || 2023-01-01-2023-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 + 2023-01-01 opening balances assets:cash $100 $100 + 2023-01-10 gift received assets:cash $20 $120 + 2023-01-12 farmers market assets:cash $-13 $107 + 2023-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + + $ hledger activity -W + 2019-12-30 ***** + 2023-01-06 **** + 2023-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. + +BUGS + We welcome bug reports in the hledger issue tracker (shortcut: + http://bugs.hledger.org), or on the #hledger chat or hledger mail list + (https://hledger.org/support). + + Some known issues and limitations: + + The need to precede add-on command options with -- when invoked from + hledger is awkward. (See Command options, Constructing command lines.) + + A UTF-8-aware system locale must be configured to work with non-ascii + data. (See Unicode characters, Troubleshooting.) + + On Microsoft Windows, depending whether you are running in a CMD window + or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii + characters and colours may not be supported, and the tab key may not be + supported by hledger add. (Running in a WSL window should resolve + these.) + + When processing large data files, hledger uses more memory than Ledger. + + Troubleshooting + Here are some common issues you might encounter when you run hledger, + and how to resolve them (and remember also you can usually get quick + Support): + + PATH issues: I get an error like "No command 'hledger' found" + Depending how you installed hledger, the executables may not be in your + shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- + cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one + of these directories to your shell's PATH, and/or open a new terminal + window. + + LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using + it + o LEDGER_FILE should be a real environment variable, not just a shell + variable. Eg on unix, the command env | grep LEDGER_FILE should show + it. You may need to use export (see https://stackover- + flow.com/a/7411509). + + o You may need to force your shell to see the new configuration. A + simple way is to close your terminal window and open a new one. + + LANG issues: I get errors like "Illegal byte sequence" or "Invalid or + incomplete multibyte or wide character" or "commitAndReleaseBuffer: in- + valid argument (invalid character)" + Programs compiled with GHC (hledger, haskell build tools, etc.) need + the system locale to be UTF-8-aware, or they will fail when they en- + counter non-ascii characters. To fix it, set the LANG environment + variable to a locale which supports UTF-8 and which is installed on + your system. + + On unix, locale -a lists the installed locales. Look for one which + mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8, + fr_FR.utf8. If necessary, use your system package manager to install + one. Then select it by setting the LANG environment variable. Note, + exact spelling and capitalisation of the locale name may be important: + Here's one common way to configure this permanently for your shell: + + $ echo "export LANG=en_US.utf8" >>~/.profile + # close and re-open terminal window + + If you are using Nix (not NixOS) for GHC and Hledger, you might need to + set the LOCALE_ARCHIVE variable: + + $ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile + # close and re-open terminal window + + COMPATIBILITY ISSUES: hledger gives an error with my Ledger file + Not all of Ledger's journal file syntax or feature set is supported. + See hledger and Ledger for full details. + + + +AUTHORS + Simon Michael and contributors. + See http://hledger.org/CREDITS.html + + +COPYRIGHT + Copyright 2007-2023 Simon Michael and contributors. + + +LICENSE + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + +hledger-1.32.1 December 2023 HLEDGER(1)