hledger 1.41 → 1.42

raw patch · 38 files changed

+25010/−23613 lines, 38 filesdep −terminfodep ~basedep ~hledger-libPVP ok

version bump matches the API change (PVP)

Dependencies removed: terminfo

Dependency ranges changed: base, hledger-lib

API changes (from Hackage documentation)

Files

• CHANGES.md +120/−3
• Hledger/Cli.hs +56/−40
• Hledger/Cli/CliOptions.hs +35/−125
• Hledger/Cli/Commands.hs +174/−56
• Hledger/Cli/Commands/Add.hs +3/−3
• Hledger/Cli/Commands/Aregister.hs +10/−11
• Hledger/Cli/Commands/Aregister.txt +2/−3
• Hledger/Cli/Commands/Balance.hs +15/−16
• Hledger/Cli/Commands/Balance.txt +4/−8
• Hledger/Cli/Commands/Balancesheet.txt +0/−2
• Hledger/Cli/Commands/Balancesheetequity.txt +0/−2
• Hledger/Cli/Commands/Cashflow.txt +0/−2
• Hledger/Cli/Commands/Close.hs +25/−27
• Hledger/Cli/Commands/Close.txt +95/−83
• Hledger/Cli/Commands/Commands.txt +6/−0
• Hledger/Cli/Commands/Demo.txt +2/−0
• Hledger/Cli/Commands/Incomestatement.txt +0/−2
• Hledger/Cli/Commands/Print.hs +6/−4
• Hledger/Cli/Commands/Print.txt +7/−2
• Hledger/Cli/Commands/Register.hs +4/−4
• Hledger/Cli/Commands/Register.txt +4/−8
• Hledger/Cli/Commands/Repl.txt +67/−0
• Hledger/Cli/Commands/Roi.hs +101/−104
• Hledger/Cli/Commands/Run.hs +260/−0
• Hledger/Cli/Commands/Run.txt +86/−0
• Hledger/Cli/CompoundBalanceCommand.hs +16/−15
• bench/bench.hs +4/−5
• embeddedfiles/hledger-ui.1 +2/−5
• embeddedfiles/hledger-ui.info +19/−21
• embeddedfiles/hledger-ui.txt +2/−4
• embeddedfiles/hledger-web.1 +2/−2
• embeddedfiles/hledger-web.info +12/−12
• embeddedfiles/hledger-web.txt +2/−2
• embeddedfiles/hledger.1 +553/−247
• embeddedfiles/hledger.info +12980/−12700
• embeddedfiles/hledger.txt +10324/−10067
• hledger.cabal +12/−25
• test/unittest.hs +0/−3

@@ -23,8 +23,126 @@ User-visible changes in the hledger command line tool and library.  -# 2024-12-09 1.41+# 2025-03-07 1.42 +Fixes++- hledger's default options for the `less` pager no longer include --use-color,+  which caused older less versions (eg 551) to break. [#2335]++- In balance --budget reports, costs no longer prevent display of percentages. [#2327]++- In the balance command's HTML output, -H/--historical now suppresses the total heading.++- print --help now shows the right default for --round. [#2318]++- close --infer-costs no longer implies the -x/--explicit flag. [#1826]++- add: Account names provided on the command line are no longer ignored. [#2305]++- bs/bse/cf/is no longer show the unsupported --budget option in their help. [#2302]++- The print command now ignores --depth entirely. Previously, a depth+  limit caused it to show only transactions referencing accounts as+  deep or deeper than that.++- Week periods beginning in the previous year are now shown correctly.+  Eg the week beginning 2024-12-30 (which is week 1 of 2025 because the+  thursday falls in 2025) was previously shown as 2024-W01, and is now shown as 2025-W01.+  [#2304]++Features++- `run` and `repl` are new commands which run a multiple commands,+  without re-parsing data, so they run faster.+  `run` runs a commands from files or provided on the command line,+  and `repl` provides an interactive prompt with readline-style history.+  (Dmitry Astapov, Simon Michael, [#2323], [#2328])++- `commands` is a new explicit command for showing the commands list; it's useful in the REPL.+  With --builtin, it shows only the builtin commands.++- hledger can now read CSV/SSV/TSV data in encodings other than UTF8,+  using the new `encoding` CSV rule. (Joschua Kesper,  [#2319])++- `if` matchers in CSV rules now allow multiple matchers to be combined on the same line,+  separated by `&&` (AND) or `&& !` (AND NOT).  This makes `if` tables more expressive.+  Examples:++  	if %description amazon && %date 2025-02-22+  	    account2 expenses:books++  	if,account2+  	%description amazon && %date 2025-02-22, expenses:books++  For consistency, the next-line `&` operator may now also be written as `&&`.+  (Thomas Miedema, [#2333])++Improvements++- Two more file extensions are now recognised as possible hledger addon+  commands: `.osh` and `.ysh`.++- Terminal width is now detected more robustly by using the POSIX API.+  This means eg that register commands use the proper terminal width in more environments,+  eg when $TERM or $COLUMNS do not have a correct/up-to-date value, and on Windows.+  hledger no longer uses COLUMNS.+  (gesh, [#2332, #2340])++- The print command now supports the --invert flag. [#2314]++- --pivot can now also pivot on amount quantity (`amt`),+  amount cost (`cost`), and/or commodity symbol (`comm` or `cur`).++- imp:close: omit file extension from tag value++- close --migrate has been renamed to close --clopen.++- The close command's start: tag has been renamed to `clopen:`.+  And its default value now excludes the file extension.++- close --assign's tag has been renamed to `assign:`.++- The roi command is now faster:+  it no longer checks every day with P directive,+  and the "one period per report interval" case has been optimised.+  (Dmitry Astapov)++- Error messages (first line) in the terminal are now shown in red (and bold),+  and warning messages are shown in yellow,+  when ANSI codes are supported and permitted.++Docs++- aregister: Drop an inconsistent newline from options help.+- balance: improve --layout option help.+- close: doc rewrites+- shell completions: mention zsh; cleanups+- cost/lot notations: clarify+- cost, value reporting: edits+- Directive effects: fix account types link [#126]+- commodity styles: fix typo [hledger_site#123]+- commodity directive: clarify+- close: mention the balance assertions+- pager: mention --pager=no+- Aliases and account types: better troubleshooting command+- Beancount output: mention limitations: P and balance assignments+- Balance report output: drop outdated note about --tree and HTML [#1846]++Scripts/addons++API++- Reader's rReadFn has changed type (for the new CSV text encoding feature);+  it now takes a `Handle` rather than a `Text`, allowing more flexibility.++- lib: add dropRawOpt, cliOptsDropArgs++- lib: showAmountCost(B): drop leading whitespace+++# 1.41 2024-12-09+ Breaking changes  - Accounts named "equity:conversion", "equity:trading", or "equity:trade(s)",@@ -83,7 +201,7 @@  - In a multi-line comment generated by CSV rules, tags on all lines now work (ie, can be matched).   Posting dates in comments generated from CSV also now [work](https://hledger.org/hledger.html#comment-field).-  (#2241)+  [#2241]  - hledger's bash shell completions are now up to date with the latest CLI.   [#986]@@ -228,7 +346,6 @@ - FODS output: describe the advantages over CSV (Henning Thielemann) - Debug output: note that the --debug option doesn't work in config files. - bal: improve --layout doc-- bal: note that tree mode doesn't work in html output [#1846] - bal: also mention hledger.css and text encoding in balance doc - html: note safari text encoding issue - timedot: mention the common journal+timedot file setup [#2238]

@@ -108,7 +108,6 @@ import System.Console.CmdArgs.Explicit as CmdArgsWithoutName hiding (Name) import System.Environment import System.Exit-import System.FilePath import System.Process import Text.Megaparsec (optional, takeWhile1P, eof) import Text.Megaparsec.Char (char)@@ -118,6 +117,7 @@ import Hledger.Cli.CliOptions import Hledger.Cli.Conf import Hledger.Cli.Commands+import Hledger.Cli.Commands.Run import Hledger.Cli.DocFiles import Hledger.Cli.Utils import Hledger.Cli.Version@@ -224,7 +224,7 @@   usecolor <- useColorOnStdout   when usecolor setupPager   -- Search PATH for addon commands. Exclude any that match builtin command names.-  addons <- hledgerAddons <&> filter (not . (`elem` builtinCommandNames) . dropExtension)+  addons <- addonCommandNames    ---------------------------------------------------------------   dbgIO "\n1. Preliminary command line parsing" ()@@ -239,12 +239,13 @@   cliargs <- getArgs     >>= expandArgsAt         -- interpolate @ARGFILEs     <&> replaceNumericFlags  -- convert -NUM to --depth=NUM+    <&> argsAddDoubleDash    -- repeat the first -- arg, as a cmdargs workaround   let     (clicmdarg, cliargswithoutcmd, cliargswithcmdfirst) = moveFlagsAfterCommand cliargs     cliargswithcmdfirstwithoutclispecific = dropCliSpecificOpts cliargswithcmdfirst     (cliargsbeforecmd, cliargsaftercmd) = second (drop 1) $ break (==clicmdarg) cliargs-  dbgIO "cli args" cliargs-  dbg1IO "cli args with options moved after command, if any" cliargswithcmdfirst+  dbgIO  "cli args with preprocessing" cliargs+  dbg1IO "cli args with preprocessing and options moved after command" cliargswithcmdfirst   dbgIO "cli command argument found" clicmdarg   dbgIO "cli args before command"    cliargsbeforecmd   dbgIO "cli args after command"     cliargsaftercmd@@ -365,7 +366,16 @@     infoFlag    = boolopt "info"    rawopts     manFlag     = boolopt "man"     rawopts     versionFlag = boolopt "version" rawopts+    -- ignoredopts    cmd = error' $ cmd ++ " tried to read options but is not supposed to"+    ignoredjournal cmd = error' $ cmd ++ " tried to read the journal but is not supposed to" +  -- validate opts/args more and convert to CliOpts+  opts <- rawOptsToCliOpts rawopts >>= \opts0 -> return opts0{progstarttime_=starttime}+  dbgIO2 "processed opts" opts+  dbgIO "period from opts" (period_ . _rsReportOpts $ reportspec_ opts)+  dbgIO "interval from opts" (interval_ . _rsReportOpts $ reportspec_ opts)+  dbgIO "query from opts & args" (_rsQuery $ reportspec_ opts)+   -- Ensure that anything calling getArgs later will see all args, including config file args.   -- Some things (--color, --debug, some checks in journalFinalise) are detected by unsafePerformIO,   -- eg in Hledger.Utils.IO.progArgs, which means they aren't be seen in a config file@@ -385,39 +395,37 @@     | badcmdprovided -> error' $ "command "++clicmdarg++" is not recognized, run with no command to see a list"      -- 6.4. no command found, nothing else to do - show the commands list-    | nocmdprovided -> dbgIO1 "no command, showing commands list" () >> printCommandsList prognameandversion addons+    | nocmdprovided -> do+        dbgIO1 "no command, showing commands list" ()+        commands opts (ignoredjournal "commands")      -- 6.5. builtin command found     | Just (cmdmode, cmdaction) <- mbuiltincmdaction -> do       let mmodecmdname = headMay $ modeNames cmdmode       dbgIO1 "running builtin command mode" $ fromMaybe "" mmodecmdname -      -- validate opts/args more and convert to CliOpts-      opts <- rawOptsToCliOpts rawopts >>= \opts0 -> return opts0{progstarttime_=starttime}-      dbgIO2 "processed opts" opts-      dbgIO "period from opts" (period_ . _rsReportOpts $ reportspec_ opts)-      dbgIO "interval from opts" (interval_ . _rsReportOpts $ reportspec_ opts)-      dbgIO "query from opts & args" (_rsQuery $ reportspec_ opts)-      let tldrpagename = maybe "hledger" (("hledger-"<>)) mmodecmdname-       -- run the builtin command according to its type       if         -- 6.5.1. help/doc flag - show command help/docs         | helpFlag  -> runPager $ showModeUsage cmdmode ++ "\n"-        | tldrFlag  -> runTldrForPage tldrpagename+        | tldrFlag  -> runTldrForPage $ maybe "hledger" (("hledger-"<>)) mmodecmdname         | infoFlag  -> runInfoForTopic "hledger" mmodecmdname         | manFlag   -> runManForTopic "hledger"  mmodecmdname          -- 6.5.2. builtin command which should not require or read the journal - run it-        | cmdname `elem` ["demo","help","test"] ->-          cmdaction opts $ error' $ cmdname++" tried to read the journal but is not supposed to"+        | cmdname `elem` ["commands","demo","help","test"] ->+          cmdaction opts (ignoredjournal cmdname)          -- 6.5.3. builtin command which should create the journal if missing - do that and run it         | cmdname `elem` ["add","import"] -> do           ensureJournalFileExists . NE.head =<< journalFilePathFromOpts opts           withJournalDo opts (cmdaction opts) -        -- 6.5.4. all other builtin commands - read the journal and if successful run the command with it+        -- 6.5.4. "run" and "repl" need findBuiltinCommands passed to it to avoid circular dependency in the code+        | cmdname == "run"  -> Hledger.Cli.Commands.Run.run Nothing findBuiltinCommand addons opts+        | cmdname == "repl" -> Hledger.Cli.Commands.Run.repl findBuiltinCommand addons opts++        -- 6.5.5. all other builtin commands - read the journal and if successful run the command with it         | otherwise -> withJournalDo opts $ cmdaction opts      -- 6.6. external addon command found - run it,@@ -481,12 +489,24 @@     (traceOrLogAt verboseDebugLevel ("cmdargs: parsing " <> desc <> ": " <> show args0))   -- XXX better error message when cmdargs fails (eg spaced/quoted/malformed flag values) ? --- | cmdargs does not allow flags (options) to appear before the subcommand argument.--- We prefer to hide this restriction from the user, making the CLI more forgiving.--- So this tries to move flags, and their values if any, after the command argument.--- It also returns the (possibly empty) command argument and the other arguments,--- separately for convenience.+-- | cmdargs does not allow options to appear before the subcommand argument.+-- We prefer to hide this restriction from the user, providing a more forgiving CLI.+-- So this helper tries to move any pre-command flags/options, and their values if any, after the command argument.+-- If there is a "--"" argument, only the preceding args are rearranged.+-- To be precise: pre-command options will be moved to the end of the part of the command line preceding the first -- argument.+-- The pre-command options' relative order will be preserved, but since they may be moved after post-command options,+-- the overall order of options may change.+-- XXX moving them right after the command would probably be better. --+-- For convenience of the caller, this currently returns a triple:+-- (+--  the command, if one was found (or ""),+--  the rearranged args without the command,+--  the command followed by the rearranged args+-- )+--+-- Notes:+-- -- Detecting the command argument is tricky because of the flexibility of traditional flag syntax. -- Short flags can be joined together, some flags can have a value or no value, -- flags and values can be separated by =, a space, or nothing, etc.@@ -503,31 +523,27 @@ -- - it begins with a long requires-value flag followed by =; likewise -- - it begins with a long optional-value flag followed by =; likewise ----- Notes:------ - This hackery increases the risk of misleading errors, bugs, and confusion.---   It should be fairly robust now, being aware of all builtin flags.---   The main tests are in hledger/test/cli/cli.test, but they are not exhaustive.------ - All general and builtin command flags (and their values) will be moved. It's clearer to---   write command flags after the command, but if not we'll handle it (for greater robustness).+-- This hackery increases the risk of misleading errors, bugs, and confusion.+-- It should be fairly robust now, being aware of all builtin flags.+-- The main tests are in hledger/test/cli/cli.test, but they are not exhaustive. ----- - Long flags should be spelled in full; abbreviated long flags might not get moved.+-- All general and builtin command flags (and their values) will be moved. It's clearer to+-- write command flags after the command, but if not we'll handle it (for greater robustness). ----- - Unknown flags (from addons) are assumed to be valueless or have a joined value,---   and will be moved - but later rejected by cmdargs.---   Instead these should be written to the right of a "--" argument, which hides them.+-- Long flags should be spelled in full; abbreviated long flags might not get moved. ----- - XXX Relative order of flags is mostly but not entirely preserved, currently:---   pre-command flags get moved to the end, after post-command flags. +-- Unknown flags (from addons) are assumed to be valueless or have a joined value,+-- and will be moved - but later rejected by cmdargs.+-- Instead these should be written to the right of a "--" argument, which hides them. -- moveFlagsAfterCommand :: [String] -> (String, [String], [String]) moveFlagsAfterCommand args =-  case moveFlagAndVal (args, []) of-    ([],as)                      -> ("", as, as)-    (unmoved@(('-':_):_), moved) -> ("", as, as) where as = unmoved<>moved-    (cmdarg:unmoved, moved)      -> (cmdarg, as, cmdarg:as) where as = unmoved<>moved+  case moveFlagAndVal (as1, []) of+    ([],as1')                    -> ("", as, as) where as = as1' <> as2+    (unmoved@(('-':_):_), moved) -> ("", as, as) where as = unmoved <> moved <> as2+    (cmdarg:unmoved, moved)      -> (cmdarg, as, cmdarg:as) where as = unmoved <> moved <> as2   where+    (as1, as2) = break (== "--") args     -- Move the next argument to the end if it is a movable flag, along with its subsequent value argument if any.     moveFlagAndVal :: ([String], [String]) -> ([String], [String])     moveFlagAndVal ((a:b:cs), moved) =

@@ -49,7 +49,6 @@   showModeUsage,   withAliases,   likelyExecutablesInPath,-  hledgerExecutablesInPath,    -- * CLI options   CliOpts(..),@@ -58,6 +57,8 @@   getHledgerCliOpts,   getHledgerCliOpts',   rawOptsToCliOpts,+  cliOptsDropArgs,+  argsAddDoubleDash,   outputFormats,   defaultOutputFormat,   CommandHelpStr,@@ -67,18 +68,17 @@   -- * CLI option accessors   -- | These do the extra processing required for some options.   journalFilePathFromOpts,+  journalFilePathFromOptsNoDefault,   rulesFilePathFromOpts,   outputFileFromOpts,   outputFormatFromOpts,   defaultWidth,-  -- widthFromOpts,   replaceNumericFlags,   ensureDebugFlagHasVal,   -- | For register:   registerWidthsFromOpts,    -- * Other utils-  hledgerAddons,   topicForMode,  --  -- * Convenience re-exports@@ -91,9 +91,8 @@ import Control.Monad (when) import Data.Char import Data.Default-import Data.Either (isRight)-import Data.List.Extra (groupSortOn, intercalate, isInfixOf, nubSort)-import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, head, nonEmpty)+import Data.List.Extra (intercalate, isInfixOf, nubSort)+import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, nonEmpty) import Data.List.Split (splitOn) import Data.Maybe --import Data.String.Here@@ -106,9 +105,6 @@ import System.Console.CmdArgs hiding (Default,def) import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Text-#ifndef mingw32_HOST_OS-import System.Console.Terminfo-#endif import System.Directory import System.Environment import System.Exit (exitSuccess)@@ -551,9 +547,8 @@     ,no_new_accounts_ :: Bool           -- add     ,width_           :: Maybe String   -- ^ the --width value provided, if any     ,available_width_ :: Int            -- ^ estimated usable screen width, based on-                                        -- 1. the COLUMNS env var, if set-                                        -- 2. the width reported by the terminal, if supported-                                        -- 3. the default (80)+                                        -- 1. the width reported by the terminal, if supported+                                        -- 2. the default (80)     ,progstarttime_   :: POSIXTime      -- system POSIX time at start  } deriving (Show) @@ -616,15 +611,8 @@   usecolor <- useColorOnStdout   let iopts = rawOptsToInputOpts day usecolor postingaccttags rawopts   rspec <- either error' pure $ rawOptsToReportSpec day usecolor rawopts  -- PARTIAL:-  mcolumns <- readMay <$> getEnvSafe "COLUMNS"-  mtermwidth <--#ifdef mingw32_HOST_OS-    return Nothing-#else-    (`getCapability` termColumns) <$> setupTermFromEnv-    -- XXX Throws a SetupTermError if the terminfo database could not be read, should catch-#endif-  let availablewidth = NE.head $ NE.fromList $ catMaybes [mcolumns, mtermwidth, Just defaultWidth]  -- PARTIAL: fromList won't fail because non-null list+  mtermwidth <- getTerminalWidth+  let availablewidth = fromMaybe defaultWidth mtermwidth   return defcliopts {               rawopts_         = rawopts              ,command_         = command@@ -641,6 +629,18 @@              ,available_width_ = availablewidth              } +-- | Drop the arguments ("args") from this CliOpts' rawopts field.+cliOptsDropArgs :: CliOpts -> CliOpts+cliOptsDropArgs copts@CliOpts{rawopts_} = copts{rawopts_ = dropRawOpt "args" rawopts_}++-- | cmdargs eats the first double-dash (--) argument when parsing a command line,+-- which causes problems for the run and repl commands.+-- Sometimes we work around this by duplicating that first -- argument.+-- This doesn't break anything that we know of yet.+argsAddDoubleDash args'+  | "--" `elem` args' = let (as,bs) = break (=="--") args' in as <> ["--"] <> bs+  | otherwise = args'+ -- | A helper for addon commands: this parses options and arguments from -- the current command line using the given hledger-style cmdargs mode, -- and returns a CliOpts. Or, with --help or -h present, it prints@@ -706,12 +706,20 @@ -- File paths can have a READER: prefix naming a reader/data format. journalFilePathFromOpts :: CliOpts -> IO (NE.NonEmpty String) journalFilePathFromOpts opts = do-  f <- defaultJournalPath+  mbpaths <- journalFilePathFromOptsNoDefault opts+  case mbpaths of+    Just paths -> return paths+    Nothing -> do+      f <- defaultJournalPath+      return $ NE.fromList [f]++-- | Like journalFilePathFromOpts, but does not use defaultJournalPath+journalFilePathFromOptsNoDefault :: CliOpts -> IO (Maybe (NE.NonEmpty String))+journalFilePathFromOptsNoDefault opts = do   d <- getCurrentDirectory-  maybe-    (return $ NE.fromList [f])-    (mapM (expandPathPreservingPrefix d))-    $ NE.nonEmpty $ file_ opts+  case NE.nonEmpty $ file_ opts of+    Nothing -> return Nothing+    Just paths -> Just <$> mapM (expandPathPreservingPrefix d) paths  expandPathPreservingPrefix :: FilePath -> PrefixedFilePath -> IO PrefixedFilePath expandPathPreservingPrefix d prefixedf = do@@ -765,24 +773,11 @@   d <- getCurrentDirectory   maybe (return Nothing) (fmap Just . expandPath d) $ mrules_file_ $ inputopts_ opts --- -- | Get the width in characters to use for console output.--- -- This comes from the --width option, or the COLUMNS environment--- -- variable, or (on posix platforms) the current terminal width, or 80.--- -- Will raise a parse error for a malformed --width argument.--- widthFromOpts :: CliOpts -> Int--- widthFromOpts CliOpts{width_=Nothing, available_width_=w} = w--- widthFromOpts CliOpts{width_=Just s}  =---     case runParser (read `fmap` some digitChar <* eof :: ParsecT Void String Identity Int) "(unknown)" s of---         Left e   -> usageError $ "could not parse width option: "++errorBundlePretty e---         Right w  -> w---- for register:- -- | Get the width in characters to use for the register command's console output, -- and also the description column width if specified (following the main width, comma-separated). -- The widths will be as follows: -- @--- no --width flag - overall width is the available width (COLUMNS, or posix terminal width, or 80); description width is unspecified (auto)+-- no --width flag - overall width is the available width (or terminal width, or 80); description width is unspecified (auto) -- --width W       - overall width is W, description width is auto -- --width W,D     - overall width is W, description width is D -- @@@ -803,48 +798,6 @@  -- Other utils --- | Get the sorted unique canonical names of hledger addon commands--- found in the current user's PATH. These are used in command line--- parsing and to display the commands list.------ Canonical addon names are the filenames of hledger-* executables in--- PATH, without the "hledger-" prefix, and without the file extension--- except when it's needed for disambiguation (see below).------ When there are exactly two versions of an executable (same base--- name, different extensions) that look like a source and compiled--- pair (one has .exe, .com, or no extension), the source version will--- be excluded (even if it happens to be newer). When there are three--- or more versions (or two versions that don't look like a--- source/compiled pair), they are all included, with file extensions--- intact.----hledgerAddons :: IO [String]-hledgerAddons = do-  -- past bug generator-  as1 <- hledgerExecutablesInPath                     -- ["hledger-check","hledger-check-dates","hledger-check-dates.hs","hledger-check.hs","hledger-check.py"]-  let as2 = map stripPrognamePrefix as1               -- ["check","check-dates","check-dates.hs","check.hs","check.py"]-  let as3 = groupSortOn takeBaseName as2              -- [["check","check.hs","check.py"],["check-dates","check-dates.hs"]]-  let as4 = concatMap dropRedundantSourceVersion as3  -- ["check","check.hs","check.py","check-dates"]-  return as4--stripPrognamePrefix = drop (length progname + 1)--dropRedundantSourceVersion [f,g]-  | map toLower (takeExtension f) `elem` compiledExts = [f]-  | map toLower (takeExtension g) `elem` compiledExts = [g]-dropRedundantSourceVersion fs = fs--compiledExts = ["",".com",".exe"]---- | Get the sorted unique filenames of all hledger-* executables in--- the current user's PATH. These are files in any of the PATH directories,--- named hledger-*, with either no extension (and no periods in the name)--- or one of the addonExtensions.--- We do not currently filter out non-file objects or files without execute permission.-hledgerExecutablesInPath :: IO [String]-hledgerExecutablesInPath = filter isHledgerExeName <$> likelyExecutablesInPath- -- None of https://hackage.haskell.org/package/directory-1.3.8.1/docs/System-Directory.html#g:5 -- do quite what we need (find all the executables in PATH with a filename prefix). -- | Get all sorted unique filenames in the current user's PATH.@@ -865,55 +818,12 @@ -- return exes'' -- where isExecutable f = getPermissions f >>= (return . executable) -isHledgerExeName :: String -> Bool-isHledgerExeName = isRight . parsewith hledgerexenamep . T.pack-    where-      hledgerexenamep = do-        _ <- string $ T.pack progname-        _ <- char '-'-        _ <- some $ noneOf ['.']-        optional (string "." >> choice' (map (string . T.pack) addonExtensions))-        eof---- stripAddonExtension :: String -> String--- stripAddonExtension = regexReplace re "" where re = "\\.(" ++ intercalate "|" addonExtensions ++ ")$"--addonExtensions :: [String]-addonExtensions =-  ["bat"-  ,"com"-  ,"exe"-  ,"hs"-  ,"js"-  ,"lhs"-  ,"lua"-  ,"php"-  ,"pl"-  ,"py"-  ,"rb"-  ,"rkt"-  ,"sh"-  -- ,""-  ]- getEnvSafe :: String -> IO String getEnvSafe v = getEnv v `C.catch` (\(_::C.IOException) -> return "") -- XXX should catch only isDoesNotExistError e  getDirectoryContentsSafe :: FilePath -> IO [String] getDirectoryContentsSafe d =     (filter (not . (`elem` [".",".."])) `fmap` getDirectoryContents d) `C.catch` (\(_::C.IOException) -> return [])---- not used:--- -- | Print debug info about arguments and options if --debug is present.--- debugArgs :: [String] -> CliOpts -> IO ()--- debugArgs args opts =---   when ("--debug" `elem` args) $ do---     progname <- getProgName---     putStrLn $ "running: " ++ progname---     putStrLn $ "raw args: " ++ show args---     putStrLn $ "processed opts:\n" ++ show opts---     d <- getCurrentDay---     putStrLn $ "search query: " ++ (show $ queryFromOpts d $ reportopts_ opts)  -- ** Lenses 

@@ -15,11 +15,13 @@ {-# LANGUAGE TemplateHaskell #-}  module Hledger.Cli.Commands (-   testcmd+   commands+  ,testcmd   ,builtinCommands   ,builtinCommandNames+  ,addonCommandNames+  ,knownAddonCommandNames   ,findBuiltinCommand-  ,knownAddonCommands   ,knownCommands   ,printCommandsList   ,tests_Hledger_Cli@@ -46,22 +48,27 @@   ,module Hledger.Cli.Commands.Print   ,module Hledger.Cli.Commands.Register   ,module Hledger.Cli.Commands.Rewrite+  ,module Hledger.Cli.Commands.Run   ,module Hledger.Cli.Commands.Stats   ,module Hledger.Cli.Commands.Tags )  where -import Data.Char (isAlphaNum, isSpace)+import Data.Char (isAlphaNum, isSpace, toLower)+import Data.Either (isRight) import Data.List-import Data.List.Extra (nubSort)+import Data.List.Extra (groupSortOn, nubSort) import Data.Text (Text) import qualified Data.Text as T import Data.Time.Calendar import Safe (headErr) import String.ANSI-import System.Environment (withArgs) import System.Console.CmdArgs.Explicit as C+import System.Environment (withArgs)+import System.FilePath (dropExtension, takeBaseName, takeExtension) import Test.Tasty (defaultMain)+import Text.Megaparsec+import Text.Megaparsec.Char  import Hledger import Hledger.Cli.CliOptions@@ -91,9 +98,11 @@ import Hledger.Cli.Commands.Register import Hledger.Cli.Commands.Rewrite import Hledger.Cli.Commands.Roi+import Hledger.Cli.Commands.Run import Hledger.Cli.Commands.Stats import Hledger.Cli.Commands.Tags import Hledger.Cli.Utils (tests_Cli_Utils)+import Data.Functor ((<&>))  -- | The cmdargs subcommand mode (for command-line parsing) -- and IO action (for doing the command's work) for each builtin command.@@ -111,6 +120,7 @@   ,(checkmode              , check)   ,(closemode              , close)   ,(codesmode              , codes)+  ,(commandsmode           , commands)   ,(commoditiesmode        , commodities)   ,(demomode               , demo)   ,(descriptionsmode       , descriptions)@@ -126,6 +136,8 @@   ,(registermode           , register)   ,(rewritemode            , rewrite)   ,(roimode                , roi)+  ,(runmode                , runOrReplStub)+  ,(replmode               , runOrReplStub)   ,(statsmode              , stats)   ,(tagsmode               , tags)   ,(testmode               , testcmd)@@ -188,7 +200,7 @@ --  commandsList :: String -> [String] -> [String] commandsList progversion othercmds =-  map (bold'.accent) _banner_smslant ++ +  map (bold'.accent) _banner_smslant ++   -- XXX not showing bold, why ?   [   -- Keep the following synced with:   --  commands.m4@@ -199,31 +211,34 @@    "-------------------------------------------------------------------------------"   ,progversion   ,"Usage: hledger COMMAND [OPTIONS] [-- ADDONOPTIONS]"-  ,"Commands (builtins + addons):"+  -- ,"Commands (builtins + addons):"  -- XXX adapt for commands --builtin+  ,"Commands:"   ,""     -----------------------------------------80-------------------------------------   ,bold' "HELP (docs, demos..)"-  ," (no arguments)           show this commands list"-  ," -h [COMMAND]             show command line help"-  ," --tldr [COMMAND]         show command examples with tldr"-  ," --info [COMMAND]         show the hledger manual with info"-  ," --man  [COMMAND]         show the hledger manual with man"-  ," help [-i|-m|-p] [TOPIC]  show any topic in the hledger manual"+  ," commands                 show the commands list (default)"   ," demo [DEMO]              show brief demos in the terminal"+  ," help [-i|-m|-p] [TOPIC]  show the hledger manual with info/man/pager"+  ," --tldr    [COMMAND]      show command examples   [for command] with tldr"+  ," --help/-h [COMMAND]      show command line help  [for command]"+  ," --info    [COMMAND]      show the hledger manual [for command] with info"+  ," --man     [COMMAND]      show the hledger manual [for command] with man"   ,"                          more help: https://hledger.org"   ,""     -----------------------------------------80-------------------------------------   ,bold' "USER INTERFACES (alternate UIs)"-  ,"+ui                       run terminal UI"                                       -- hledger-ui-  ,"+web                      run web UI"                                            -- hledger-web+  ," repl                     run commands from an interactive prompt"+  ," run                      run command scripts from files or arguments"+  ,"+ui                       run a terminal UI (hledger-ui)"+  ,"+web                      run a web UI (hledger-web)"                                                                                      -- see also: MoLe, https://hledger.org/mobile.html   ,""     -----------------------------------------80-------------------------------------   ,bold' "ENTERING DATA (add or edit transactions)"   ," add                      add transactions using interactive prompts"-  ,"+iadd                     add transactions using a TUI"                          -- hledger-iadd+  ,"+iadd                     add transactions using a TUI (hledger-iadd)"   ," import                   add new transactions from other files, eg CSV files"-  ,"+edit                     edit existing transactions with $EDITOR"               -- hledger-utils+  ,"+edit                     edit specific transactions with $EDITOR"               -- hledger-utils   ,""     -----------------------------------------80-------------------------------------   ,bold' "BASIC REPORTS (simple lists)"@@ -297,54 +312,157 @@   , not $ "https://" `isInfixOf` line   , let cmdname:_ = words line   ]-  -- KEEP SYNCED WITH commandsList.+  -- Keep synced with commandsList. +commandsmode =+  hledgerCommandMode+    $(embedFileRelative "Hledger/Cli/Commands/Commands.txt")+    [flagNone ["builtin"] (setboolopt "builtin")  "show only builtin commands, not addons"+    ]+    [(helpflagstitle, helpflags)]+    []+    -- flagReq  ["debug"]    (\s opts -> Right $ setopt "debug" s opts) "[N]" "show debug output (levels 1-9, default: 1)"++    ([], Nothing)++-- | Display the commands list.+commands :: CliOpts -> Journal -> IO ()+commands opts _ = do+  addons <- if boolopt "builtin" (rawopts_ opts) then return [] else addonCommandNames+  printCommandsList prognameandversion addons++{- | Print the commands list, with a pager if appropriate, customising the+commandsList template above with the given version string and the installed addons.+Uninstalled known addons will be removed from the list,+installed known addons will have the + prefix removed,+and installed unknown addons will be added under Misc.+-}+printCommandsList :: String -> [String] -> IO ()+printCommandsList progversion installedaddons =+  seq (length $ dbg8 "uninstalledknownaddons" uninstalledknownaddons) $ -- for debug output+    seq (length $ dbg8 "installedknownaddons" installedknownaddons) $+      seq (length $ dbg8 "installedunknownaddons" installedunknownaddons) $+        runPager $+          unlines $+            map unplus $+              filter (not . isuninstalledaddon) $+                commandsList progversion installedunknownaddons+ where+  knownaddons = knownAddonCommandNames+  uninstalledknownaddons = knownaddons \\ installedaddons+  installedknownaddons = knownaddons `intersect` installedaddons+  installedunknownaddons = installedaddons \\ knownaddons+  unplus ('+' : cs) = ' ' : cs+  unplus s = s+  isuninstalledaddon =+    \case+      ('+' : l)+        | cmd `notElem` installedaddons ->+            dbg9With (const $ "hiding uninstalled addon: " <> cmd) $+              True+       where+        cmd = takeWhile (not . isSpace) l+      _ -> False+ -- | Canonical names of all commands which have a slot in the commands list, in alphabetical order. -- These include the builtin commands and the known addon commands. knownCommands :: [String] knownCommands = nubSort . commandsListExtractCommands False $ commandsList progname [] --- | Canonical names of the known addon commands which have a slot in the commands list,--- in alphabetical order.-knownAddonCommands :: [String]-knownAddonCommands = nubSort . commandsListExtractCommands True $ commandsList progname []- -- | All names and aliases of the builtin commands. builtinCommandNames :: [String] builtinCommandNames = concatMap (modeNames . fst) builtinCommands --- | Look up a builtin command's mode and action by exact command name or alias. +-- | Look up a builtin command's mode and action by exact command name or alias. findBuiltinCommand :: String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())  findBuiltinCommand cmdname = find (elem cmdname . modeNames . fst) builtinCommands  --- | Print the commands list, with a pager if appropriate, customising the--- commandsList template above with the given version string and the installed addons.--- Uninstalled known addons will be removed from the list,--- installed known addons will have the + prefix removed,--- and installed unknown addons will be added under Misc.-printCommandsList :: String -> [String] -> IO ()-printCommandsList progversion installedaddons =-  seq (length $ dbg8 "uninstalledknownaddons" uninstalledknownaddons) $  -- for debug output-  seq (length $ dbg8 "installedknownaddons"   installedknownaddons)   $-  seq (length $ dbg8 "installedunknownaddons" installedunknownaddons) $-  runPager $ unlines $ map unplus $ filter (not.isuninstalledaddon) $-    commandsList progversion installedunknownaddons-  where-    knownaddons = knownAddonCommands-    uninstalledknownaddons  = knownaddons \\ installedaddons-    installedknownaddons    = knownaddons `intersect` installedaddons-    installedunknownaddons  = installedaddons \\ knownaddons-    unplus ('+':cs) = ' ':cs-    unplus s = s-    isuninstalledaddon =-      \case-        ('+':l) | cmd `notElem` installedaddons ->-                  dbg9With (const $ "hiding uninstalled addon: "<>cmd) $-                  True where cmd = takeWhile (not . isSpace) l-        _ -> False+{- | Canonical names of the known addon commands which have a slot in the commands list,+in alphabetical order.+-}+knownAddonCommandNames :: [String]+knownAddonCommandNames = nubSort . commandsListExtractCommands True $ commandsList progname [] --- The test command is defined here for easy access to other modules' tests.+-- Search PATH for names of addon commands, that aren't shadowed by builtin commands.+addonCommandNames :: IO [String]+addonCommandNames = installedAddonCommandNames <&> filter (not . (`elem` builtinCommandNames) . dropExtension) +-- | Get the sorted unique canonical names of hledger addon commands+-- found in the current user's PATH. These are used in command line+-- parsing and to display the commands list.+--+-- Canonical addon names are the filenames of hledger-* executables in+-- PATH, without the "hledger-" prefix, and without the file extension+-- except when it's needed for disambiguation (see below).+--+-- When there are exactly two versions of an executable (same base+-- name, different extensions) that look like a source and compiled+-- pair (one has .exe, .com, or no extension), the source version will+-- be excluded (even if it happens to be newer). When there are three+-- or more versions (or two versions that don't look like a+-- source/compiled pair), they are all included, with file extensions+-- intact.+--+installedAddonCommandNames :: IO [String]+installedAddonCommandNames = do+  -- past bug generator+  as1 <- hledgerExecutablesInPath                     -- ["hledger-check","hledger-check-dates","hledger-check-dates.hs","hledger-check.hs","hledger-check.py"]+  let as2 = map stripPrognamePrefix as1               -- ["check","check-dates","check-dates.hs","check.hs","check.py"]+  let as3 = groupSortOn takeBaseName as2              -- [["check","check.hs","check.py"],["check-dates","check-dates.hs"]]+  let as4 = concatMap dropRedundantSourceVersion as3  -- ["check","check.hs","check.py","check-dates"]+  return as4++stripPrognamePrefix = drop (length progname + 1)++dropRedundantSourceVersion [f,g]+  | map toLower (takeExtension f) `elem` compiledExts = [f]+  | map toLower (takeExtension g) `elem` compiledExts = [g]+dropRedundantSourceVersion fs = fs++compiledExts = ["",".com",".exe"]++-- | Get the sorted unique filenames of all hledger-* executables in+-- the current user's PATH. These are files in any of the PATH directories,+-- named hledger-*, with either no extension (and no periods in the name)+-- or one of the addonExtensions.+-- We do not currently filter out non-file objects or files without execute permission.+hledgerExecutablesInPath :: IO [String]+hledgerExecutablesInPath = filter isHledgerExeName <$> likelyExecutablesInPath++isHledgerExeName :: String -> Bool+isHledgerExeName = isRight . parsewith hledgerexenamep . T.pack+ where+  hledgerexenamep = do+    _ <- string $ T.pack progname+    _ <- char '-'+    _ <- some $ noneOf ['.']+    optional (string "." >> choice' (map (string . T.pack) addonExtensions))+    eof++-- stripAddonExtension :: String -> String+-- stripAddonExtension = regexReplace re "" where re = "\\.(" ++ intercalate "|" addonExtensions ++ ")$"++addonExtensions :: [String]+addonExtensions =+  ["bat"+  ,"com"+  ,"exe"+  ,"hs"+  ,"js"+  ,"lhs"+  ,"lua"+  ,"php"+  ,"pl"+  ,"py"+  ,"rb"+  ,"rkt"+  ,"sh"+  ,"osh"+  ,"ysh"+  ]++-- The test command is also defined here for easy access to other modules' tests.+ testmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Test.txt")   []@@ -387,8 +505,8 @@         let           ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepospair}) (jtxns j)}           sameParse str1 str2 = do-            j1 <- ignoresourcepos <$> readJournal' str1  -- PARTIAL:-            j2 <- ignoresourcepos <$> readJournal' str2  -- PARTIAL:+            j1 <- ignoresourcepos <$> readJournal'' str1  -- PARTIAL:+            j2 <- ignoresourcepos <$> readJournal'' str2  -- PARTIAL:             j1 @?= j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1}         sameParse            ("2008/12/07 One\n  alpha  $-1\n  beta  $1\n" <>@@ -405,19 +523,19 @@            )      ,testCase "preserves \"virtual\" posting type" $ do-      j <- readJournal' "apply account test\n2008/12/07 One\n  (from)  $-1\n  (to)  $1\n"  -- PARTIAL:+      j <- readJournal'' "apply account test\n2008/12/07 One\n  (from)  $-1\n  (to)  $1\n"  -- PARTIAL:       let p = headErr $ tpostings $ headErr $ jtxns j  -- PARTIAL headErrs succeed because txns & postings provided       paccount p @?= "test:from"       ptype p @?= VirtualPosting     ]    ,testCase "alias directive" $ do-    j <- readJournal' "!alias expenses = equity:draw:personal\n1/1\n (expenses:food)  1\n"  -- PARTIAL:+    j <- readJournal'' "!alias expenses = equity:draw:personal\n1/1\n (expenses:food)  1\n"  -- PARTIAL:     let p = headErr $ tpostings $ headErr $ jtxns j  -- PARTIAL headErrs succeed because txns & postings provided     paccount p @?= "equity:draw:personal:food"    ,testCase "Y default year directive" $ do-    j <- readJournal' defaultyear_journal_txt  -- PARTIAL:+    j <- readJournal'' defaultyear_journal_txt  -- PARTIAL:     tdate (headErr $ jtxns j) @?= fromGregorian 2009 1 1  -- PARTIAL headErr succeeds because defaultyear_journal_txt has a txn    ,testCase "ledgerAccountNames" $@@ -450,7 +568,7 @@ -- t1 = LocalTime date1 midday  {--samplejournal = readJournal' sample_journal_str+samplejournal = readJournal'' sample_journal_str  sample_journal_str = unlines  ["; A sample journal file."

@@ -161,7 +161,7 @@ confirmedTransactionWizard prevInput es@EntryState{..} stack@(currentStage : _) = case currentStage of   EnterDateAndCode -> dateAndCodeWizard prevInput es >>= \case     Just (efd, code) -> do-      let +      let         date = fromEFDay efd         es' = es{ esArgs = drop 1 esArgs                 , esDefDate = date@@ -239,7 +239,7 @@                           }           amountAndCommentString = showAmount amt ++ T.unpack (if T.null comment then "" else "  ;" <> comment)           prevAmountAndCmnt' = replaceNthOrAppend (length esPostings) amountAndCommentString (prevAmountAndCmnt prevInput)-          es' = es{esPostings=esPostings++[p], esArgs=drop 2 esArgs}+          es' = es{esPostings=esPostings++[p], esArgs=drop 1 esArgs}       confirmedTransactionWizard prevInput{prevAmountAndCmnt=prevAmountAndCmnt'} es' (EnterNewPosting txnParams (Just posting) : stack)     Nothing -> confirmedTransactionWizard prevInput es (drop 1 stack) @@ -459,7 +459,7 @@ -- | Convert a string of journal data into a register report. registerFromString :: T.Text -> IO TL.Text registerFromString s = do-  j <- readJournal' s+  j <- readJournal'' s   return . postingsReportAsText opts $ postingsReport rspec j       where         ropts = defreportopts{empty_=True}

@@ -29,19 +29,18 @@ import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as TB import Control.Monad (when)-import Lucid (toHtml)-import qualified Lucid as L+import qualified Lucid as L hiding (Html) import System.Console.CmdArgs.Explicit (flagNone, flagReq)+import qualified System.IO as IO+import Text.Tabular.AsciiWide hiding (render)  import Hledger+import Hledger.Cli.CliOptions+import Hledger.Cli.Utils import Hledger.Write.Csv (CSV, printCSV, printTSV)+import Hledger.Write.Html (formatRow, htmlAsLazyText, toHtml) import Hledger.Write.Ods (printFods) import qualified Hledger.Write.Spreadsheet as Spr-import qualified Hledger.Write.Html.Lucid as Html-import Hledger.Cli.CliOptions-import Hledger.Cli.Utils-import Text.Tabular.AsciiWide hiding (render)-import qualified System.IO as IO  aregistermode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Aregister.txt")@@ -52,7 +51,7 @@   ,flagNone ["cumulative"] (setboolopt "cumulative")      "show running total from report start date"   ,flagNone ["historical","H"] (setboolopt "historical")-     "show historical running total/balance (includes postings before report start date) (default)\n "+     "show historical running total/balance (includes postings before report start date) (default)"   -- ,flagNone ["average","A"] (setboolopt "average")   --    "show running average of posting amounts instead of total (implies --empty)"   -- ,flagNone ["related","r"] (setboolopt "related") "show postings' siblings instead"@@ -66,7 +65,7 @@ #else       "terminal width" #endif-      ++ " or $COLUMNS). -wN,M sets description width as well."+      ++ "). -wN,M sets description width as well."      )   ,flagNone ["align-all"] (setboolopt "align-all") "guarantee alignment across all lines (slower)"   ,outputFormatFlag ["txt","html","csv","tsv","json"]@@ -176,7 +175,7 @@ -- | Render a register report as a HTML snippet. accountTransactionsReportAsHTML :: CliOpts -> Query -> Query -> AccountTransactionsReport -> TL.Text accountTransactionsReportAsHTML copts reportq thisacctq items =-  L.renderText $ do+  htmlAsLazyText $ do     L.link_ [L.rel_ "stylesheet", L.href_ "hledger.css"]     L.table_ $ do       when (headingopt copts) $ L.thead_ $ L.tr_ $ do@@ -186,7 +185,7 @@         L.th_ "change"         L.th_ "balance"       L.tbody_ $ for_ items $-        Html.formatRow . map (fmap toHtml) .+        formatRow . map (fmap toHtml) .         accountTransactionsReportItemAsRecord           oneLineNoCostFmt False           (whichDate $ _rsReportOpts $ reportspec_ copts)

@@ -13,11 +13,10 @@      --cumulative           show running total from report start date   -H --historical           show historical running total/balance (includes                             postings before report start date) (default)-                                  --invert               display all amounts with reversed sign      --heading=YN           show heading row above table: yes (default) or no-  -w --width=N              set output width (default: terminal width or-                            $COLUMNS). -wN,M sets description width as well.+  -w --width=N              set output width (default: terminal width). -wN,M+                            sets description width as well.      --align-all            guarantee alignment across all lines (slower)   -O --output-format=FMT    select the output format. Supported formats:                             txt, html, csv, tsv, json.

@@ -291,7 +291,6 @@ import qualified Data.Text.Lazy.Builder as TB import Data.Time (addDays, fromGregorian) import System.Console.CmdArgs.Explicit as C (flagNone, flagReq, flagOpt)-import Lucid as L hiding (value_) import Safe (headMay, maximumMay) import Text.Tabular.AsciiWide     (Header(..), Align(..), Properties(..), Cell(..), Table(..), TableOpts(..),@@ -305,7 +304,7 @@ import Hledger.Cli.Anchor (setAccountAnchor, dateSpanCell, headerDateSpanCell) import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Write.Ods (printFods)-import Hledger.Write.Html.Lucid (printHtml)+import Hledger.Write.Html (Html, styledTableHtml, htmlAsLazyText, toHtml) import Hledger.Write.Spreadsheet (rawTableContent, headerCell,             addHeaderBorders, addRowSpanHeader,             cellFromMixedAmount, cellsFromMixedAmount)@@ -360,10 +359,10 @@     ,flagReq  ["layout"] (\s opts -> Right $ setopt "layout" s opts) "ARG"       (unlines         ["how to lay out multi-commodity amounts and the overall table:"-        ,"'wide[,WIDTH]': commodities on one line"-        ,"'tall'        : commodities on separate lines"-        ,"'bare'        : commodity symbols in one column"-        ,"'tidy'        : every attribute in its own column"+        ,"'wide[,W]': commodities on same line, up to W wide"+        ,"'tall'    : commodities on separate lines"+        ,"'bare'    : commodity symbols in a separate column"+        ,"'tidy'    : each data field in its own column"         ])      ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "URLPREFIX" "in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.)" @@ -391,8 +390,8 @@             "json" -> (<>"\n") . toJsonText             "csv"  -> printCSV . budgetReportAsCsv ropts             "tsv"  -> printTSV . budgetReportAsCsv ropts-            "html" -> (<>"\n") . L.renderText .-                      printHtml . map (map (fmap L.toHtml)) . budgetReportAsSpreadsheet ropts+            "html" -> (<>"\n") . htmlAsLazyText .+                      styledTableHtml . map (map (fmap toHtml)) . budgetReportAsSpreadsheet ropts             "fods" -> printFods IO.localeEncoding .                       Map.singleton "Budget Report" . (,) (1,0) . budgetReportAsSpreadsheet ropts             _      -> error' $ unsupportedOutputFormatError fmt@@ -404,7 +403,7 @@               "txt"  -> multiBalanceReportAsText ropts               "csv"  -> printCSV . multiBalanceReportAsCsv ropts               "tsv"  -> printTSV . multiBalanceReportAsCsv ropts-              "html" -> (<>"\n") . L.renderText . multiBalanceReportAsHtml ropts+              "html" -> (<>"\n") . htmlAsLazyText . multiBalanceReportAsHtml ropts               "json" -> (<>"\n") . toJsonText               "fods" -> printFods IO.localeEncoding .                         Map.singleton "Multi-period Balance Report" . multiBalanceReportAsSpreadsheet ropts@@ -417,8 +416,8 @@               "txt"  -> TB.toLazyText . balanceReportAsText ropts               "csv"  -> printCSV . balanceReportAsCsv ropts               "tsv"  -> printTSV . balanceReportAsCsv ropts-              "html" -> (<>"\n") . L.renderText .-                                   printHtml . map (map (fmap L.toHtml)) . balanceReportAsSpreadsheet ropts+              "html" -> (<>"\n") . htmlAsLazyText .+                                   styledTableHtml . map (map (fmap toHtml)) . balanceReportAsSpreadsheet ropts               "json" -> (<>"\n") . toJsonText               "fods" -> printFods IO.localeEncoding . Map.singleton "Balance Report" . (,) (1,0) . balanceReportAsSpreadsheet ropts               _      -> error' $ unsupportedOutputFormatError fmt  -- PARTIAL:@@ -685,7 +684,7 @@       _          -> dateHeaders     dateHeaders =       map (headerDateSpanCell balance_base_url_ querystring_) colspans ++-      [hCell "rowtotal" "total" | row_total_] +++      [hCell "rowtotal" "total" | multiBalanceHasTotalsColumn opts] ++       [hCell "rowaverage" "average" | average_]     fullRowAsTexts row =         addRowSpanHeader anchorCell $@@ -709,9 +708,9 @@   -- | Render a multi-column balance report as HTML.-multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html ()+multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html multiBalanceReportAsHtml ropts mbr =-  printHtml . map (map (fmap L.toHtml)) $+  styledTableHtml . map (map (fmap toHtml)) $     snd $ multiBalanceReportAsSpreadsheet ropts mbr  -- | Render the ODS table rows for a MultiBalanceReport.@@ -1120,7 +1119,7 @@               where                 costedAmounts = case conversionop_ of                     Just ToCost -> amounts . mixedAmountCost-                    _           -> amounts+                    _           -> amounts . mixedAmountStripCosts  -- strip any lingering cost info that would prevent unification              -- | Like percentage, but accept multicommodity actual and budget amounts,             -- and extract the specified commodity from both.@@ -1227,7 +1226,7 @@     testGroup "balanceReportAsText" [     testCase "unicode in balance layout" $ do-      j <- readJournal' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"+      j <- readJournal'' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"       let rspec = defreportspec{_rsReportOpts=defreportopts{no_total_=True}}       TB.toLazyText (balanceReportAsText (_rsReportOpts rspec) (balanceReport rspec{_rsDay=fromGregorian 2008 11 26} j))         @?=

@@ -54,10 +54,10 @@      --transpose            switch rows and columns (use vertical time axis)      --layout=ARG           how to lay out multi-commodity amounts and the                             overall table:-                            'wide[,WIDTH]': commodities on one line-                            'tall'        : commodities on separate lines-                            'bare'        : commodity symbols in one column-                            'tidy'        : every attribute in its own column+                            'wide[,W]': commodities on same line, up to W wide+                            'tall'    : commodities on separate lines+                            'bare'    : commodity symbols in a separate column+                            'tidy'    : each data field in its own column      --base-url=URLPREFIX   in html output, generate links to hledger-web,                             with this prefix. (Usually the base url shown by                             hledger-web; can also be relative.)@@ -908,10 +908,6 @@ run the balance command with the extra option --base-url=http://localhost:5000. You can also produce relative links, like --base-url="some/path" or --base-url="".)--The balance reports' HTML output currently does not indent tree mode-reports properly (#1846). So in HTML balance reports, use list mode for-now (it is the default).  Some useful balance reports 

@@ -12,8 +12,6 @@                             market price fluctuations)      --gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      --count                show the count of postings      --change               accumulate amounts from column start to column                             end (in multicolumn reports)

@@ -13,8 +13,6 @@                             market price fluctuations)      --gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      --count                show the count of postings      --change               accumulate amounts from column start to column                             end (in multicolumn reports)

@@ -14,8 +14,6 @@                             market price fluctuations)      --gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      --count                show the count of postings      --change               accumulate amounts from column start to column                             end (in multicolumn reports) (default)

@@ -14,13 +14,12 @@ import qualified Data.Text as T import qualified Data.Text.IO as T import Data.Time.Calendar (addDays)-import Lens.Micro ((^.)) import System.Console.CmdArgs.Explicit as C  import Hledger import Hledger.Cli.CliOptions import Safe (lastDef, readMay, readDef)-import System.FilePath (takeFileName)+import System.FilePath (takeBaseName) import Data.Char (isDigit) import Hledger.Read.RulesReader (parseBalanceAssertionType) import Hledger.Cli.Commands.Print (roundFlag, amountStylesSetRoundingFromRawOpts)@@ -34,18 +33,15 @@  closemode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Close.txt")-  [flagOpt "" ["migrate"]    (\s opts -> Right $ setopt "migrate" s opts) "NEW" ("show closing and opening transactions,"-    <> " for Asset and Liability accounts by default, tagged for easy matching."-    <> " The tag's default value can be overridden by providing NEW."-    )-  ,flagOpt "" ["close"]      (\s opts -> Right $ setopt "close" s opts)  "NEW" "(default) show a closing transaction"-  ,flagOpt "" ["open"]       (\s opts -> Right $ setopt "open" s opts)   "NEW" "show an opening transaction"-  ,flagOpt "" ["assign"]     (\s opts -> Right $ setopt "assign" s opts) "NEW" "show opening balance assignments"-  ,flagOpt "" ["assert"]     (\s opts -> Right $ setopt "assert" s opts) "NEW" "show closing balance assertions"-  ,flagOpt "" ["retain"]     (\s opts -> Right $ setopt "retain" s opts) "NEW" "show a retain earnings transaction, for Revenue and Expense accounts by default"-  ,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly"-  ,flagNone ["show-costs"]   (setboolopt "show-costs") "show amounts with different costs separately"-  ,flagNone ["interleaved"]  (setboolopt "interleaved") "show source and destination postings together"+  [flagOpt "" ["clopen"]     (\s opts -> Right $ setopt "clopen" s opts) "TAGVAL" "show closing and opening balances transactions, for AL accounts by default"+  ,flagOpt "" ["close"]      (\s opts -> Right $ setopt "close" s opts)  "TAGVAL" "show just a closing balances transaction"+  ,flagOpt "" ["open"]       (\s opts -> Right $ setopt "open" s opts)   "TAGVAL" "show just an opening balances transaction"+  ,flagOpt "" ["assert"]     (\s opts -> Right $ setopt "assert" s opts) "TAGVAL" "show a balance assertions transaction"+  ,flagOpt "" ["assign"]     (\s opts -> Right $ setopt "assign" s opts) "TAGVAL" "show a balance assignments transaction"+  ,flagOpt "" ["retain"]     (\s opts -> Right $ setopt "retain" s opts) "TAGVAL" "show a retain earnings transaction, for RX accounts by default"+  ,flagNone ["explicit","x"] (setboolopt "explicit")                              "show all amounts explicitly"+  ,flagNone ["show-costs"]   (setboolopt "show-costs")                            "show amounts with different costs separately"+  ,flagNone ["interleaved"]  (setboolopt "interleaved")                           "show source and destination postings together"   ,flagReq  ["assertion-type"]  (\s opts -> Right $ setopt "assertion-type" s opts) "TYPE" "=, ==, =* or ==*"   ,flagReq  ["close-desc"]   (\s opts -> Right $ setopt "close-desc" s opts) "DESC" "set closing transaction's description"   ,flagReq  ["close-acct"]   (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "set closing transaction's destination account"@@ -58,23 +54,24 @@     ++  -- keep supporting old flag names for compatibility     [flagNone ["closing"]   (setboolopt "close")                                   "old spelling of --close"     ,flagNone ["opening"]   (setboolopt "open")                                    "old spelling of --open"+    ,flagNone ["migrate"]   (setboolopt "clopen")                                  "old spelling of --clopen"     ,flagReq  ["close-to"]  (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "old spelling of --close-acct"     ,flagReq  ["open-from"] (\s opts -> Right $ setopt "open-acct"  s opts) "ACCT" "old spelling of --open-acct"     ]   )-  ([], Just $ argsFlag "[--migrate|--close|--open|--assign|--assert|--retain] [ACCTQUERY]")+  ([], Just $ argsFlag "[--close|--open|--clopen|--assign|--assert|--retain] [ACCTQUERY]")  -- | The close command's mode (subcommand). -- The code depends on these spellings.-data CloseMode = Migrate | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read)+data CloseMode = Clopen | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read) --- | Pick the rightmost flag spelled like a CloseMode (--migrate, --close, --open, etc), or default to Close.+-- | Pick the rightmost flag spelled like a CloseMode (--clopen, --close, --open, etc), or default to Close. closeModeFromRawOpts :: RawOpts -> CloseMode closeModeFromRawOpts rawopts = lastDef Close $ collectopts (\(name,_) -> readMay (capitalise name)) rawopts  -- Debugger, beware: close is incredibly devious; simple rules combine to make a horrid maze. -- Tests are in hledger/test/close.test.-close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do+close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do   let     mode_ = closeModeFromRawOpts rawopts     defacctsq_    = if mode_ == Retain then Type [Revenue, Expense] else Type [Asset, Liability]@@ -86,15 +83,16 @@     tagval = fromMaybe "" $ maybestringopt modeflag rawopts where modeflag = lowercase $ show mode_     comment = T.pack $ if       | mode_ == Assert -> "assert:" <> tagval+      | mode_ == Assign -> "assign:" <> tagval       | mode_ == Retain -> "retain:" <> tagval-      | otherwise       -> "start:"  <> if null tagval then inferredval else tagval+      | otherwise       -> "clopen:" <> if null tagval then inferredval else tagval       where-        inferredval = newfilename+        inferredval = newfilebasename           where-            oldfilename = takeFileName $ journalFilePath j-            (nonnum, rest) = break isDigit $ reverse oldfilename+            oldfilebasename = takeBaseName $ journalFilePath j+            (nonnum, rest) = break isDigit $ reverse oldfilebasename             (oldnum, rest2) = span isDigit rest-            newfilename = case oldnum of+            newfilebasename = case oldnum of               [] -> ""               _  -> reverse rest2 <> newnum <> reverse nonnum                 where@@ -119,7 +117,7 @@     opendate = addDays 1 closedate      -- should we show the amount(s) on the equity posting(s) ?-    explicit = boolopt "explicit" rawopts || copts ^. infer_costs+    explicit = boolopt "explicit" rawopts      -- the accounts to close     argsacctq = filterQuery (\q -> queryIsAcct q || queryIsType q) argsq@@ -147,7 +145,7 @@      -- the closing (balance-asserting or balance-zeroing) transaction     mclosetxn-      | mode_ `notElem` [Migrate, Close, Assert, Retain] = Nothing+      | mode_ `notElem` [Clopen, Close, Assert, Retain] = Nothing       | otherwise = Just nulltransaction{           tdate=closedate, tdescription=closedesc, tcomment=comment, tpostings=closeps           }@@ -162,7 +160,7 @@           -- XXX some duplication           | mode_ == Assert =             [ posting{-                  paccount          = a+                   paccount          = a                   ,pamount           = mixedAmount $ precise b{aquantity=0, acost=Nothing}                   -- after each commodity's last posting, assert 0 balance (#1035)                   -- balance assertion amounts are unpriced (#824)@@ -210,7 +208,7 @@      -- the opening (balance-assigning or balance-unzeroing) transaction     mopentxn-      | mode_ `notElem` [Migrate, Open, Assign] = Nothing+      | mode_ `notElem` [Clopen, Open, Assign] = Nothing       | otherwise = Just nulltransaction{           tdate=opendate, tdescription=opendesc, tcomment=comment, tpostings=openps           }

@@ -2,24 +2,21 @@  (equity) -close generates several kinds of "closing" and/or "opening"-transactions, useful in certain situations, including migrating balances-to a new journal file, retaining earnings into equity, consolidating-balances, or viewing lots. Like print, it prints valid journal entries.-You can append or copy these to your journal file(s) when you are happy-with how they look.+close prints several kinds of "closing" and/or "opening" transactions,+useful in various situations: migrating balances to a new journal file,+retaining earnings into equity, consolidating balances, viewing lot+costs.. Like print, it prints valid journal entries. You can copy these+into your journal file(s) when you are happy with how they look.  Flags:-     --migrate[=NEW]        show closing and opening transactions, for Asset-                            and Liability accounts by default, tagged for easy-                            matching. The tag's default value can be overridden-                            by providing NEW.-     --close[=NEW]          (default) show a closing transaction-     --open[=NEW]           show an opening transaction-     --assign[=NEW]         show opening balance assignments-     --assert[=NEW]         show closing balance assertions-     --retain[=NEW]         show a retain earnings transaction, for Revenue-                            and Expense accounts by default+     --clopen[=TAGVAL]      show closing and opening balances transactions,+                            for AL accounts by default+     --close[=TAGVAL]       show just a closing balances transaction+     --open[=TAGVAL]        show just an opening balances transaction+     --assert[=TAGVAL]      show a balance assertions transaction+     --assign[=TAGVAL]      show a balance assignments transaction+     --retain[=TAGVAL]      show a retain earnings transaction, for RX+                            accounts by default   -x --explicit             show all amounts explicitly      --show-costs           show amounts with different costs separately      --interleaved          show source and destination postings together@@ -31,94 +28,109 @@      --round=TYPE           how much rounding or padding should be done when                             displaying amounts ?                             none - show original decimal digits,-                                   as in journal+                                   as in journal (default)                             soft - just add or remove decimal zeros-                                   to match precision (default)+                                   to match precision                             hard - round posting amounts to precision                                    (can unbalance transactions)                             all  - also round cost amounts to precision                                    (can unbalance transactions) -close currently has six modes, selected by a single mode flag:+close has six modes, selected by choosing one of the mode flags (--close+is the default). They all do much the same operation, but with different+defaults, useful in different situations. -close --migrate+close --clopen -This is the most common mode. It prints a "closing balances" transaction-that zeroes out all asset and liability balances (by default), and an-opposite "opening balances" transaction that restores them again. The-balancing account will be equity:opening/closing balances (or another-specified by --close-acct or --open-acct).+This is useful if migrating balances to a new journal file at the start+of a new year. It prints a "closing balances" transaction that zeroes+out account balances (Asset and Liability accounts, by default), and an+opposite "opening balances" transaction that restores them again.+Typically, you would run -This is useful when migrating balances to a new journal file at the-start of a new year. Essentially, you run-hledger close --migrate=NEWYEAR -e NEWYEAR and then copy the closing-transaction to the end of the old file and the opening transaction to-the start of the new file. The opening transaction sets correct starting-balances in the new file when it is used alone, and the closing-transaction keeps balances correct when you use both old and new files-together, by cancelling out the following opening transaction and-preventing buildup of duplicated opening balances. Think of the-closing/opening pair as "moving the balances into the next file".+hledger close --clopen -e NEWYEAR >> $LEDGER_FILE -You can close a different set of accounts by providing a query. Eg if-you want to include equity, you can add assets liabilities equity or-type:ALE arguments. (The balancing account is always excluded.) Revenues-and expenses usually are not migrated to a new file directly; see---retain below.+and then move the opening transaction from the old file to the new file+(and probably also update your LEDGER_FILE environment variable). -The generated transactions will have a start: tag, with its value set to---migrate's NEW argument if any, for easier matching or exclusion. When-NEW is not specified, it will be inferred if possible by incrementing a-number (eg a year number) within the default journal's main file name.-The other modes behave similarly.+Why might you do this ? If your reports are fast, you may not need it.+But at some point you will probably want to partition your data by time,+for performance or data integrity or regulatory reasons. A new file or+set of files per year is common. Then, having each file/fileset+"bookended" with opening and closing balance transactions will allow you+to freely pick and choose which files to read - just the current year,+any past year, any sequence of years, or all of them - while showing+correct account balances in each case. The earliest opening balances+transaction sets correct starting balances, and any later+closing/opening pairs will harmlessly cancel each other out. +The balances will be transferred to and from+equity:opening/closing balances by default. You can override this by+using --close-acct and/or --open-acct.++You can select a different set of accounts to close/open by providing an+account query. Eg to add Equity accounts, provide arguments like+assets liabilities equity or type:ALE. When migrating to a new file,+you'll usually want to bring along the AL or ALE accounts, but not the+RX accounts (Revenue, Expense).++Assertions will be added indicating and checking the new balances of the+closed/opened accounts.++The generated transactions will have a clopen: tag. If the main+journal's base file name contains a number (eg a year number), the tag's+value will be that base file name with the number incremented. Or you+can choose the tag value yourself, by using --clopen=TAGVAL.+ close --close -This prints just the closing balances transaction of --migrate. It is-the default behaviour if you specify no mode flag. Using the-customisation options below, you can move balances from any set of-accounts to a different account.+This prints just the closing balances transaction of --clopen. It is the+default if you don't specify a mode. +More customisation options are described below. Among other things, you+can use close --close to generate a transaction moving the balances from+any set of accounts, to a different account. (If you need to move just a+portion of the balance, see hledger-move.)+ close --open -This prints just the opening balances transaction of --migrate. It is-similar to Ledger's equity command.+This prints just the opening balances transaction of --clopen. (It is+similar to Ledger's equity command.)  close --assert -This prints a "closing balances" transaction (with balances: tag), that-just declares balance assertions for the current balances without-changing them. It could be useful as documention and to guard against-changes.+This prints a transaction that asserts the account balances as they are+on the end date (and adds an assert: tag). It could be useful as+documention and to guard against changes.  close --assign -This prints an "opening balances" transaction that restores the account-balances using balance assignments. Balance assignments work regardless-of any previous balance, so a preceding closing balances transaction is-not needed.+This prints a transaction that assigns the account balances as they are+on the end date (and adds an "assign:" tag). Unlike balance assertions,+assignments will post changes to balances as needed to reach the+specified amounts. -However, omitting the closing balances transaction would unbalance-equity. This is relatively harmless for personal reports, but it-disturbs the accounting equation, removing a source of error detection.-So --migrate is generally the best way to set to set balances in new-files, for now.+This is another way to set starting balances when migrating to a new+file, and it will set them correctly even in the presence of earlier+files which do not have a closing balances transaction. However, it can+hide errors, and disturb the accounting equation, so --clopen is usually+recommended.  close --retain -This is like --close with different defaults: it prints a "retain-earnings" transaction (with retain: tag), that transfers revenue and-expense balances to equity:retained earnings.+This is like --close, but it closes Revenue and Expense account balances+by default. They will be transferred to equity:retained earnings, or+another account specified with --close-acct. -This is a different kind of closing, called "retaining earnings" or-"closing the books"; it is traditionally performed by businesses at the-end of each accounting period, to consolidate revenues and expenses into-the main equity balance. ("Revenues" and "expenses" are actually equity-by another name, kept separate temporarily for reporting purposes.)+Revenues and expenses correspond to changes in equity. They are+categorised separately for reporting purposes, but traditionally at the+end of each accounting period, businesses consolidate them into equity,+This is called "retaining earnings", or "closing the books". -In personal accounting you generally don't need to do this, unless you-want the balancesheetequity report to show a zero total, demonstrating-that the accounting equation (A-L=E) is satisfied.+In personal accounting, there's not much reason to do this, and most+people don't. (One reason to do it is to help the balancesheetequity+report show a zero total, demonstrating that the accounting equation+(A-L=E) is satisfied.)  close customisation @@ -207,7 +219,7 @@  Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: -$ hledger close --migrate -f 2022.journal -p 2022+$ hledger close --clopen -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 @@ -217,14 +229,14 @@ $ hledger -f 2022.journal bs not:desc:'closing balances'  For more flexibility, it helps to tag closing and opening transactions-with eg start:NEWYEAR, then you can ensure correct balances by excluding-all opening/closing transactions except the first, like so:+with eg clopen:NEWYEAR, then you can ensure correct balances by+excluding all opening/closing transactions except the first, like so: -$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'-$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:start=2021 or not tag:start'-$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:start=2022 or not tag:start'-$ hledger bs -Y -f 2021.j                     expr:'tag:start=2021 or not tag:start'-$ hledger bs -Y -f 2022.j                     expr:'tag:start=2022 or not tag:start'+$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'+$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:clopen=2021 or not tag:clopen'+$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:clopen=2022 or not tag:clopen'+$ hledger bs -Y -f 2021.j                     expr:'tag:clopen=2021 or not tag:clopen'+$ hledger bs -Y -f 2022.j                     expr:'tag:clopen=2022 or not tag:clopen' $ hledger bs -Y -f 2023.j                     # unclosed file, no query needed  More detailed close examples

@@ -0,0 +1,6 @@+commands++Show the hledger commands list.++Flags:+     --builtin             show only builtin commands, not addons

@@ -26,3 +26,5 @@ $ 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++This command is experimental: there aren't many useful demos yet.

@@ -13,8 +13,6 @@                             market price fluctuations)      --gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      --count                show the count of postings      --change               accumulate amounts from column start to column                             end (in multicolumn reports) (default)

@@ -37,7 +37,7 @@ import Hledger.Write.Beancount (accountNameToBeancount, showTransactionBeancount, showBeancountMetadata) import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Write.Ods (printFods)-import Hledger.Write.Html.Lucid (printHtml)+import Hledger.Write.Html.Lucid (styledTableHtml) import qualified Hledger.Write.Spreadsheet as Spr import Hledger.Cli.CliOptions import Hledger.Cli.Utils@@ -54,6 +54,7 @@   ,flagNone ["show-costs"] (setboolopt "show-costs")     "show transaction prices even with conversion postings"   ,roundFlag+  ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign"   ,flagNone ["new"] (setboolopt "new")     "show only newer-dated transactions added in each file since last run"   ,let arg = "DESC" in@@ -71,9 +72,9 @@   intercalate "\n"   ["how much rounding or padding should be done when displaying amounts ?"   ,"none - show original decimal digits,"-  ,"       as in journal"+  ,"       as in journal (default)"   ,"soft - just add or remove decimal zeros"-  ,"       to match precision (default)"+  ,"       to match precision"   ,"hard - round posting amounts to precision"   ,"       (can unbalance transactions)"   ,"all  - also round cost amounts to precision"@@ -142,7 +143,7 @@            | fmt=="json"      = toJsonText                    . styleAmounts styles            | fmt=="sql"       = entriesReportAsSql            . styleAmounts styles            | fmt=="html" =-                (<>"\n") . Lucid.renderText . printHtml .+                (<>"\n") . Lucid.renderText . styledTableHtml .                 map (map (fmap Lucid.toHtml)) .                 entriesReportAsSpreadsheet oneLineNoCostFmt baseUrl query .                 styleAmounts styles@@ -158,6 +159,7 @@           -- with -x/--explicit:           | boolopt "explicit" (rawopts_ opts) = id           -- with --show-costs:+          -- XXX infer_costs is --infer-costs not --show-costs. And where is show-costs used anyway ?           | 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

@@ -9,13 +9,14 @@      --round=TYPE           how much rounding or padding should be done when                             displaying amounts ?                             none - show original decimal digits,-                                   as in journal+                                   as in journal (default)                             soft - just add or remove decimal zeros-                                   to match precision (default)+                                   to match precision                             hard - round posting amounts to precision                                    (can unbalance transactions)                             all  - also round cost amounts to precision                                    (can unbalance transactions)+     --invert               display all amounts with reversed sign      --new                  show only newer-dated transactions added in each                             file since last run   -m --match=DESC           fuzzy search for one recent transaction with@@ -117,6 +118,10 @@ print, other features  With -B/--cost, amounts with costs are shown converted to cost.++With --invert, posting amounts are shown with their sign flipped. It+could be useful if you have accidentally recorded some transactions with+the wrong signs.  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

@@ -31,7 +31,7 @@ import Hledger hiding (per) import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Write.Ods (printFods)-import Hledger.Write.Html.Lucid (printHtml)+import Hledger.Write.Html.Lucid (styledTableHtml) import qualified Hledger.Write.Spreadsheet as Spr import Hledger.Cli.CliOptions import Hledger.Cli.Utils@@ -67,7 +67,7 @@ #else       "terminal width" #endif-      ++ " or $COLUMNS). -wN,M sets description width as well."+      ++ "). -wN,M sets description width as well."      )   ,flagNone ["align-all"] (setboolopt "align-all") "guarantee alignment across all lines (slower)"   ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "URLPREFIX" "in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.)"@@ -103,7 +103,7 @@            | fmt=="csv"  = printCSV . postingsReportAsCsv            | fmt=="tsv"  = printTSV . postingsReportAsCsv            | fmt=="html" =-                (<>"\n") . Lucid.renderText . printHtml .+                (<>"\n") . Lucid.renderText . styledTableHtml .                 map (map (fmap Lucid.toHtml)) .                 postingsReportAsSpreadsheet oneLineNoCostFmt baseUrl query            | fmt=="fods" =@@ -304,7 +304,7 @@     testGroup "postingsReportAsText" [     testCase "unicode in register layout" $ do-      j <- readJournal' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"+      j <- readJournal'' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"       let rspec = defreportspec       (TL.unpack . postingsReportAsText defcliopts $ postingsReport rspec j)         @?=

@@ -18,8 +18,8 @@      --sort=FIELDS          sort by: date, desc, account, amount, absamount,                             or a comma-separated combination of these. For a                             descending sort, prefix with -. (Default: date)-  -w --width=N              set output width (default: terminal width or-                            $COLUMNS). -wN,M sets description width as well.+  -w --width=N              set output width (default: terminal width). -wN,M+                            sets description width as well.      --align-all            guarantee alignment across all lines (slower)      --base-url=URLPREFIX   in html output, generate links to hledger-web,                             with this prefix. (Usually the base url shown by@@ -132,9 +132,8 @@  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.+register normally uses the full terminal width (or 80 columns if it+can't detect that). You can override this with 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@@ -149,10 +148,7 @@  $ 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 (Added in 1.32),

@@ -0,0 +1,67 @@+repl++Start an interactive prompt, where you can run any of hledger's+commands. Data files are parsed just once, so the commands run faster.++Flags:+no command-specific flags++This command is experimental and could change in the future.++hledger repl starts a read-eval-print loop (REPL) where you can enter+commands interactively. As with the run command, each input file (or+each input file/input options combination) is parsed just once, so+commands will run more quickly than if you ran them individually at the+command line.++Also like run, the input file(s) specified for the repl command will be+the default input for all interactive commands, you can override this+temporarily by specifying an -f option in particular commands, and+commands will not see any changes made to input files (eg by add) until+you exit and restart the REPL.++The command syntax is the same as with run:++-   enter one hledger command at a time, without the usual hledger first+    word+-   empty lines and comment text from # to end of line are ignored+-   use single or double quotes to quote arguments when needed+-   type exit or quit or control-D to exit the REPL.++While it is running, the REPL remembers your command history, and you+can navigate in the usual ways: - Keypad or Emacs navigation keys to+edit the current command line - UP/DOWN or control-P/control-N to step+back/forward through history - control-R to search for a past command,+etc.++The commands and help commands, and the command help flags (CMD --tldr,+CMD -h/--help, CMD --info, CMD --man), work in the usual way, and can be+useful.++You can type control-C to cancel a long-running command (but only once;+typing it a second time will exit the REPL).++And in most shells you can type control-Z to exit temporarily to the+shell (and fg to return to the REPL).++Caveats++You may find some differences in behaviour between run command lines and+normal hledger command lines. For example, in the REPL,++-   the command name must be written first, options afterward+-   full command names or official abbreviations (as in the command+    list) must be used+-   options parsing with addon commands might be less flexible than the+    CLI+-   the stats command gives false timings, currently++Examples++Start the REPL:++hledger repl++or++hledger repl -f some.journal

@@ -20,14 +20,13 @@ import Data.Time.Calendar import Text.Printf import Data.Bifunctor (second)-import Data.Either (fromLeft, fromRight, isLeft) import Data.Function (on) import Data.List import Numeric.RootFinding import Data.Decimal import qualified Data.Text as T import qualified Data.Text.Lazy.IO as TL-import Safe (headDef, tailDef)+import Safe (headDef, lastMay) import System.Console.CmdArgs.Explicit as CmdArgs  import Text.Tabular.AsciiWide as Tab@@ -99,8 +98,6 @@    let (fullPeriod, spans) = reportSpan filteredj rspec -  let priceDirectiveDates = dbg3 "priceDirectiveDates" $ map pddate $ jpricedirectives j-   let processSpan (DateSpan Nothing _) = error "Undefined start of the period - will be unable to compute the rates of return"       processSpan (DateSpan _ Nothing) = error "Undefined end of the period - will be unable to compute the rates of return"       processSpan spn@(DateSpan (Just begin) (Just end)) = do@@ -120,9 +117,7 @@             total trans (And [investmentsQuery                              , Date (DateSpan Nothing (Just end))]) -          priceDates = dbg3 "priceDates" $ nub $ filter (spanContainsDate spn) priceDirectiveDates-          cashFlow =-            ((map (,nullmixedamt) priceDates)++) $+          cashFlow = dbg3 "cashFlow" $             cashFlowApplyCostValue $             calculateCashFlow wd trans (And [ Not investmentsQuery                                             , Not pnlQuery@@ -159,7 +154,9 @@                , T.pack $ printf "%0.2f%%" $ smallIsZero annualizedTwr ]    periodRows <- forM spans processSpan-  totalRow <- processSpan fullPeriod+  totalRow <- case periodRows of+    [singleRow] -> return singleRow+    _           -> processSpan fullPeriod    let rowTitles = Tab.Group Tab.NoLine (map (Header . T.pack . show) (take (length periodRows) [1..])) @@ -179,116 +176,116 @@    TL.putStrLn $ Tab.render prettyTables id id id table -timeWeightedReturn styles showCashFlow prettyTables investmentsQuery trans mixedAmountValue (OneSpan begin end valueBeforeAmt valueAfter cashFlow pnl) = do-  let valueBefore = unMix valueBeforeAmt-  let initialUnitCost = 100 :: Decimal-  let initialUnits = valueBefore / initialUnitCost-  let changes =-        -- If cash flow and PnL changes happen on the same day, this-        -- will sort PnL changes to come before cash flows (on any-        -- given day), so that we will have better unit price computed-        -- first for processing cash flow. This is why pnl changes are Left-        -- and cashflows are Right.-        -- However, if the very first date in the changes list has both-        -- PnL and CashFlow, we would not be able to apply pnl change to 0 unit,-        -- which would lead to an error. We make sure that we have at least one-        -- cashflow entry at the front, and we know that there would be at most-        -- one for the given date, by construction. Empty CashFlows added-        -- because of a begin date before the first transaction are not seen as-        -- a valid cashflow entry at the front.-        zeroUnitsNeedsCashflowAtTheFront+-- Entry for TWR computation, capturing all cashflows that are potentially accompanied by pnl change on the same day (if not, it is zero)+data TwrEntry = TwrEntry { twrDate :: Day, twrCashflow :: Decimal, twrValueAfter :: Decimal, twrPnl :: Decimal } deriving (Eq, Show)++timeWeightedReturn _styles showCashFlow prettyTables investmentsQuery trans mixedAmountValue (OneSpan begin end valueBeforeAmt valueAfterAmt cashflows pnls) = do+  let datedCashflows =+        -- Aggregate all entries for a single day, assuming that intraday interest is negligible+        dbg3 "datedCashflows"         $ sort-        $ datedCashflows ++ datedPnls-        where-          zeroUnitsNeedsCashflowAtTheFront changes1 =-            if initialUnits > 0 then changes1-            else-              let (leadingEmptyCashFlows, rest) = span isEmptyCashflow changes1-                  (leadingPnls, rest') = span (isLeft . snd) rest-                  (firstCashflow, rest'') = splitAt 1 rest'-              in leadingEmptyCashFlows ++ firstCashflow ++ leadingPnls ++ rest''+        $ map (\datecashes -> let (dates, cash) = unzip datecashes in (headDef (error' "Roi.hs: datecashes was null, please report a bug") dates, maSum cash))+        $ groupBy ((==) `on` fst)+        $ sortOn fst+        $ map (second maNegate)+        $ cashflows -          isEmptyCashflow (_date, amt) = case amt of-            Right amt' -> mixedAmountIsZero amt'-            Left _     -> False+      valueBefore = unMix valueBeforeAmt+      valueAfter = unMix valueAfterAmt+      +      investmentPostings = concatMap (filter (matchesPosting investmentsQuery) . realPostings) trans -          datedPnls = map (second Left) $ aggregateByDate pnl+      totalInvestmentPostingsTill date = sumPostings $ filter (matchesPosting (Date (DateSpan Nothing (Just $ Exact date)))) investmentPostings -          datedCashflows = map (second Right) $ aggregateByDate cashFlow+      -- filter span is (-infinity, date+1), which gives us effectively (-infinity, date]+      valueAfterDate date = unMix $ mixedAmountValue end date $ totalInvestmentPostingsTill (addDays 1 date) -          aggregateByDate datedAmounts =-            -- Aggregate all entries for a single day, assuming that intraday interest is negligible-            sort-            $ map (\datecashes -> let (dates, cash) = unzip datecashes in (headDef (error' "Roi.hs: datecashes was null, please report a bug") dates, maSum cash))-            $ groupBy ((==) `on` fst)-            $ sortOn fst-            $ map (second maNegate)-            $ datedAmounts+      -- We are dividing the period [begin, end) into subperiods on each cashflow, and then compute+      -- the rate of return for each subperiod. For this we need to know the value of the investment+      -- at the beginning and end of each subperiod, adjusted for cashflow.+      -- +      -- Subperiods are going to be [valueBefore ... (c_0,v_0)][... (c_1, v_1)][... (c_2,v_2)] ... [... (c_n,v_n)][... valueAfter]+      -- , where v_i is the value of investment computed immediately after cashflow c_i+      addEnd cflows =+        case lastMay cflows of+          Nothing -> cflows+          Just entry ->+            let end_ = addDays (-1) end in+              if twrDate entry < end_ then cflows++[TwrEntry end_ 0 valueAfter (pnlOn end_)] else cflows -  let units =-        tailDef (error' "Roi.hs units was null, please report a bug") $-        scanl-          (\(_, _, unitCost, unitBalance) (date, amt) ->-             let valueOnDate = unMix $ mixedAmountValue end date $ total trans (And [investmentsQuery, Date (DateSpan Nothing (Just $ Exact date))])-             in-             case amt of-               Right amt' ->-                 -- we are buying or selling-                 let unitsBoughtOrSold = unMix amt' / unitCost-                 in (valueOnDate, unitsBoughtOrSold, unitCost, unitBalance + unitsBoughtOrSold)-               Left pnl' ->-                 -- PnL change-                 let valueAfterDate = valueOnDate + unMix pnl'-                     unitCost' =-                       if unitBalance == 0 then initialUnitCost -- everything was sold, let's reset the cost to initial cost-                       else valueAfterDate/unitBalance-                 in (valueOnDate, 0, unitCost', unitBalance))-          (0, 0, initialUnitCost, initialUnits)-          $ dbg3 "changes" changes+      pnlOn date = unMix $ maNegate $ sum $ map snd $ filter ((==date).fst) pnls -  let finalUnitBalance = if null units then initialUnits else let (_,_,_,u) = last units in u-      finalUnitCost = if finalUnitBalance == 0 then-                         if null units then initialUnitCost-                         else let (_,_,lastUnitCost,_) = last units in lastUnitCost-                       else (unMix valueAfter) / finalUnitBalance-      -- Technically, totalTWR should be (100*(finalUnitCost - initialUnitCost) / initialUnitCost), but initalUnitCost is 100, so 100/100 == 1-      totalTWR = roundTo 2 $ (finalUnitCost - initialUnitCost)+      twrEntries =+        dbg3 "twrEntries"+        $ addEnd+        $ concatMap (\(date,cashflow) ->+                        let pnl = pnlOn date+                            cash = unMix cashflow+                            value_ = valueAfterDate date - pnl - cash -- valueAfterDate includes both cashflow and pnl on date, if any+                        in+                        -- if we had PnL postings on the same day as cashflow,+                        -- we want to account for them separately. If pnl is positive, we apply pnl first, and if pnl was negative+                        -- we apply cashflow first, in an attempt to avoid having negative valuations and ugly debug output (and+                        -- computations as well)+                        if pnl == 0 then [TwrEntry date cash (value_ + cash) 0]+                        else if pnl > 0  +                             then [TwrEntry date 0 (value_ + pnl)   pnl, TwrEntry date cash (value_ + cash + pnl) 0]+                             else [TwrEntry date cash (value_ + cash) 0, TwrEntry date 0    (value_ + cash + pnl) pnl]+                    ) datedCashflows++  -- Calculate interest for each subperiod, adjusting the value at the start of the period by the cashflow+  -- For subperiods [valueBefore ... (c_0,v_0)][... (c_1, v_1)][... (c_2,v_2)] ... [... (c_n,v_n)][... valueAfter], the computation is going to be+  -- 1 + twr = (v_0 - c_0)/valueBefore + (v_1 - c_1) / v_0 +  ... + valueAfter/v_n+  -- See https://en.wikipedia.org/wiki/Time-weighted_return#Time-weighted_return_compensating_for_external_flows+  let calculateSubPeriods _ [] = []+      calculateSubPeriods  prev (curr:rest) =+        let adjustedEnd = twrValueAfter curr - twrCashflow curr in+          let subPeriodReturn =+                if twrValueAfter prev == 0 || adjustedEnd == 0+                then 1+                else adjustedEnd / (twrValueAfter prev)+          in (subPeriodReturn, (prev, curr)) : calculateSubPeriods curr rest++  let subPeriods = dbg3 "subPeriods" $ calculateSubPeriods (TwrEntry begin 0 valueBefore (pnlOn begin)) twrEntries++  -- Compute overall time-weighted rate of return+  let twr =+        dbg3 "twr" $+        if subPeriods == []+        then if valueBefore == 0 then 0 else (valueAfter - valueBefore)/valueBefore+        else (product $ map fst subPeriods) - 1       (startYear, _, _) = toGregorian begin       years = fromIntegral (diffDays end begin) / (if isLeapYear startYear then 366 else 365) :: Double-      annualizedTWR = 100*((1+(realToFrac totalTWR/100))**(1/years)-1) :: Double+      periodTWR = roundTo 2 $ 100 * twr+      annualizedTWR = 100*((1+(realToFrac twr))**(1/years)-1) :: Double    when showCashFlow $ do-    printf "\nTWR cash flow for %s - %s\n" (showDate begin) (showDate (addDays (-1) end))-    let (dates', amts) = unzip changes-        cashflows' = map (fromRight nullmixedamt) amts-        pnls = map (fromLeft nullmixedamt) amts-        (valuesOnDate,unitsBoughtOrSold', unitPrices', unitBalances') = unzip4 units-        add x lst = if valueBefore/=0 then x:lst else lst-        dates = add begin dates'-        cashflows = add valueBeforeAmt cashflows'-        unitsBoughtOrSold = add initialUnits unitsBoughtOrSold'-        unitPrices = add initialUnitCost unitPrices'-        unitBalances = add initialUnits unitBalances'--    TL.putStr $ Tab.render prettyTables id id T.pack+    printf "\nTWR cash flow entries and subperiod rates for period %s - %s\n" (showDate begin) (showDate (addDays (-1) end))+    let showDecimalT = T.pack . showDecimal+    let dates = map twrDate twrEntries+    TL.putStrLn $ Tab.render prettyTables id id id       (Table-       (Tab.Group NoLine (map (Header . showDate) dates))-       (Tab.Group DoubleLine [ Tab.Group Tab.SingleLine [Tab.Header "Portfolio value", Tab.Header "Unit balance"]-                         , Tab.Group Tab.SingleLine [Tab.Header "Pnl", Tab.Header "Cashflow", Tab.Header "Unit price", Tab.Header "Units"]-                         , Tab.Group Tab.SingleLine [Tab.Header "New Unit Balance"]])-       [ [val, oldBalance, pnl', cashflow, prc, udelta, balance]-       | val <- map showDecimal valuesOnDate-       | oldBalance <- map showDecimal (0:unitBalances)-       | balance <- map showDecimal unitBalances-       | pnl' <- map (showMixedAmountOneLineWithoutCost False . styleAmounts styles) pnls-       | cashflow <- map (showMixedAmountOneLineWithoutCost False . styleAmounts styles) cashflows-       | prc <- map showDecimal unitPrices-       | udelta <- map showDecimal unitsBoughtOrSold ])+       (Tab.Group Tab.NoLine (map (Header . showDate) dates))+       (Tab.Group Tab.SingleLine [Header "Amount", Header "PnL on this day", Header "Value afterwards" ])+       ( [ [ showDecimalT (twrCashflow e), showDecimalT (twrPnl e), showDecimalT (twrValueAfter e) ]+         | e <- twrEntries ]))+    +    TL.putStr $ Tab.render prettyTables T.pack id id+      (Table+       (Tab.Group Tab.NoLine [ Header (show n) | n <-[1..length subPeriods]])+       (Tab.Group DoubleLine [ Tab.Group Tab.SingleLine [Tab.Header "Subperiod start", Tab.Header "Subperiod end"]+                             , Tab.Group Tab.SingleLine [Tab.Header "Value at start", Tab.Header "Cashflow", Tab.Header "PnL postings", Tab.Header "Value at end"]+                             , Tab.Group Tab.SingleLine [Tab.Header "Subperiod return rate"]])+       [ [ showDate (twrDate prev), showDate (twrDate curr)+         , showDecimalT (twrValueAfter prev - twrCashflow prev), showDecimalT (twrCashflow prev), showDecimalT (twrPnl prev), showDecimalT (twrValueAfter curr - twrCashflow curr)+         , showDecimalT rate ]+       | (rate, (prev, curr)) <-  subPeriods+       ]) -    printf "Final unit price: %s/%s units = %s\nTotal TWR: %s%%.\nPeriod: %.2f years.\nAnnualized TWR: %.2f%%\n\n"-      (showMixedAmountOneLineWithoutCost False $ styleAmounts styles valueAfter) (showDecimal finalUnitBalance) (showDecimal finalUnitCost) (showDecimal totalTWR) years annualizedTWR+    printf "Total period TWR: %s%%.\nPeriod: %.2f years.\nAnnualized TWR: %.2f%%\n\n"+      (showDecimal periodTWR) years annualizedTWR -  return ((realToFrac totalTWR) :: Double, annualizedTWR)+  return ((realToFrac periodTWR) :: Double, annualizedTWR)  internalRateOfReturn styles showCashFlow prettyTables (OneSpan begin end valueBefore valueAfter cashFlow _pnl) = do   let prefix = (begin, maNegate valueBefore)

@@ -0,0 +1,260 @@+{-|++The @run@ command allows you to run multiple commands via REPL or from the supplied file(s).++-}++{-# LANGUAGE MultiWayIf #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE ScopedTypeVariables #-}+{-# LANGUAGE TemplateHaskell #-}++module Hledger.Cli.Commands.Run (+  runmode+ ,run+ ,replmode+ ,repl+ ,runOrReplStub+) where++import qualified Data.List.NonEmpty as NE+import qualified Data.Map.Strict as Map+import Data.Semigroup (sconcat)+import qualified Data.Text as T+import qualified Data.Text.IO as T+import System.Console.CmdArgs.Explicit as C ( Mode )+import Hledger+import Hledger.Cli.CliOptions++import Control.Exception+import Control.Concurrent.MVar+import Control.Monad (forM_)+import Control.Monad.IO.Class (liftIO)+import Control.Monad.Extra (concatMapM)++import System.Exit (ExitCode, exitWith)+import System.Console.CmdArgs.Explicit (expandArgsAt, modeNames)+import System.IO (stdin, hIsTerminalDevice, hIsOpen)+import System.IO.Unsafe (unsafePerformIO)+import System.Console.Haskeline++import Safe (headMay)+import Hledger.Cli.DocFiles (runTldrForPage, runInfoForTopic, runManForTopic)+import Hledger.Cli.Utils (journalTransform)+import Text.Printf (printf)+import System.Process (system)++-- | Command line options for this command.+runmode = hledgerCommandMode+  $(embedFileRelative "Hledger/Cli/Commands/Run.txt")+  (+  []+  )+  cligeneralflagsgroups1+  hiddenflags+  ([], Just $ argsFlag "[COMMANDS_FILE1 COMMANDS_FILE2 ...] OR [-- command1 args... -- command2 args... -- command3 args...]")++replmode = hledgerCommandMode+  $(embedFileRelative "Hledger/Cli/Commands/Repl.txt")+  (+  []+  )+  cligeneralflagsgroups1+  hiddenflags+  ([], Nothing)++-- | The fake run/repl command introduced to break circular dependency.+-- This module needs access to `findBuiltinCommand`, which is defined in Hledger.Cli.Commands+-- However, Hledger.Cli.Commands imports this module, which creates circular dependency.+-- We expose this do-nothing function so that it could be included in the list of all commands inside+-- Hledger.Cli.Commands and ensure that "run" is recognized as a valid command by the Hledger.Cli top-level+-- command line parser. That parser, however, would not call run'. It has a special case for "run", and+-- will call "run" (see below), passing it `findBuiltinCommand`, thus breaking circular dependency.+runOrReplStub :: CliOpts -> Journal -> IO ()+runOrReplStub _opts _j = return ()++-- | Default input files that would be used by commands if+--   there is no explicit alternative given+newtype DefaultRunJournal = DefaultRunJournal (NE.NonEmpty String) deriving (Show)++-- | The actual run command.+run :: Maybe DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> CliOpts -> IO ()+run defaultJournalOverride findBuiltinCommand addons cliopts@CliOpts{rawopts_=rawopts} = do+  withJournalCached defaultJournalOverride cliopts $ \(_,key) -> do+    let args = dbg1 "args" $ listofstringopt "args" rawopts+    isTerminal <- isStdinTerminal+    if args == [] && not isTerminal+      then do+        inputFiles <- journalFilePathFromOpts cliopts+        let journalFromStdin = any (== "-") $ map (snd . splitReaderPrefix) $ NE.toList inputFiles+        if journalFromStdin+        then error' "'run' can't read commands from stdin, as one of the input files was stdin as well"+        else runREPL key findBuiltinCommand addons+      else do+        -- Check if arguments start with "--".+        -- If not, assume that they are files with commands+          case args of+            "--":_ -> runFromArgs  key findBuiltinCommand addons args+            _      -> runFromFiles key findBuiltinCommand addons args++-- | The actual repl command.+repl :: (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> CliOpts -> IO ()+repl findBuiltinCommand addons cliopts = do+  withJournalCached Nothing cliopts $ \(_,key) -> do+    runREPL key findBuiltinCommand addons++-- | Run commands from files given to "run".+runFromFiles :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> [String] -> IO ()+runFromFiles defaultJournalOverride findBuiltinCommand addons inputfiles = do+  dbg1IO "inputfiles" inputfiles+  -- read commands from all the inputfiles+  commands <- (flip concatMapM) inputfiles $ \f -> do+    dbg1IO "reading commands" f+    lines . T.unpack <$> T.readFile f++  forM_ commands (runCommand defaultJournalOverride findBuiltinCommand addons . parseCommand)++-- | Run commands from command line arguments given to "run".+runFromArgs :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> [String] -> IO ()+runFromArgs defaultJournalOverride findBuiltinCommand addons args = do+  -- read commands from all the inputfiles+  let commands = dbg1 "commands from args" $ splitAtElement "--" args+  forM_ commands (runCommand defaultJournalOverride findBuiltinCommand addons)++-- When commands are passed on the command line, shell will parse them for us+-- When commands are read from file, we need to split the line into command and arguments+parseCommand :: String -> [String]+parseCommand line =+  -- # begins a comment, ignore everything after #+  takeWhile (not. ((Just '#')==) . headMay) $  words' (strip line)++-- | Take a single command line (from file, or REPL, or "--"-surrounded block of the args), and run it.+runCommand :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> [String] -> IO ()+runCommand defaultJournalOverride findBuiltinCommand addons cmdline = do+  dbg1IO "runCommand for" cmdline+  case cmdline of+    "echo":args -> putStrLn $ unwords $ args+    cmdname:args ->+      case findBuiltinCommand cmdname of+        Just (cmdmode,cmdaction) -> do+              -- Even though expandArgsAt is done by the Cli.hs, it stops at the first '--', so we need+              -- to do it here as well to make sure that each command can use @ARGFILEs+              args' <- replaceNumericFlags <$> expandArgsAt args+              dbg1IO "runCommand final args" (cmdname,args')+              opts <- getHledgerCliOpts' cmdmode args'+              let+                rawopts      = rawopts_ opts+                mmodecmdname = headMay $ modeNames cmdmode+                helpFlag     = boolopt "help"    rawopts+                tldrFlag     = boolopt "tldr"    rawopts+                infoFlag     = boolopt "info"    rawopts+                manFlag      = boolopt "man"     rawopts+              if+                | helpFlag  -> runPager $ showModeUsage cmdmode ++ "\n"+                | tldrFlag  -> runTldrForPage $ maybe "hledger" (("hledger-"<>)) mmodecmdname+                | infoFlag  -> runInfoForTopic "hledger" mmodecmdname+                | manFlag   -> runManForTopic "hledger"  mmodecmdname+                | otherwise -> do+                  withJournalCached (Just defaultJournalOverride) opts $ \(j,key) -> do+                    if cmdname == "run" -- allow "run" to call "run"+                      then run (Just key) findBuiltinCommand addons opts+                      else cmdaction opts j+        Nothing | cmdname `elem` addons ->+          system (printf "%s-%s %s" progname cmdname (unwords' args)) >>= exitWith+        Nothing ->+          error' $ "Unrecognized command: " ++ unwords (cmdname:args)+    [] -> return ()++-- | Run an interactive REPL.+runREPL :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> IO ()+runREPL defaultJournalOverride findBuiltinCommand addons = do+  isTerminal <- isStdinTerminal+  if not isTerminal+    then runInputT defaultSettings (loop "")+    else do+      putStrLn "Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF."+      runInputT defaultSettings (loop "% ")+  where+  loop :: String -> InputT IO ()+  loop prompt = do+    minput <- getInputLine prompt+    case minput of+      Nothing -> return ()+      Just "quit" -> return ()+      Just "exit" -> return ()+      Just input -> do+        liftIO $ (runCommand defaultJournalOverride findBuiltinCommand addons $ argsAddDoubleDash $ parseCommand input)+                  `catches`+                  [Handler (\(e::ErrorCall) -> putStrLn $ rstrip $ show e)+                  ,Handler (\(e::IOError)   -> putStrLn $ rstrip $ show e)+                  ,Handler (\(_::ExitCode)  -> return ())+                  ,Handler (\UserInterrupt  -> return ())+                  ]+        loop prompt++isStdinTerminal = do+  op <- hIsOpen stdin+  if op then hIsTerminalDevice stdin else return False++-- | Cache of all journals that have been read by commands given to "run",+-- keyed by the fully-expanded filename.+journalCache :: MVar (Map.Map (InputOpts,PrefixedFilePath) Journal)+journalCache = unsafePerformIO $ newMVar Map.empty+{-# NOINLINE journalCache #-}++-- | Cache of stdin contents, so that we can re-read it if InputOptions change+stdinCache :: MVar (Maybe T.Text)+stdinCache = unsafePerformIO $ newMVar Nothing+{-# NOINLINE stdinCache #-}++-- | Similar to `withJournal`, but uses caches all the journals it reads.+-- When reading from stdin, caches the stdin contents so that we could reprocess+-- it if a read with different InputOptions is requested.+withJournalCached :: Maybe DefaultRunJournal -> CliOpts -> ((Journal, DefaultRunJournal) -> IO ()) -> IO ()+withJournalCached defaultJournalOverride cliopts cmd = do+  (j,key) <- case defaultJournalOverride of+    Nothing -> journalFilePathFromOpts cliopts >>= readFiles+    Just (DefaultRunJournal defaultFiles) -> do+      mbjournalpaths <- journalFilePathFromOptsNoDefault cliopts+      case mbjournalpaths of+        Nothing -> readFiles defaultFiles -- use the journal(s) given to the "run" itself+        Just journalpaths -> readFiles journalpaths+  cmd (j,key)+  where+    readFiles journalpaths = do+      j <- journalTransform cliopts . sconcat <$> mapM (readAndCacheJournalFile (inputopts_ cliopts)) journalpaths+      return (j, DefaultRunJournal journalpaths)+    -- | Read a journal file, caching it (and InputOptions used to read it) if it has not been seen before.+    -- If the same file is requested with different InputOptions, we read it anew and cache+    -- it separately.+    readAndCacheJournalFile :: InputOpts -> PrefixedFilePath -> IO Journal+    readAndCacheJournalFile iopts fp = do+      modifyMVar journalCache $ \cache ->+        case Map.lookup (ioptsWithoutReportSpan,fp) cache of+          Just journal -> do+            dbg1IO ("readAndCacheJournalFile using cache for "++fp) iopts+            return (cache, journal)+          Nothing -> do+            dbg1IO ("readAndCacheJournalFile reading and caching "++fp) iopts+            journal <- runExceptT $ if snd (splitReaderPrefix fp) == "-" then readStdin else readJournalFile iopts fp+            either error' (\j -> return (Map.insert (ioptsWithoutReportSpan,fp) j cache, j)) journal+      where+        -- InputOptions contain reportspan_ that is used to calculare forecast period,+        -- that is used by journalFinalise to insert forecast transactions.addHeaderBorders+        -- For the purposes of caching, we want to ignore this, as it is only used for forecast+        -- and it is sufficient to include forecast_ in the InputOptions that we use as a key.+        ioptsWithoutReportSpan = iopts { reportspan_ = emptydatespan }+        -- Read stdin, or if we read it alread, use a cache+        -- readStdin :: InputOpts -> ExceptT String IO Journal+        readStdin = do+          stdinContent <- liftIO $ modifyMVar stdinCache $ \cache ->+            case cache of+              Just cached -> do+                dbg1IO "readStdin using cached stdin" "-"+                return (cache, cached)+              Nothing -> do+                dbg1IO "readStdin reading and caching stdin" "-"+                stdinContent <- readFileOrStdinPortably "-"+                return (Just stdinContent, stdinContent)+          hndl <- liftIO $ inputToHandle stdinContent+          readJournal iopts Nothing hndl

@@ -0,0 +1,86 @@+run++Run a sequence of hledger commands, provided as files or command line+arguments. Data files are parsed just once, so the commands run faster.++Flags:+no command-specific flags++This command is experimental and could change in the future.++You can use run in three ways:++-   hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command+    line, separated by --+-   hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more+    files+-   cat SCRIPTFILE1 | hledger run - read commands from standard input.++run first loads the input file(s) specified by LEDGER_FILE or by -f+options, in the usual way. Then it runs each command in turn, each using+the same input data. But if you want a particular command to use+different input, you can specify an -f option within that command. This+will override (not add to) the default input, just for that command.++Each input file (more precisely, each combination of input file and+input options) is parsed only once. This means that commands will not+see any changes made to these files, until the next run. But the+commands will run more quickly than if run individually (typically about+twice as fast).++Command scripts, whether in a file or written on the command line, have+a simple syntax:++-   each line may contain a single hledger command and its arguments,+    without the usual hledger first word+-   empty lines are ignored+-   text from # to end of line is a comment, and ignored+-   you can use single or double quotes to quote arguments when needed,+    as on the command line+-   these extra commands are available: echo TEXT prints some text, and+    exit or quit ends the run.++On unix systems you can use #!/usr/bin/env hledger run in the first line+of a command file to make it a runnable script. If that gives an error,+use #!/usr/bin/env -S hledger run.++It's ok to use the run command recursively within a command script.++Caveats++You may find some differences in behaviour between run command lines and+normal hledger command lines. For example, with run,++-   the command name must be written first, options afterward+-   full command names or official abbreviations (as in the command+    list) must be used++Examples++Run commands specified on the command line:++hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats++This would load some.journal, run balance assets --depth 2 on it, then+run balance liabilities --depth 3 --transpose on /some/other.journal,+and finally run stats on some.journal++Run commands from standard input:++(echo "files"; echo "stats") | hledger -f some.journal run++Provide commands as a runnable script:++#!/usr/bin/env -S hledger run -f some.journal++echo "List of accounts in some.journal"+accounts++echo "Assets of some.journal"+balance assets --depth 2++echo "Liabilities from /some/other.journal"+balance liabilities -f /some/other.journal --depth 3 --transpose++echo "Commands from another.script, applied to another.journal"+run -f another.journal another.script

@@ -14,9 +14,11 @@  ,compoundBalanceCommand ) where -import Data.Maybe (fromMaybe, mapMaybe, maybeToList)-import Data.List.NonEmpty (NonEmpty((:|)))+import Control.Monad (guard) import Data.Bifunctor (second)+import Data.Function ((&))+import Data.List.NonEmpty (NonEmpty((:|)))+import Data.Maybe (fromMaybe, mapMaybe, maybeToList) import qualified Data.Map as Map import qualified Data.List as List import qualified Data.List.NonEmpty as NonEmpty@@ -24,22 +26,20 @@ import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as TB import Data.Time.Calendar (Day, addDays)+import Lucid as L hiding (Html, value_) import System.Console.CmdArgs.Explicit as C (Mode, flagNone, flagReq) import qualified System.IO as IO-import Hledger.Write.Ods (printFods)-import Hledger.Write.Csv (CSV, printCSV, printTSV)-import Hledger.Write.Html.Lucid (printHtml)-import Hledger.Write.Html.Attribute (stylesheet, tableStyle, alignleft)-import qualified Hledger.Write.Spreadsheet as Spr-import Lucid as L hiding (value_) import Text.Tabular.AsciiWide as Tabular hiding (render)  import Hledger import Hledger.Cli.Commands.Balance import Hledger.Cli.CliOptions import Hledger.Cli.Utils (unsupportedOutputFormatError, writeOutputLazyText)-import Data.Function ((&))-import Control.Monad (guard)+import Hledger.Write.Csv (CSV, printCSV, printTSV)+import Hledger.Write.Html (htmlAsLazyText, styledTableHtml, Html)+import Hledger.Write.Html.Attribute (stylesheet, tableStyle, alignleft)+import Hledger.Write.Ods (printFods)+import qualified Hledger.Write.Spreadsheet as Spr  -- | Description of a compound balance report command, -- from which we generate the command's cmdargs mode and IO action.@@ -76,8 +76,9 @@       "show total change of period-end historical balance value (caused by deposits, withdrawals, market price fluctuations)"     ,flagNone ["gain"] (setboolopt "gain")       "show unrealised capital gain/loss (historical balance value minus cost basis)"-   ,flagNone ["budget"] (setboolopt "budget")-      "show sum of posting amounts compared to budget goals defined by periodic transactions"+  -- currently not supported by compound balance commands:+  --  ,flagNone ["budget"] (setboolopt "budget")+  --     "show sum of posting amounts compared to budget goals defined by periodic transactions"    ,flagNone ["count"] (setboolopt "count") "show the count of postings"     ,flagNone ["change"] (setboolopt "change")@@ -201,7 +202,7 @@       "txt"  -> compoundBalanceReportAsText ropts'       "csv"  -> printCSV . compoundBalanceReportAsCsv ropts'       "tsv"  -> printTSV . compoundBalanceReportAsCsv ropts'-      "html" -> L.renderText . compoundBalanceReportAsHtml ropts'+      "html" -> htmlAsLazyText . compoundBalanceReportAsHtml ropts'       "fods" -> printFods IO.localeEncoding .                 fmap (second NonEmpty.toList) . uncurry Map.singleton .                 compoundBalanceReportAsSpreadsheet@@ -322,7 +323,7 @@         NonEmpty.toList spreadsheet  -- | Render a compound balance report as HTML.-compoundBalanceReportAsHtml :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> Html ()+compoundBalanceReportAsHtml :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> Html compoundBalanceReportAsHtml ropts cbr =   let (title, (_fixed, cells)) =           compoundBalanceReportAsSpreadsheet@@ -337,7 +338,7 @@       ]     table_ $ do       tr_ $ th_ [colspanattr, style_ alignleft] $ h2_ $ toHtml title-      printHtml $ NonEmpty.toList $ fmap (map (fmap L.toHtml)) cells+      styledTableHtml $ NonEmpty.toList $ fmap (map (fmap L.toHtml)) cells  -- | Render a compound balance report as Spreadsheet. compoundBalanceReportAsSpreadsheet ::

@@ -4,12 +4,11 @@  import Criterion.Main     (defaultMainWith, defaultConfig, bench, nfIO) -- import QuickBench        (defaultMain)-import Data.Default import System.Directory   (getCurrentDirectory) import System.Environment (getArgs, withArgs) import System.TimeIt      (timeItT) import Text.Printf-import Hledger.Cli+import Hledger.Cli hiding (main)  -- sample journal file to use for benchmarks inputfile = "bench/10000x1000x10.journal"@@ -34,7 +33,7 @@ benchWithTimeit = do   getCurrentDirectory >>= printf "Benchmarking hledger in %s with timeit\n"   let opts = defcliopts{output_file_=Just outputfile}-  (t0,j) <- timeit ("read "++inputfile) $ either error id <$> readJournalFile def inputfile  -- PARTIAL:+  (t0,j) <- timeit ("read "++inputfile) $ readJournalFile' inputfile  -- PARTIAL:   (t1,_) <- timeit ("print") $ print' opts j   (t2,_) <- timeit ("register") $ register opts j   (t3,_) <- timeit ("balance") $ balance  opts j@@ -50,9 +49,9 @@ benchWithCriterion = do   getCurrentDirectory >>= printf "Benchmarking hledger in %s with criterion\n"   let opts = defcliopts{output_file_=Just "/dev/null"}-  j <- either error id <$> readJournalFile def inputfile  -- PARTIAL:+  j <- readJournalFile' inputfile  -- PARTIAL:   Criterion.Main.defaultMainWith defaultConfig $ [-    bench ("read "++inputfile) $ nfIO $ (either error const <$> readJournalFile def inputfile),  -- PARTIAL:+    bench ("read "++inputfile) $ nfIO $ const <$> readJournalFile' inputfile,  -- PARTIAL:     bench ("print")            $ nfIO $ print'   opts j,     bench ("register")         $ nfIO $ register opts j,     bench ("balance")          $ nfIO $ balance  opts j,

@@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "October 2024" "hledger-ui-1.41 " "hledger User Manuals"+.TH "HLEDGER\-UI" "1" "March 2025" "hledger-ui-1.42 " "hledger User Manuals"   @@ -17,7 +17,7 @@ .PD \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s terminal interface, version 1.41.+This manual is for hledger\[aq]s terminal interface, version 1.42. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for@@ -458,9 +458,6 @@ If you are viewing files mounted from another machine, the system clocks on both machines should be roughly in agreement. .SH ENVIRONMENT-\f[B]COLUMNS\f[R] The screen width to use.-Default: the full terminal width.-.PP \f[B]LEDGER_FILE\f[R] The main journal file to use when not specified with \f[CR]\-f/\-\-file\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R].

@@ -1,4 +1,4 @@-This is hledger-ui.info, produced by makeinfo version 7.1.1 from stdin.+This is hledger-ui.info, produced by makeinfo version 7.2 from stdin.  INFO-DIR-SECTION User Applications START-INFO-DIR-ENTRY@@ -18,7 +18,7 @@ or 'hledger ui -- [OPTS] [QUERYARGS]' -   This manual is for hledger's terminal interface, version 1.41.  See+   This manual is for hledger's terminal interface, version 1.42.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -514,9 +514,7 @@ 6 ENVIRONMENT ************* -*COLUMNS* The screen width to use.  Default: the full terminal width.--   *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'.  @@ -543,22 +541,22 @@   Tag Table:-Node: Top223-Node: OPTIONS1872-Node: MOUSE8546-Node: KEYS8878-Node: SCREENS13882-Node: Menu screen14622-Node: Cash accounts screen14938-Node: Balance sheet accounts screen15299-Node: Income statement accounts screen15635-Node: All accounts screen16020-Node: Register screen16383-Node: Transaction screen18826-Node: Error screen20401-Node: WATCH MODE20767-Node: ENVIRONMENT22343-Node: BUGS22650+Node: Top221+Node: OPTIONS1870+Node: MOUSE8544+Node: KEYS8876+Node: SCREENS13880+Node: Menu screen14620+Node: Cash accounts screen14936+Node: Balance sheet accounts screen15297+Node: Income statement accounts screen15633+Node: All accounts screen16018+Node: Register screen16381+Node: Transaction screen18824+Node: Error screen20399+Node: WATCH MODE20765+Node: ENVIRONMENT22341+Node: BUGS22574  End Tag Table 

@@ -11,7 +11,7 @@        hledger ui -- [OPTS] [QUERYARGS]  DESCRIPTION-       This manual is for hledger's terminal  interface,  version  1.41.   See+       This manual is for hledger's terminal  interface,  version  1.42.   See        also the hledger manual for common concepts and file formats.         hledger  is a robust, user-friendly, cross-platform set of programs for@@ -412,8 +412,6 @@        clocks on both machines should be roughly in agreement.  ENVIRONMENT-       COLUMNS The screen width to use.  Default: the full terminal width.-        LEDGER_FILE The main journal  file  to  use  when  not  specified  with        -f/--file.  Default: $HOME/.hledger.journal. @@ -452,4 +450,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.41                  October 2024                    HLEDGER-UI(1)+hledger-ui-1.42                   March 2025                     HLEDGER-UI(1)

@@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "October 2024" "hledger-web-1.41 " "hledger User Manuals"+.TH "HLEDGER\-WEB" "1" "March 2025" "hledger-web-1.42 " "hledger User Manuals"   @@ -17,7 +17,7 @@ .PD \f[CR]hledger web \-\- [OPTS] [QUERY]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s web interface, version 1.41.+This manual is for hledger\[aq]s web interface, version 1.42. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for

@@ -1,4 +1,4 @@-This is hledger-web.info, produced by makeinfo version 7.1.1 from stdin.+This is hledger-web.info, produced by makeinfo version 7.2 from stdin.  INFO-DIR-SECTION User Applications START-INFO-DIR-ENTRY@@ -18,7 +18,7 @@ or 'hledger web -- [OPTS] [QUERY]' -   This manual is for hledger's web interface, version 1.41.  See also+   This manual is for hledger's web interface, version 1.42.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -528,16 +528,16 @@   Tag Table:-Node: Top225-Node: OPTIONS2568-Node: PERMISSIONS11257-Node: EDITING UPLOADING DOWNLOADING12608-Node: RELOADING13623-Node: JSON API14190-Node: DEBUG OUTPUT19839-Node: Debug output19991-Node: ENVIRONMENT20509-Node: BUGS20745+Node: Top223+Node: OPTIONS2566+Node: PERMISSIONS11255+Node: EDITING UPLOADING DOWNLOADING12606+Node: RELOADING13621+Node: JSON API14188+Node: DEBUG OUTPUT19837+Node: Debug output19989+Node: ENVIRONMENT20507+Node: BUGS20743  End Tag Table 

@@ -11,7 +11,7 @@        hledger web -- [OPTS] [QUERY]  DESCRIPTION-       This manual is for hledger's web interface, version 1.41.  See also the+       This manual is for hledger's web interface, version 1.42.  See also the        hledger manual for common concepts and file formats.         hledger is a robust, user-friendly, cross-platform set of programs  for@@ -480,4 +480,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.41                 October 2024                   HLEDGER-WEB(1)+hledger-web-1.42                  March 2025                    HLEDGER-WEB(1)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "October 2024" "hledger-1.41 " "hledger User Manuals"+.TH "HLEDGER" "1" "March 2025" "hledger-1.42 " "hledger User Manuals"   @@ -32,7 +32,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.41.+This manual is for hledger\[aq]s command line interface, version 1.42. 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!@@ -132,20 +132,26 @@ For more about how to do that on your system, see Common tasks > Setting LEDGER_FILE. .SS Text encoding-Data files containing non\-ascii characters must use UTF\-8 encoding.-An optional byte order mark (BOM) is allowed, at the beginning of the-file (only).+hledger input files containing non\-ascii characters must use UTF\-8+encoding, with the exception of CSV (SSV, TSV..)+files, which can be read from other encodings (see \f[CR]encoding\f[R]+CSV rule). .PP-Also, your system should be configured with a locale that can decode-UTF\-8 text.-On some unix systems, you may need set the \f[CR]LANG\f[R] environment-variable, eg.+In UTF\-8 input files, an optional byte order mark (BOM) at the+beginning of the file is allowed.+.PP+Your system may need to be configured with a locale that understands the+input file\[aq]s encoding.+Eg on some unix systems, you may need set the \f[CR]LANG\f[R]+environment variable. You can read more about this in Unicode characters, below. .PP-On unix systems you can check a file\[aq]s encoding with the-\f[CR]file\f[R] command.-If you need to import from a UTF\-16\-encoded CSV file, say, you can-convert it to UTF\-8 with the \f[CR]iconv\f[R] command.+On some unix systems you can use the \f[CR]file\f[R] command to show a+file\[aq]s text encoding.+On mac, you\[aq]ll need the version from homebrew:+\f[CR]brew install file\-formula\f[R].+.PP+hledger\[aq]s text output is always UTF\-8 encoded. .SS Data formats Usually the data file is in hledger\[aq]s journal format, but it can be in any of the supported file formats, which currently are:@@ -903,12 +909,11 @@ The config file feature was added in hledger 1.40 and is considered \f[I]experimental\f[R]. .SS Shell completions-If you use the bash shell, you can optionally set up context\-sensitive-autocompletions when you press TAB in a hledger command line.-At a bash shell prompt, try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R]-(should list all hledger commands) or-\f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list your top\-level-account names).+If you use the bash or zsh shells, you can optionally set up+context\-sensitive autocompletion for hledger command lines.+Try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R] (should list all+hledger commands) or \f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list+your top\-level account names). If completions aren\[aq]t working, or for more details, see Install > Shell completions. .SH Output@@ -1112,13 +1117,10 @@ terminal and font that render those correctly. (This can be challenging on MS Windows.) .PP-Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will use the-width indicated by the \f[CR]COLUMNS\f[R] environment variable.-If your shell and terminal are working well, they will keep COLUMNS-updated as you resize the window.-So register reports normally will use the full window width.-When this isn\[aq]t working or you want to override it, you can manually-set COLUMNS, or use the \f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option.+Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will normally+use the full window width.+If this isn\[aq]t working or you want to override it, you can use the+\f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option. .PP Balance reports (\f[CR]balance\f[R], \f[CR]balancesheet\f[R], \f[CR]incomestatement\f[R]...)@@ -1151,6 +1153,9 @@ .SS Paging In unix\-like environments, when displaying large output (in any output format) in the terminal, hledger tries to use a pager when appropriate.+(You can disable this with the \f[CR]\-\-pager=no\f[R] option, perhaps+in your config file.)+.PP The pager shows one page of text at a time, and lets you scroll around to see more. While it is active, usually \f[CR]SPACE\f[R] shows the next page,@@ -1176,7 +1181,7 @@ (At the time of writing: \-\-chop\-long\-lines \-\-hilite\-unread \-\-ignore\-case \-\-mouse \-\-no\-init \-\-quit\-at\-eof \-\-quit\-if\-one\-screen \-\-RAW\-CONTROL\-CHARS \-\-shift=8-\-\-squeeze\-blank\-lines \-\-use\-backslash \-\-use\-color ).+\-\-squeeze\-blank\-lines \-\-use\-backslash ). If these don\[aq]t work well, you can set your preferred options in the \f[CR]HLEDGER_LESS\f[R] variable, which will be used instead. .SS HTML output@@ -1230,6 +1235,13 @@ \f[CR]Expenses\f[R]. You can use account aliases to rewrite your account names temporarily, if needed, as in this hledger2beancount.conf config file.+.PP+2024\-12\-20: Some more things not yet handled for you:+.IP \[bu] 2+P directives are not converted automatically \- convert those yourself+.IP \[bu] 2+Balance assignments are not converted (Beancount doesnt support them) \-+replace those with explicit amounts .SS Beancount account names Aside from the top\-level names, hledger will adjust your account names to make valid Beancount account names, by capitalising each part,@@ -1328,7 +1340,7 @@ $ hledger print \-c \[aq]$1.000,0\[aq] .EE .PP-This option can repeated to set the display style for multiple+This option can be repeated to set the display style for multiple commodities/currencies. Its argument is as described in the commodity directive. .PP@@ -1358,10 +1370,6 @@ .SH Environment These environment variables affect hledger: .PP-\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger-commands (\f[CR]register\f[R]) will format their output to this width.-If not set, they will try to use the available terminal width.-.PP \f[B]HLEDGER_LESS\f[R] If \f[CR]less\f[R] is your pager, this variable specifies the \f[CR]less\f[R] options hledger should use. (Otherwise, \f[CR]LESS\f[R] + custom options are used.)@@ -3105,7 +3113,7 @@ command, eg something like: .IP .EX-$ hledger accounts \-\-alias assets=bassetts type:a+$ hledger accounts \-\-types \-1 \-\-alias assets=bassetts .EE .SS \f[CR]commodity\f[R] directive The \f[CR]commodity\f[R] directive performs several functions:@@ -3143,7 +3151,7 @@ .SS Commodity directive syntax A commodity directive is normally the word \f[CR]commodity\f[R] followed by a sample amount (and optionally a comment).-Only the amount\[aq]s symbol and format is significant.+Only the amount\[aq]s symbol and the number\[aq]s format is significant. Eg: .IP .EX@@ -3872,14 +3880,15 @@ syntax comparison. .SS Other cost/lot notations A slight digression for Ledger and Beancount users.-Ledger has a number of cost/lot\-related notations:+.PP+\f[B]Ledger\f[R] has a number of cost/lot\-related notations: .IP \[bu] 2 \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] .RS 2 .IP \[bu] 2 expresses a conversion rate, as in hledger .IP \[bu] 2-when buying, also creates a lot than can be selected at selling time+when buying, also creates a lot that can be selected at selling time .RE .IP \[bu] 2 \f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R]@@ -3889,15 +3898,11 @@ like the above, but also means \[dq]this cost was exceptional, don\[aq]t use it when inferring market prices\[dq]. .RE-.PP-Currently, hledger treats the above like \f[CR]\[at]\f[R] and-\f[CR]\[at]\[at]\f[R]; the parentheses are ignored. .IP \[bu] 2-\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed-price)+\f[CR]{=UNITCOST}\f[R] and \f[CR]{{=TOTALCOST}}\f[R] (fixed price) .RS 2 .IP \[bu] 2-when buying, means \[dq]this cost is also the fixed price, don\[aq]t let+when buying, means \[dq]this cost is also the fixed value, don\[aq]t let it fluctuate in value reports\[dq] .RE .IP \[bu] 2@@ -3907,11 +3912,12 @@ can be used identically to \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot .IP \[bu] 2-when selling, combined with \f[CR]\[at] ...\f[R], specifies an-investment lot by its cost basis; does not check if that lot is present+when selling, combined with \f[CR]\[at] ...\f[R], selects an existing+lot by its cost basis.+Does not check if that lot is present. .RE .IP \[bu] 2-and related: \f[CR][YYYY/MM/DD]\f[R] (lot date)+\f[CR][YYYY/MM/DD]\f[R] (lot date) .RS 2 .IP \[bu] 2 when buying, attaches this acquisition date to the lot@@ -3927,29 +3933,37 @@ when selling, selects a lot by its note .RE .PP-Currently, hledger accepts any or all of the above in any order after-the posting amount, but ignores them.+Currently, hledger+.IP \[bu] 2+accepts any or all of the above in any order after the posting amount+.IP \[bu] 2+supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]+.IP \[bu] 2+treats \f[CR](\[at])\f[R] and \f[CR](\[at]\[at])\f[R] as synonyms for+\f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]+.IP \[bu] 2+and ignores the rest. (This can break transaction balancing.) .PP-For Beancount users, the notation and behaviour is different:+\f[B]Beancount\f[R] has simpler notation and different behaviour: .IP \[bu] 2 \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] .RS 2 .IP \[bu] 2 expresses a cost without creating a lot, as in hledger .IP \[bu] 2-when buying (augmenting) or selling (reducing) a lot, combined with-\f[CR]{...}\f[R]: documents the cost/selling price (not used for-transaction balancing)+when buying (acquiring) or selling (disposing of) a lot, and combined+with \f[CR]{...}\f[R]: is not used except to document the cost/selling+price .RE .IP \[bu] 2 \f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] .RS 2 .IP \[bu] 2-when buying (augmenting), expresses the cost for transaction balancing,-and also creates a lot with this cost basis attached+when buying, expresses the cost for transaction balancing, and also+creates a lot with this cost basis attached .IP \[bu] 2-when selling (reducing),+when selling, .RS 2 .IP \[bu] 2 selects a lot by its cost basis@@ -3960,15 +3974,24 @@ expresses the selling price for transaction balancing .RE .RE-.PP-Currently, hledger accepts the-\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it. .IP \[bu] 2-variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R],-\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],-\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc.+\f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], \f[CR]{\[dq]LABEL\[dq]}\f[R],+\f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],+\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R]+.RS 2+.IP \[bu] 2+when selling, other combinations of date/cost/label, like the above, are+accepted for selecting the lot.+.RE .PP-Currently, hledger rejects these.+Currently, hledger+.IP \[bu] 2+supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]+.IP \[bu] 2+accepts the \f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation, but+ignores it+.IP \[bu] 2+and rejects the rest. .PP .SH CSV hledger can read CSV files (Character Separated Value \- usually comma,@@ -4038,6 +4061,11 @@ optionally declare which file to read data from T} T{+\f[B]\f[CB]encoding\f[B]\f[R]+T}@T{+optionally declare which text encoding the data has+T}+T{ \f[B]\f[CB]separator\f[B]\f[R] T}@T{ declare the field separator, instead of relying on file extension@@ -4144,6 +4172,26 @@ .EE .PP See also \[dq]Working with CSV > Reading files specified by rule\[dq].+.SS \f[CR]encoding\f[R]+.IP+.EX+encoding ENCODING+.EE+.PP+hledger normally expects non\-ascii text to be UTF8\-encoded.+If you need to read CSV files which have some other encoding, you can do+it by adding \f[CR]encoding ENCODING\f[R] to your CSV rules.+Eg: \f[CR]encoding ISO88591\f[R].+.PP+The following encodings are supported (these names are+case\-insensitive, and can be written with inner spaces or hyphens if+you prefer): ASCII, UTF8, UTF16, UTF32, ISO88591, ISO88592, ISO88593,+ISO88594, ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910,+ISO885911, ISO885913, ISO885914, ISO885915, ISO885916, CP1250, CP1251,+CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U,+GB18030, MacOSRoman, JISX0201, JISX0208, ISO2022JP, ShiftJIS, CP437,+CP737, CP775, CP850, CP852, CP855, CP857, CP860, CP861, CP862, CP863,+CP864, CP865, CP866, CP869, CP874, CP932. .SS \f[CR]separator\f[R] You can use the \f[CR]separator\f[R] rule to read other kinds of character\-separated data.@@ -4689,12 +4737,20 @@ .IP \[bu] 2 By default they are OR\[aq]d (any of them can match). .IP \[bu] 2-Matcher lines beginning with \f[CR]&\f[R] (and optional space) are-AND\[aq]ed with the matcher above (all in the AND\[aq]ed group must-match).+Matcher lines beginning with \f[CR]&\f[R] (or \f[CR]&&\f[R], \f[I]since+1.42\f[R]) are AND\[aq]ed with the matcher above (all in the AND\[aq]ed+group must match).+.IP \[bu] 2+Matcher lines beginning with \f[CR]& !\f[R] (\f[I]since 1.41\f[R], or+\f[CR]&& !\f[R], \f[I]since 1.42\f[R]) are first negated and then+AND\[aq]ed with the matcher above. .PP-\f[I](Since 1.41:)\f[R] You can use a negated \f[CR]!\f[R] matcher on a-\f[CR]&\f[R] line, meaning AND NOT.+You can also combine multiple matchers one the same line separated by+\f[CR]&&\f[R] (AND) or \f[CR]&& !\f[R] (AND NOT).+Eg \f[CR]%description amazon && %date 2025\-01\-01\f[R] will match only+when the description field contains \[dq]amazon\[dq] and the date field+contains \[dq]2025\-01\-01\[dq].+\f[I]Added in 1.42.\f[R] .SS Match groups \f[I]Added in 1.32\f[R] .PP@@ -4731,9 +4787,9 @@ .EX if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,...-MATCHERB,VALUE1,VALUE2,...-; Comment line that explains MATCHERC-MATCHERC,VALUE1,VALUE2,...+MATCHERB && MATCHERC,VALUE1,VALUE2,...  (*since 1.42*)+; Comment line that explains MATCHERD+MATCHERD,VALUE1,VALUE2,... <empty line> .EE .PP@@ -4753,10 +4809,11 @@ The table must be terminated by an empty line (or end of file). .PP 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; If multiple lines match, later-lines will override fields assigned by the earlier ones \- just like the-sequence of \f[CR]if\f[R] blocks would behave.+lines with matchers; whenever a line with matchers succeeds, assign all+of the values on that line to the corresponding hledger fields; If+multiple lines match, later lines will override fields assigned by the+earlier ones \- just like the sequence of \f[CR]if\f[R] blocks would+behave. .PP If table presented above is equivalent to this sequence of if blocks: .IP@@ -4766,13 +4823,13 @@   HLEDGERFIELD2 VALUE2   ... -if MATCHERB+if MATCHERB && MATCHERC   HLEDGERFIELD1 VALUE1   HLEDGERFIELD2 VALUE2   ... -; Comment line which explains MATCHERC-if MATCHERC+; Comment line which explains MATCHERD+if MATCHERD   HLEDGERFIELD1 VALUE1   HLEDGERFIELD2 VALUE2   ...@@ -6759,21 +6816,38 @@ symbol and the old amount quantity, not the new ones. (Except in hledger 1.22, #1625.) .SH Pivoting-Normally, hledger groups and sums amounts within each account.-The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction-field for account names, causing amounts to be grouped and summed by-that field\[aq]s value instead.-FIELD can be any of the transaction fields \f[CR]acct\f[R],-\f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], \f[CR]payee\f[R],-\f[CR]note\f[R], 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 \f[CR]colon:separated:parts\f[R] will be displayed-hierarchically, like account names.-Multiple, colon\-delimited fields can be pivoted simultaneously,-generating a hierarchical account name.+Normally, hledger groups amounts and displays their totals by account+(name).+With \f[CR]\-\-pivot PIVOTEXPR\f[R], some other field\[aq]s (or multiple+fields\[aq]) value is used as a synthetic account name, causing+different grouping and display.+PIVOTEXPR can be+.IP \[bu] 2+any of these standard transaction or posting fields (their value is+substituted): \f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R],+\f[CR]payee\f[R], \f[CR]note\f[R], \f[CR]acct\f[R],+\f[CR]comm\f[R]/\f[CR]cur\f[R], \f[CR]amt\f[R], \f[CR]cost\f[R]+.IP \[bu] 2+or a tag name+.IP \[bu] 2+or any combination of these, colon\-separated. .PP-Some examples:+Some special cases:+.IP \[bu] 2+Colons appearing in PIVOTEXPR or in a pivoted tag value will generate+account hierarchy.+.IP \[bu] 2+When pivoting a posting has multiple values for a tag, the pivoted value+of that tag will be the first value.+.IP \[bu] 2+When a posting has multiple commodities, the pivoted value of+\[dq]comm\[dq]/\[dq]cur\[dq] will be \[dq]\[dq].+Also when an unrecognised tag name or field is provided, its pivoted+value will be \[dq]\[dq].+(If this causes confusing output, consider excluding those postings from+the report.)+.PP+Examples: .IP .EX 2016/02/16 Yearly Dues Payment@@ -6820,7 +6894,7 @@               \-2 EUR .EE .PP-Hierarchical reports can be generated with multiple pivots:+Hierarchical reports can be generated with multiple pivot values: .IP .EX $ hledger balance Income:Dues \-\-pivot kind:member@@ -7209,9 +7283,10 @@ 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 \[dq]cost\[dq], for convenience; feel free-to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling-price\[dq] if helpful.+(In hledger docs we just say \[dq]cost\[dq] generically for+convenience.)+With the \f[CR]\-B/\-\-cost\f[R] flag, hledger can show amounts \[dq]at+cost\[dq], converted to the cost\[aq]s commodity. .SS Recording costs We\[aq]ll explore several ways of recording transactions involving costs.@@ -7455,14 +7530,16 @@ and let us know what problems you find. .PP .SH 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 \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option,-which will be described below.-We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]-options, and often one of these is all you need:+hledger can also show amounts \[dq]at market value\[dq], converted to+some other commodity using the market price or conversion rate on a+certain date.+.PP+This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option.+We also provide simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]+aliases for this, which are often sufficient.+The market prices are declared with a special \f[CR]P\f[R] directive,+and/or they can be inferred from the costs recorded in transactions, by+using the \f[CR]\-\-infer\-market\-prices\f[R] flag. .SS \-V: Value The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in their default \f[I]valuation commodity\f[R], using the market prices in@@ -8271,6 +8348,49 @@ .PP Next, these commands are described in detail. .SH Help commands+.SS commands+Show the hledger commands list.+.IP+.EX+Flags:+     \-\-builtin             show only builtin commands, not addons+.EE+.SS demo+Play demos of hledger usage in the terminal, if asciinema is installed.+.IP+.EX+Flags:+  \-s \-\-speed=SPEED         playback speed (1 is original speed, .5 is half, 2+                           is double, etc (default: 2))+.EE+.PP+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:+.PP+Make your terminal window large enough to see the demo clearly.+.PP+Use the \-s/\-\-speed SPEED option to set your preferred playback speed,+eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to+play at half speed.+The default speed is 2x.+.PP+Other asciinema options can be added following a double dash, eg+\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list+asciinema\[aq]s other options.+.PP+During playback, several keys are available: SPACE to pause/unpause, .+to step forward (while paused), CTRL\-c quit.+.PP+Examples:+.IP+.EX+$ hledger demo               # list available demos+$ hledger demo 1             # play the first demo at default speed (2x)+$ hledger demo install \-s4   # play the \[dq]install\[dq] demo at 4x speed+.EE+.PP+This command is experimental: there aren\[aq]t many useful demos yet. .SS help Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a pager.@@ -8318,41 +8438,220 @@ $ hledger help \[aq]time periods\[aq]     # show the manual\[aq]s \[dq]Time periods\[dq] topic $ hledger help \[aq]time periods\[aq] \-m  # use man, even if info is installed .EE-.SS demo-Play demos of hledger usage in the terminal, if asciinema is installed.+.SH User interface commands+.SS repl+Start an interactive prompt, where you can run any of hledger\[aq]s+commands.+Data files are parsed just once, so the commands run faster. .IP .EX Flags:-  \-s \-\-speed=SPEED         playback speed (1 is original speed, .5 is half, 2-                           is double, etc (default: 2))+no command\-specific flags .EE .PP-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:+This command is experimental and could change in the future. .PP-Make your terminal window large enough to see the demo clearly.+\f[CR]hledger repl\f[R] starts a read\-eval\-print loop (REPL) where you+can enter commands interactively.+As with the \f[CR]run\f[R] command, each input file (or each input+file/input options combination) is parsed just once, so commands will+run more quickly than if you ran them individually at the command line. .PP-Use the \-s/\-\-speed SPEED option to set your preferred playback speed,-eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to-play at half speed.-The default speed is 2x.+Also like \f[CR]run\f[R], the input file(s) specified for the+\f[CR]repl\f[R] command will be the default input for all interactive+commands, you can override this temporarily by specifying an+\f[CR]\-f\f[R] option in particular commands, and commands will not see+any changes made to input files (eg by \f[CR]add\f[R]) until you exit+and restart the REPL. .PP-Other asciinema options can be added following a double dash, eg-\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list-asciinema\[aq]s other options.+The command syntax is the same as with \f[CR]run\f[R]:+.IP \[bu] 2+enter one hledger command at a time, without the usual+\f[CR]hledger\f[R] first word+.IP \[bu] 2+empty lines and comment text from \f[CR]#\f[R] to end of line are+ignored+.IP \[bu] 2+use single or double quotes to quote arguments when needed+.IP \[bu] 2+type \f[CR]exit\f[R] or \f[CR]quit\f[R] or control\-D to exit the REPL. .PP-During playback, several keys are available: SPACE to pause/unpause, .-to step forward (while paused), CTRL\-c quit.+While it is running, the REPL remembers your command history, and you+can navigate in the usual ways:+.IP \[bu] 2+Keypad or Emacs navigation keys to edit the current command line+.IP \[bu] 2+UP/DOWN or control\-P/control\-N to step back/forward through history+.IP \[bu] 2+control\-R to search for a past command+.IP \[bu] 2+TAB completes file paths. .PP-Examples:+The \f[CR]commands\f[R] and \f[CR]help\f[R]\ commands, and the command+help flags (\f[CR]CMD \-\-tldr\f[R], \f[CR]CMD \-h/\-\-help\f[R],+\f[CR]CMD \-\-info\f[R], \f[CR]CMD \-\-man\f[R]), work in the usual way,+and can be useful.+.PP+You can type control\-C to cancel a long\-running command (but only+once; typing it a second time will exit the REPL).+.PP+And in most shells you can type control\-Z to exit temporarily to the+shell (and \f[CR]fg\f[R] to return to the REPL).+.PP+You may find some differences in behaviour between \f[CR]run\f[R]+command lines and normal hledger command lines.+For example, in the REPL,+.IP \[bu] 2+the command name must be written first, options afterward+.IP \[bu] 2+full command names or official abbreviations (as in the command list)+must be used+.IP \[bu] 2+options parsing with addon commands might be less flexible than the CLI+.IP \[bu] 2+the \f[CR]stats\f[R] command gives false timings, currently+.SS Examples+Start the REPL and enter some commands: .IP .EX-$ hledger demo               # list available demos-$ hledger demo 1             # play the first demo at default speed (2x)-$ hledger demo install \-s4   # play the \[dq]install\[dq] demo at 4x speed+$ hledger repl +Enter hledger commands. To exit, enter \[aq]quit\[aq] or \[aq]exit\[aq], or send EOF.+% stats+Main file           : .../2025.journal+\&...+% stats \-f 2024/2024.journal +Main file           : .../2024.journal+\&...+% stats+Main file           : .../2025.journal+\&... .EE-.SH User interface commands+.PP+or:+.IP+.EX+$ hledger repl \-f some.journal+Enter hledger commands. To exit, enter \[aq]quit\[aq] or \[aq]exit\[aq], or send EOF.+% bs+\&...+% print \-b \[aq]last week\[aq]+\&...+% bs \-f other.journal+\&...+.EE+.SS run+Run a sequence of hledger commands, provided as files or command line+arguments.+Data files are parsed just once, so the commands run faster.+.IP+.EX+Flags:+no command\-specific flags+.EE+.PP+This command is experimental and could change in the future.+.PP+You can use \f[CR]run\f[R] in three ways:+.IP \[bu] 2+\f[CR]hledger run \-\- CMD1 \-\- CMD2 \-\- CMD3\f[R] \- read commands+from the command line, separated by \f[CR]\-\-\f[R]+.IP \[bu] 2+\f[CR]hledger run SCRIPTFILE1 SCRIPTFILE2\f[R] \- read commands from one+or more files+.IP \[bu] 2+\f[CR]cat SCRIPTFILE1 | hledger run\f[R] \- read commands from standard+input.+.PP+\f[CR]run\f[R] first loads the input file(s) specified by+\f[CR]LEDGER_FILE\f[R] or by \f[CR]\-f\f[R] options, in the usual way.+Then it runs each command in turn, each using the same input data.+But if you want a particular command to use different input, you can+specify an \f[CR]\-f\f[R] option within that command.+This will override (not add to) the default input, just for that+command.+.PP+Each input file (more precisely, each combination of input file and+input options) is parsed only once.+This means that commands will not see any changes made to these files,+until the next run.+But the commands will run more quickly than if run individually+(typically about twice as fast).+.PP+Command scripts, whether in a file or written on the command line, have+a simple syntax:+.IP \[bu] 2+each line may contain a single hledger command and its arguments,+without the usual \f[CR]hledger\f[R] first word+.IP \[bu] 2+empty lines are ignored+.IP \[bu] 2+text from \f[CR]#\f[R] to end of line is a comment, and ignored+.IP \[bu] 2+you can use single or double quotes to quote arguments when needed, as+on the command line+.IP \[bu] 2+these extra commands are available: \f[CR]echo TEXT\f[R] prints some+text, and \f[CR]exit\f[R] or \f[CR]quit\f[R] ends the run.+.PP+On unix systems you can use \f[CR]#!/usr/bin/env hledger run\f[R] in the+first line of a command file to make it a runnable script.+If that gives an error, use \f[CR]#!/usr/bin/env \-S hledger run\f[R].+.PP+It\[aq]s ok to use the \f[CR]run\f[R] command recursively within a+command script.+.PP+You may find some differences in behaviour between \f[CR]run\f[R]+command lines and normal hledger command lines.+For example, with \f[CR]run\f[R],+.IP \[bu] 2+the command name must be written first, options afterward+.IP \[bu] 2+full command names or official abbreviations (as in the command list)+must be used+.SS Examples+Run commands from the command line:+.IP+.EX+hledger \-f some.journal run \-\- balance assets \-\-depth 2 \-\- balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose \-\- stats+.EE+.PP+This would load \f[CR]some.journal\f[R], run+\f[CR]balance assets \-\-depth 2\f[R] on it, then run+\f[CR]balance liabilities \-\-depth 3 \-\-transpose\f[R] on+\f[CR]/some/other.journal\f[R], and finally run \f[CR]stats\f[R] on+\f[CR]some.journal\f[R]+.PP+Run commands from standard input:+.IP+.EX+(echo \[dq]files\[dq]; echo \[dq]stats\[dq]) | hledger \-f some.journal run+.EE+.PP+Run commands as a script:+.IP+.EX+$ cat report+#!/usr/bin/env \-S hledger run \-f some.journal++echo \[dq]List of accounts in some.journal\[dq]+accounts++echo \[dq]Assets of some.journal\[dq]+balance assets \-\-depth 2++echo \[dq]Liabilities from /some/other.journal\[dq]+balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose++echo \[dq]Commands from another.script, applied to another.journal\[dq]+run \-f another.journal another.script+.EE+.IP+.EX+$ chmod +x report+$ ./report+List of accounts in some.journal+\&...+.EE .SS ui Runs hledger\-ui (if installed). .SS web@@ -9011,13 +9310,14 @@      \-\-round=TYPE           how much rounding or padding should be done when                             displaying amounts ?                             none \- show original decimal digits,-                                   as in journal+                                   as in journal (default)                             soft \- just add or remove decimal zeros-                                   to match precision (default)+                                   to match precision                             hard \- round posting amounts to precision                                    (can unbalance transactions)                             all  \- also round cost amounts to precision                                    (can unbalance transactions)+     \-\-invert               display all amounts with reversed sign      \-\-new                  show only newer\-dated transactions added in each                             file since last run   \-m \-\-match=DESC           fuzzy search for one recent transaction with@@ -9131,6 +9431,11 @@ With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown converted to cost. .PP+With \f[CR]\-\-invert\f[R], posting amounts are shown with their sign+flipped.+It could be useful if you have accidentally recorded some transactions+with the wrong signs.+.PP With \f[CR]\-\-new\f[R], print shows only transactions it has not seen on a previous run. This uses the same deduplication system as the \f[CR]import\f[R]@@ -9233,11 +9538,10 @@      \-\-cumulative           show running total from report start date   \-H \-\-historical           show historical running total/balance (includes                             postings before report start date) (default)-                                  \-\-invert               display all amounts with reversed sign      \-\-heading=YN           show heading row above table: yes (default) or no-  \-w \-\-width=N              set output width (default: terminal width or-                            $COLUMNS). \-wN,M sets description width as well.+  \-w \-\-width=N              set output width (default: terminal width). \-wN,M+                            sets description width as well.      \-\-align\-all            guarantee alignment across all lines (slower)   \-O \-\-output\-format=FMT    select the output format. Supported formats:                             txt, html, csv, tsv, json.@@ -9357,8 +9661,8 @@      \-\-sort=FIELDS          sort by: date, desc, account, amount, absamount,                             or a comma\-separated combination of these. For a                             descending sort, prefix with \-. (Default: date)-  \-w \-\-width=N              set output width (default: terminal width or-                            $COLUMNS). \-wN,M sets description width as well.+  \-w \-\-width=N              set output width (default: terminal width). \-wN,M+                            sets description width as well.      \-\-align\-all            guarantee alignment across all lines (slower)      \-\-base\-url=URLPREFIX   in html output, generate links to hledger\-web,                             with this prefix. (Usually the base url shown by@@ -9495,10 +9799,10 @@ If there is no similar\-enough match, no posting will be shown and the program exit code will be non\-zero. .SS Custom register output-register uses the full terminal width by default, except on windows.-You can override this by setting the \f[CR]COLUMNS\f[R] environment-variable (not a bash shell variable) or by using the-\f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] option.+register normally uses the full terminal width (or 80 columns if it+can\[aq]t detect that).+You can override this with the \f[CR]\-\-width\f[R]/\f[CR]\-w\f[R]+option. .PP The description and account columns normally share the space equally (about half of (width \- 40) each).@@ -9517,10 +9821,7 @@ .EX $ 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 .EE .PP This command also supports the output destination and output format@@ -9541,8 +9842,6 @@                             market price fluctuations)      \-\-gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     \-\-budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      \-\-count                show the count of postings      \-\-change               accumulate amounts from column start to column                             end (in multicolumn reports)@@ -9645,8 +9944,6 @@                             market price fluctuations)      \-\-gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     \-\-budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      \-\-count                show the count of postings      \-\-change               accumulate amounts from column start to column                             end (in multicolumn reports)@@ -9757,8 +10054,6 @@                             market price fluctuations)      \-\-gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     \-\-budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      \-\-count                show the count of postings      \-\-change               accumulate amounts from column start to column                             end (in multicolumn reports) (default)@@ -9858,8 +10153,6 @@                             market price fluctuations)      \-\-gain                 show unrealised capital gain/loss (historical                             balance value minus cost basis)-     \-\-budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions      \-\-count                show the count of postings      \-\-change               accumulate amounts from column start to column                             end (in multicolumn reports) (default)@@ -10004,10 +10297,10 @@      \-\-transpose            switch rows and columns (use vertical time axis)      \-\-layout=ARG           how to lay out multi\-commodity amounts and the                             overall table:-                            \[aq]wide[,WIDTH]\[aq]: commodities on one line-                            \[aq]tall\[aq]        : commodities on separate lines-                            \[aq]bare\[aq]        : commodity symbols in one column-                            \[aq]tidy\[aq]        : every attribute in its own column+                            \[aq]wide[,W]\[aq]: commodities on same line, up to W wide+                            \[aq]tall\[aq]    : commodities on separate lines+                            \[aq]bare\[aq]    : commodity symbols in a separate column+                            \[aq]tidy\[aq]    : each data field in its own column      \-\-base\-url=URLPREFIX   in html output, generate links to hledger\-web,                             with this prefix. (Usually the base url shown by                             hledger\-web; can also be relative.)@@ -11068,10 +11361,6 @@ You can also produce relative links, like \f[CR]\-\-base\-url=\[dq]some/path\[dq]\f[R] or \f[CR]\-\-base\-url=\[dq]\[dq]\f[R].)-.PP-The balance reports\[aq] HTML output currently does not indent tree mode-reports properly (#1846).-So in HTML balance reports, use list mode for now (it is the default). .SS Some useful balance reports Some frequently used \f[CR]balance\f[R] options/reports are: .IP \[bu] 2@@ -11359,26 +11648,24 @@ .SS close (equity) .PP-\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or-\[dq]opening\[dq] transactions, useful in certain situations, including-migrating balances to a new journal file, retaining earnings into-equity, consolidating balances, or viewing lots.+\f[CR]close\f[R] prints several kinds of \[dq]closing\[dq] and/or+\[dq]opening\[dq] transactions, useful in various situations: migrating+balances to a new journal file, retaining earnings into equity,+consolidating balances, viewing lot costs.. Like \f[CR]print\f[R], it prints valid journal entries.-You can append or copy these to your journal file(s) when you are happy-with how they look.+You can copy these into your journal file(s) when you are happy with how+they look. .IP .EX Flags:-     \-\-migrate[=NEW]        show closing and opening transactions, for Asset-                            and Liability accounts by default, tagged for easy-                            matching. The tag\[aq]s default value can be overridden-                            by providing NEW.-     \-\-close[=NEW]          (default) show a closing transaction-     \-\-open[=NEW]           show an opening transaction-     \-\-assign[=NEW]         show opening balance assignments-     \-\-assert[=NEW]         show closing balance assertions-     \-\-retain[=NEW]         show a retain earnings transaction, for Revenue-                            and Expense accounts by default+     \-\-clopen[=TAGVAL]      show closing and opening balances transactions,+                            for AL accounts by default+     \-\-close[=TAGVAL]       show just a closing balances transaction+     \-\-open[=TAGVAL]        show just an opening balances transaction+     \-\-assert[=TAGVAL]      show a balance assertions transaction+     \-\-assign[=TAGVAL]      show a balance assignments transaction+     \-\-retain[=TAGVAL]      show a retain earnings transaction, for RX+                            accounts by default   \-x \-\-explicit             show all amounts explicitly      \-\-show\-costs           show amounts with different costs separately      \-\-interleaved          show source and destination postings together@@ -11390,97 +11677,116 @@      \-\-round=TYPE           how much rounding or padding should be done when                             displaying amounts ?                             none \- show original decimal digits,-                                   as in journal+                                   as in journal (default)                             soft \- just add or remove decimal zeros-                                   to match precision (default)+                                   to match precision                             hard \- round posting amounts to precision                                    (can unbalance transactions)                             all  \- also round cost amounts to precision                                    (can unbalance transactions) .EE .PP-\f[CR]close\f[R] currently has six modes, selected by a single mode-flag:-.SS close \-\-migrate-This is the most common mode.-It prints a \[dq]closing balances\[dq] transaction that zeroes out all-asset and liability balances (by default), and an opposite \[dq]opening-balances\[dq] transaction that restores them again.-The balancing account will be \f[CR]equity:opening/closing balances\f[R]-(or another specified by \f[CR]\-\-close\-acct\f[R] or-\f[CR]\-\-open\-acct\f[R]).+\f[CR]close\f[R] has six modes, selected by choosing one of the mode+flags (\f[CR]\-\-close\f[R] is the default).+They all do much the same operation, but with different defaults, useful+in different situations.+.SS close \-\-clopen+This is useful if migrating balances to a new journal file at the start+of a new year.+It prints a \[dq]closing balances\[dq] transaction that zeroes out+account balances (Asset and Liability accounts, by default), and an+opposite \[dq]opening balances\[dq] transaction that restores them+again.+Typically, you would run+.IP+.EX+hledger close \-\-clopen \-e NEWYEAR >> $LEDGER_FILE+.EE .PP-This is useful when migrating balances to a new journal file at the-start of a new year.-Essentially, you run-\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] and then copy-the closing transaction to the end of the old file and the opening-transaction to the start of the new file.-The opening transaction sets correct starting balances in the new file-when it is used alone, and the closing transaction keeps balances-correct when you use both old and new files together, by cancelling out-the following opening transaction and preventing buildup of duplicated-opening balances.-Think of the closing/opening pair as \[dq]moving the balances into the-next file\[dq].+and then move the opening transaction from the old file to the new file+(and probably also update your LEDGER_FILE environment variable). .PP-You can close a different set of accounts by providing a query.-Eg if you want to include equity, you can add-\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.-(The balancing account is always excluded.)-Revenues and expenses usually are not migrated to a new file directly;-see \f[CR]\-\-retain\f[R] below.+Why might you do this ?+If your reports are fast, you may not need it.+But at some point you will probably want to partition your data by time,+for performance or data integrity or regulatory reasons.+A new file or set of files per year is common.+Then, having each file/fileset \[dq]bookended\[dq] with opening and+closing balance transactions will allow you to freely pick and choose+which files to read \- just the current year, any past year, any+sequence of years, or all of them \- while showing correct account+balances in each case.+The earliest opening balances transaction sets correct starting+balances, and any later closing/opening pairs will harmlessly cancel+each other out. .PP-The generated transactions will have a \f[CR]start:\f[R] tag, with its-value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if-any, for easier matching or exclusion.-When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by-incrementing a number (eg a year number) within the default-journal\[aq]s main file name.-The other modes behave similarly.+The balances will be transferred to and from+\f[CR]equity:opening/closing balances\f[R] by default.+You can override this by using \f[CR]\-\-close\-acct\f[R] and/or+\f[CR]\-\-open\-acct\f[R].+.PP+You can select a different set of accounts to close/open by providing an+account query.+Eg to add Equity accounts, provide arguments like+\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R].+When migrating to a new file, you\[aq]ll usually want to bring along the+AL or ALE accounts, but not the RX accounts (Revenue, Expense).+.PP+Assertions will be added indicating and checking the new balances of the+closed/opened accounts.+.PP+The generated transactions will have a \f[CR]clopen:\f[R] tag.+If the main journal\[aq]s base file name contains a number (eg a year+number), the tag\[aq]s value will be that base file name with the number+incremented.+Or you can choose the tag value yourself, by using+\f[CR]\-\-clopen=TAGVAL\f[R]. .SS close \-\-close This prints just the closing balances transaction of-\f[CR]\-\-migrate\f[R].-It is the default behaviour if you specify no mode flag.-Using the customisation options below, you can move balances from any-set of accounts to a different account.+\f[CR]\-\-clopen\f[R].+It is the default if you don\[aq]t specify a mode.+.PP+More customisation options are described below.+Among other things, you can use \f[CR]close \-\-close\f[R] to generate a+transaction moving the balances from any set of accounts, to a different+account.+(If you need to move just a portion of the balance, see hledger\-move.) .SS close \-\-open This prints just the opening balances transaction of-\f[CR]\-\-migrate\f[R].-It is similar to Ledger\[aq]s equity command.+\f[CR]\-\-clopen\f[R].+(It is similar to Ledger\[aq]s equity command.) .SS close \-\-assert-This prints a \[dq]closing balances\[dq] transaction (with-\f[CR]balances:\f[R] tag), that just declares balance assertions for the-current balances without changing them.+This prints a transaction that asserts the account balances as they are+on the end date (and adds an \f[CR]assert:\f[R] tag). It could be useful as documention and to guard against changes. .SS close \-\-assign-This prints an \[dq]opening balances\[dq] transaction that restores the-account balances using balance assignments.-Balance assignments work regardless of any previous balance, so a-preceding closing balances transaction is not needed.+This prints a transaction that assigns the account balances as they are+on the end date (and adds an \[dq]assign:\[dq] tag).+Unlike balance assertions, assignments will post changes to balances as+needed to reach the specified amounts. .PP-However, omitting the closing balances transaction would unbalance-equity.-This is relatively harmless for personal reports, but it disturbs the-accounting equation, removing a source of error detection.-So \f[CR]\-\-migrate\f[R] is generally the best way to set to set-balances in new files, for now.+This is another way to set starting balances when migrating to a new+file, and it will set them correctly even in the presence of earlier+files which do not have a closing balances transaction.+However, it can hide errors, and disturb the accounting equation, so+\f[CR]\-\-clopen\f[R] is usually recommended. .SS close \-\-retain-This is like \f[CR]\-\-close\f[R] with different defaults: it prints a-\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),-that transfers revenue and expense balances to-\f[CR]equity:retained earnings\f[R].+This is like \f[CR]\-\-close\f[R], but it closes Revenue and Expense+account balances by default.+They will be transferred to \f[CR]equity:retained earnings\f[R], or+another account specified with \f[CR]\-\-close\-acct\f[R]. .PP-This is a different kind of closing, called \[dq]retaining earnings\[dq]-or \[dq]closing the books\[dq]; it is traditionally performed by-businesses at the end of each accounting period, to consolidate revenues-and expenses into the main equity balance.-(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by-another name, kept separate temporarily for reporting purposes.)+Revenues and expenses correspond to changes in equity.+They are categorised separately for reporting purposes, but+traditionally at the end of each accounting period, businesses+consolidate them into equity, This is called \[dq]retaining+earnings\[dq], or \[dq]closing the books\[dq]. .PP-In personal accounting you generally don\[aq]t need to do this, unless-you want the \f[CR]balancesheetequity\f[R] report to show a zero total,-demonstrating that the accounting equation (A\-L=E) is satisfied.+In personal accounting, there\[aq]s not much reason to do this, and most+people don\[aq]t.+(One reason to do it is to help the \f[CR]balancesheetequity\f[R] report+show a zero total, demonstrating that the accounting equation (A\-L=E)+is satisfied.) .SS close customisation In all modes, the following things can be overridden: .IP \[bu] 2@@ -11582,7 +11888,7 @@ 2023\-01\-01: .IP .EX-$ hledger close \-\-migrate \-f 2022.journal \-p 2022+$ hledger close \-\-clopen \-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 .EE@@ -11595,15 +11901,15 @@ .EE .PP For more flexibility, it helps to tag closing and opening transactions-with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances+with eg \f[CR]clopen:NEWYEAR\f[R], then you can ensure correct balances by excluding all opening/closing transactions except the first, like so: .IP .EX-$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]-$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:start=2021 or not tag:start\[aq]-$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:start=2022 or not tag:start\[aq]-$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:start=2021 or not tag:start\[aq]-$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:start=2022 or not tag:start\[aq]+$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]+$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]+$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]+$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]+$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq] $ hledger bs \-Y \-f 2023.j                     # unclosed file, no query needed .EE .SS More detailed close examples

@@ -1,12703 +1,12983 @@-This is hledger.info, produced by makeinfo version 7.1.1 from stdin.--INFO-DIR-SECTION User Applications-START-INFO-DIR-ENTRY-* hledger: (hledger).  Command-line plain text accounting tool.-END-INFO-DIR-ENTRY---File: hledger.info,  Node: Top,  Next: PART 1 USER INTERFACE,  Up: (dir)--hledger(1)-**********--hledger - a robust, friendly plain text accounting app (command line-version).--   'hledger'-or-'hledger COMMAND [OPTS] [ARGS]'-or-'hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]'--   hledger is a robust, user-friendly, cross-platform set of programs-for tracking money, time, or any other commodity, using double-entry-accounting and a simple, editable file format.  hledger is inspired by-and largely compatible with ledger(1), and largely interconvertible with-beancount(1).--   This manual is for hledger's command line interface, version 1.41.-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 open a built-in-copy, at a point of interest, by running-'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'.--   (And for shorter help, try 'hledger --tldr [CMD]'.)--   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::-* Output::-* Environment::-* PART 2 DATA FORMATS::-* Journal::-* CSV::-* Timeclock::-* Timedot::-* PART 3 REPORTING CONCEPTS::-* Time periods::-* Depth::-* Queries::-* Pivoting::-* Generating data::-* Forecasting::-* Budgeting::-* Amount formatting::-* Cost reporting::-* Value reporting::-* PART 4 COMMANDS::-* Help commands::-* User interface commands::-* Data entry commands::-* Basic report commands::-* Standard report commands::-* Advanced report commands::-* Chart commands::-* Data generation commands::-* Maintenance commands::-* PART 5 COMMON TASKS::-* Getting help::-* Constructing command lines::-* Starting a journal file::-* Setting LEDGER_FILE::-* Setting opening balances::-* Recording transactions::-* Reconciling::-* Reporting::-* Migrating to a new file::-* 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 [-f FILE2 ...] 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:--* Text encoding::-* Data formats::-* Standard input::-* Multiple files::-* Strict mode::---File: hledger.info,  Node: Text encoding,  Next: Data formats,  Up: Input--2.1 Text encoding-=================--Data files containing non-ascii characters must use UTF-8 encoding.  An-optional byte order mark (BOM) is allowed, at the beginning of the file-(only).--   Also, your system should be configured with a locale that can decode-UTF-8 text.  On some unix systems, you may need set the 'LANG'-environment variable, eg.  You can read more about this in Unicode-characters, below.--   On unix systems you can check a file's encoding with the 'file'-command.  If you need to import from a UTF-16-encoded CSV file, say, you-can convert it to UTF-8 with the 'iconv' command.---File: hledger.info,  Node: Data formats,  Next: Standard input,  Prev: Text encoding,  Up: Input--2.2 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:                             Automatically used for-                                                  files with extensions:-----------------------------------------------------------------------------'journal'      hledger journal files and some     '.journal' '.j'-               Ledger journals, for               '.hledger' '.ledger'-               transactions-'timeclock'    timeclock files, for precise       '.timeclock'-               time logging-'timedot'      timedot files, for approximate     '.timedot'-               time logging-'csv'          Comma or other character           '.csv'-               separated values, for data-               import-'ssv'          Semicolon separated values         '.ssv'-'tsv'          Tab separated values               '.tsv'-'rules'        CSV/SSV/TSV/other separated        '.rules'-               values, alternate way--   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 containing-tab separated values:--$ hledger -f tsv:/some/file.dat stats---File: hledger.info,  Node: Standard input,  Next: Multiple files,  Prev: Data formats,  Up: Input--2.3 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 write the-format as a prefix, like 'timeclock:' here:--$ 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.4 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.5 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 a summary of commands, run 'hledger' with no arguments.  You-can see the same commands summary at the start of 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: Output,  Prev: Commands,  Up: Top--4 Options-*********--Run 'hledger -h' to see general command line help.  Options can be-written either before or after the command name.  These options are-specific to the 'hledger' CLI:--Flags:-     --conf=CONFFILE        Use extra options defined in this config file. If-                            not specified, searches upward and in XDG config-                            dir for hledger.conf (or .hledger.conf in $HOME).-  -n --no-conf              ignore any config file--   And the following general options are common to most hledger-commands:--General input/data transformation flags:-  -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,-                            inferring format from extension or a FMT: prefix.-                            Can be specified more than once. If not specified,-                            reads from $LEDGER_FILE or $HOME/.hledger.journal.-     --rules=RULESFILE      Use rules defined in this rules file for-                            converting subsequent CSV/SSV/TSV files. If not-                            specified, uses FILE.csv.rules for each FILE.csv.-     --alias=A=B|/RGX/=RPL  transform account names from A to B, or by-                            replacing regular expression matches-     --auto                 generate extra postings by applying auto posting-                            rules ("=") to all transactions-     --forecast[=PERIOD]    Generate extra transactions from periodic rules-                            ("~"), from after the latest ordinary transaction-                            until 6 months from now. Or, during the specified-                            PERIOD (the equals is required). Auto posting rules-                            will also be applied to these transactions. In-                            hledger-ui, also make future-dated transactions-                            visible at startup.-  -I --ignore-assertions    don't check balance assertions by default-     --infer-costs          infer conversion equity postings from costs-     --infer-equity         infer costs from conversion equity postings-     --infer-market-prices  infer market prices from costs-     --pivot=TAGNAME        use a different field or tag as account names-  -s --strict               do extra error checks (and override -I)-     --verbose-tags         add tags indicating generated/modified data--General output/reporting flags (supported by some commands):-  -b --begin=DATE           include postings/transactions on/after this date-  -e --end=DATE             include postings/transactions before this date-                            (with a report interval, will be adjusted to-                            following subperiod end)-  -D --daily                multiperiod report with 1 day interval-  -W --weekly               multiperiod report with 1 week interval-  -M --monthly              multiperiod report with 1 month interval-  -Q --quarterly            multiperiod report with 1 quarter interval-  -Y --yearly               multiperiod report with 1 year interval-  -p --period=PERIODEXP     set begin date, end date, and/or report interval,-                            with more flexibility-     --today=DATE           override today's date (affects relative dates)-     --date2                match/use secondary dates instead (deprecated)-  -U --unmarked             include only unmarked postings/transactions-  -P --pending              include only pending postings/transactions-  -C --cleared              include only cleared postings/transactions-                            (-U/-P/-C can be combined)-  -R --real                 include only non-virtual postings-  -E --empty                Show zero items, which are normally hidden.-                            In hledger-ui & hledger-web, do the opposite.-     --depth=DEPTHEXP       if a number (or -NUM): show only top NUM levels-                            of accounts. If REGEXP=NUM, only apply limiting to-                            accounts matching the regular expression.-  -B --cost                 show amounts converted to their cost/sale amount-  -V --market               Show amounts converted to their value at period-                            end(s) in their default valuation commodity.-                            Equivalent to --value=end.-  -X --exchange=COMM        Show amounts converted to their value at period-                            end(s) in the specified commodity.-                            Equivalent to --value=end,COMM.-     --value=WHEN[,COMM]    show amounts converted to their value on the-                            specified date(s) in their default valuation-                            commodity or a specified commodity. WHEN can be:-                            'then':     value on transaction dates-                            'end':      value at period end(s)-                            'now':      value today-                            YYYY-MM-DD: value on given date-  -c --commodity-style=S    Override a commodity's display style.-                            Eg: -c '.' or -c '1.000,00 EUR'-     --pretty[=YN]          Use box-drawing characters in text output? Can be-                            'y'/'yes' or 'n'/'no'.-                            If YN is specified, the equals is required.--General help flags:-  -h --help                 show command line help-     --tldr                 show command examples with tldr-     --info                 show the manual with info-     --man                  show the manual with man-     --version              show version information-     --debug=[1-9]          show this much debug output (default: 1)-     --pager=YN             use a pager when needed ? y/yes (default) or n/no-     --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)--   Usually hledger accepts any unambiguous flag prefix, eg you can write-'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'.--   If the same option appears more than once in a command, usually the-last (right-most) wins.--   With most commands, arguments are interpreted as a hledger query-which filter the data.  Some queries can be expressed either with-options or with arguments.--   Below are more tips for using the command line interface - feel free-to skip these until you need them.--* Menu:--* Special characters::-* Unicode characters::-* Regular expressions::-* Argument files::-* Config files::-* Shell completions::---File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Up: Options--4.1 Special characters-======================--Here we touch on shell escaping/quoting rules, and give some examples.-This is a slightly complicated topic which you may not need at first,-but you should be aware of it, so you can return here when needed.--   If you are able to minimise the use of special characters in your-data, you won't need escaping as much, and your command lines will be-simpler.  For example, avoiding spaces in account names, and using an-ISO-4217 currency code like 'USD' instead of the '$' currency symbol,-can be helpful.--   But if you want to use spaced account names and '$', go right ahead;-escaping isn't a big deal.--* Menu:--* Escaping shell special characters::-* Escaping on Windows::-* Escaping regular expression special characters::-* Escaping add-on arguments::-* Escaping in other situations::-* Using a wild card::---File: hledger.info,  Node: Escaping shell special characters,  Next: Escaping on Windows,  Up: Special characters--4.1.1 Escaping shell special characters------------------------------------------At the command line, characters which have special meaning for your-shell must be "shell-escaped" (AKA "quoted") if you want hledger to see-them.  Often these include space, '<', '>', '(', ')', '|', '\', '$'-and/or '%'.--   For example, to match an account name containing the phrase "credit-card", don't write this:--$ hledger register credit card--   In that command, "credit" and "card" are treated as separate query-arguments (described below), so this would match accounts containing-either word.  Instead, enclose the phrase in double or single quotes:--$ hledger register "credit card"--   In Unix shells, writing a backslash before the character can also-work.  Eg:--$ hledger register credit\ card--   Some shell characters still have a special meaning inside double-quotes, such as the dollar sign ('$').  Eg in '"assets:$account"', the-bash shell would replace '$account' with the value of a shell variable-with that name.  When you don't want that, use single quotes, which-escape more strongly:--$ hledger balance 'assets:$account'---File: hledger.info,  Node: Escaping on Windows,  Next: Escaping regular expression special characters,  Prev: Escaping shell special characters,  Up: Special characters--4.1.2 Escaping on Windows----------------------------If you are using hledger in a Powershell or Command window on Microsoft-Windows, the escaping rules are different:--   * In a Powershell window ('powershell', blue background), you must-     use double quotes or single quotes (not backslash).-   * In a Command window ('cmd', black background), you must use double-     quotes (not single quotes or backslash).--   The next two sections were written for Unix-like shells, so might-need to be adapted if you're using 'cmd' or 'powershell'.  (Edits-welcome.)---File: hledger.info,  Node: Escaping regular expression special characters,  Next: Escaping add-on arguments,  Prev: Escaping on Windows,  Up: Special characters--4.1.3 Escaping regular expression special characters-------------------------------------------------------Many hledger arguments are regular expressions (described below), and-these too have characters which cause special effects.  Some of those-characters are '.', '^', '$', '[', ']', '(', ')', '|', and '\'.  When-you don't want these to cause special effects, you can "regex-escape"-them by writing '\' (a backslash) before them.  But since backslash is-also special to the shell, you may need to also shell-escape the-backslashes.--   Eg, in the bash shell, to match a literal '$' sign, you could write:--$ hledger balance cur:\\$--   or:--$ hledger balance 'cur:\$'--   (The dollar sign is regex-escaped by the backslash preceding it.-Then that backslash is shell-escaped by another backslash, or by single-quotes.)---File: hledger.info,  Node: Escaping add-on arguments,  Next: Escaping in other situations,  Prev: Escaping regular expression special characters,  Up: Special characters--4.1.4 Escaping add-on arguments----------------------------------When you run an external add-on command with 'hledger' (described-below), any options or arguments being passed through to the add-on-executable lose one level of shell-escaping, so you must add an extra-level of shell-escaping to compensate.--   Eg, in the bash shell, to run the 'ui' add-on and match a literal '$'-sign, you need to write:--$ hledger ui cur:'\\$'--   or:--$ hledger ui cur:\\\\$--   If you are wondering why _four_ backslashes:--   * '$' is unescaped-   * '\$' is regex-escaped-   * '\\$' is regex-escaped, then shell-escaped-   * '\\\\$' is regex-escaped, then shell-escaped, then both slashes are-     shell-escaped once more for hledger argument pass-through.--   Or you can avoid such triple-escaping, by running the add-on-executable directly:--$ hledger-ui cur:\\$---File: hledger.info,  Node: Escaping in other situations,  Next: Using a wild card,  Prev: Escaping add-on arguments,  Up: Special characters--4.1.5 Escaping in other situations-------------------------------------hledger options and arguments are sometimes used in places other than-the command line, with different escaping rules.  For example,-backslash-quoting generally does not work there.  Here are some more-tips.--In Windows 'cmd'   Use double quotes-In Windows         Use single or double quotes-'powershell'-In hledger-ui's    Use single or double quotes-filter prompt-In hledger-web's   Use single or double quotes-search form-In an argument     Don't use spaces, don't shell-escape, do-file               regex-escape when needed-In a config file   Use single or double quotes, and enclose the whole-                   argument ('"desc:a b"' not 'desc:"a b"')-In 'ghci' (the     Use double quotes, and enclose the whole argument-Haskell REPL)---File: hledger.info,  Node: Using a wild card,  Prev: Escaping in other situations,  Up: Special characters--4.1.6 Using a wild card--------------------------When escaping a special character is too much hassle (or impossible),-you can often just write '.' (period) instead.  In regular expressions,-this means "accept any character here".  Eg:--$ hledger register credit.card---File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Options--4.2 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.  On Windows, you may need to use Windows-     Terminal and/or enable UTF-8 support.--   * 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: Options--4.3 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--4.3.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.-  7. they may not (I'm guessing not) properly support right-to-left or-     bidirectional text.--   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,  Next: Config files,  Prev: Regular expressions,  Up: Options--4.4 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'.--   An argument file's format is more restrictive than the command line.-Each line should contain just one option or argument.  Don't use spaces-except inside quotes; write '=' or nothing between a flag and its-argument.  If you use quotes, they must enclose the whole line.  For the-special characters mentioned above, use one less level of quoting than-you would at the command line.---File: hledger.info,  Node: Config files,  Next: Shell completions,  Prev: Argument files,  Up: Options--4.5 Config files-================--With hledger 1.40+, you can save extra command line options and-arguments in a more featureful hledger config file.  Here's a small-example:--# General options are listed first, and used with hledger commands that support them.---pretty--# Options following a `[COMMAND]` heading are used with that hledger command only.-[print]---explicit --show-costs--   To use a config file, specify it with the '--conf' option.  Its-options will be inserted near the start of your command line, so you can-override them with command line options if needed.--   Or, you can set up an automatic config file that is used whenever you-run hledger, by creating 'hledger.conf' in the current directory or-above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or-'hledger.conf' in your XDG config directory-('~/.config/hledger/hledger.conf').--   Here is another example config you could start with:-https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample--   You can put not only options, but also arguments in a config file.-If the first word in a config file's top (general) section does not-begin with a dash (eg: 'print'), it is treated as the command argument-(overriding any argument on the command line).--   On unix machines, you can add a shebang line at the top of a config-file, set executable permission on the file, and use it like a script.-Eg (the '-S' is needed on some operating systems):--#!/usr/bin/env -S hledger --conf--   You can ignore config files by adding the '-n'/'--no-conf' flag to-the command line.  This is useful when using hledger in scripts, or when-troubleshooting.  When both '--conf' and '--no-conf' options are used,-the right-most wins.--   To inspect the processing of config files, use '--debug' or-'--debug=8'.--   *Warning!*--   There aren't many hledger features that need a warning, but this is-one!--   Automatic config files, while convenient, also make hledger less-predictable and dependable.  It's easy to make a config file that-changes a report's behaviour, or breaks your hledger-using-scripts/applications, in ways that will surprise you later.--   If you don't want this,--  1. Just don't create a hledger.conf file on your machine.-  2. Also be alert to downloaded directories which may contain a-     hledger.conf file.-  3. Also if you are sharing scripts or examples or support, consider-     that others may have a hledger.conf file.--   Conversely, once you decide to use this feature, try to remember:--  1. Whenever a hledger command does not work as expected, try it again-     with '-n' ('--no-conf') to see if a config file was to blame.-  2. Whenever you call hledger from a script, consider whether that call-     should use '-n' or not.-  3. Be conservative about what you put in your config file; try to-     consider the effect on all your reports.-  4. To troubleshoot the effect of config files, run with '--debug' or-     '--debug 8'.--   The config file feature was added in hledger 1.40 and is considered-_experimental_.---File: hledger.info,  Node: Shell completions,  Prev: Config files,  Up: Options--4.6 Shell completions-=====================--If you use the bash shell, you can optionally set up context-sensitive-autocompletions when you press TAB in a hledger command line.  At a bash-shell prompt, try pressing 'hledger<SPACE><TAB><TAB>' (should list all-hledger commands) or 'hledger reg acct:<TAB><TAB>' (should list your-top-level account names).  If completions aren't working, or for more-details, see Install > Shell completions.---File: hledger.info,  Node: Output,  Next: Environment,  Prev: Options,  Up: Top--5 Output-********--* Menu:--* Output destination::-* Output format::-* Commodity styles::-* Debug output::---File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output--5.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--5.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:--command               txt   html   csv/tsv   fods   beancount    sql   json--------------------------------------------------------------------------------aregister             Y     Y      Y         Y                         Y-balance               Y     Y      Y         Y                         Y-balancesheet          Y     Y      Y         Y                         Y-balancesheetequity    Y     Y      Y         Y                         Y-cashflow              Y     Y      Y         Y                         Y-incomestatement       Y     Y      Y         Y                         Y-print                 Y     Y      Y         Y      Y            Y     Y-register              Y     Y      Y         Y                         Y--   You can also see which output formats a command supports by running-'hledger CMD -h' and looking for the '-O'/'--output-format=FMT' option,--   You can select the output format by using that option:--$ hledger print -O csv    # print CSV to standard output--   or by choosing a suitable filename extension 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--   Here are some notes about the various output formats.--* Menu:--* Text output::-* HTML output::-* CSV / TSV output::-* FODS output::-* Beancount output::-* SQL output::-* JSON output::---File: hledger.info,  Node: Text output,  Next: HTML output,  Up: Output format--5.2.1 Text output--------------------This is the default: human readable, plain text report output, suitable-for viewing with a monospace font in a terminal.  If your data contains-unicode or wide characters, you'll need a terminal and font that render-those correctly.  (This can be challenging on MS Windows.)--   Some reports ('register', 'aregister') will use the width indicated-by the 'COLUMNS' environment variable.  If your shell and terminal are-working well, they will keep COLUMNS updated as you resize the window.-So register reports normally will use the full window width.  When this-isn't working or you want to override it, you can manually set COLUMNS,-or use the '-w'/'--width' option.--   Balance reports ('balance', 'balancesheet', 'incomestatement'...)-use whatever width they need.  Multi-period multi-currency reports can-often be wider than the window.  Besides using a pager, helpful-techniques for this situation include '--layout=bare', '-V', 'cur:',-'--transpose', '--tree', '--depth', '--drop', switching to html output,-etc.--* Menu:--* Box-drawing characters::-* Colour::-* Paging::---File: hledger.info,  Node: Box-drawing characters,  Next: Colour,  Up: Text output--5.2.1.1 Box-drawing characters-..............................--hledger draws simple table borders by default, to minimise the risk of-display problems caused by a terminal/font not supporting box-drawing-characters.--   But your terminal and font probably do support them, so we recommend-using the '--pretty' flag to show prettier tables in the terminal.  This-is a good flag to add to your hledger config file.---File: hledger.info,  Node: Colour,  Next: Paging,  Prev: Box-drawing characters,  Up: Text output--5.2.1.2 Colour-..............--hledger tries to automatically detect ANSI colour and text styling-support and use it when appropriate.  (Currently, it is used rather-minimally: some reports show negative numbers in red, and help output-uses bold text for emphasis.)--   You can override this by setting the 'NO_COLOR' environment variable-to disable it, or by using the '--color/--colour' option, perhaps in-your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or-off.---File: hledger.info,  Node: Paging,  Prev: Colour,  Up: Text output--5.2.1.3 Paging-..............--In unix-like environments, when displaying large output (in any output-format) in the terminal, hledger tries to use a pager when appropriate.-The pager shows one page of text at a time, and lets you scroll around-to see more.  While it is active, usually 'SPACE' shows the next page,-'h' shows help, and 'q' quits.  The home/end/page up/page down/cursor-keys, and mouse scrolling, may also work.--   hledger will use the pager specified by the 'PAGER' environment-variable, otherwise 'less' if available, otherwise 'more' if available.-(With one exception: 'hledger help -p TOPIC' will always use 'less', so-that it can scroll to the topic.)--   The pager is expected to display hledger's ANSI colour and text-styling.  If you see junk characters, you might need to configure your-pager to handle ANSI codes.  Or you could disable colour as described-above.--   If you are using the 'less' pager, hledger automatically appends a-number of options to the 'LESS' variable to enable ANSI colour and a-number of other conveniences.  (At the time of writing: -chop-long-lines--hilite-unread -ignore-case -mouse -no-init -quit-at-eof--quit-if-one-screen -RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines--use-backslash -use-color ).  If these don't work well, you can set your-preferred options in the 'HLEDGER_LESS' variable, which will be used-instead.---File: hledger.info,  Node: HTML output,  Next: CSV / TSV output,  Prev: Text output,  Up: Output format--5.2.2 HTML output--------------------HTML output can be styled by an optional 'hledger.css' file in the same-directory.--   HTML output will be UTF-8 encoded.  If your web browser is showing-junk characters, you may need to change its text encoding to UTF-8.  Eg-in Safari, see View -> Text Encoding and Settings -> Advanced -> Default-Encoding.---File: hledger.info,  Node: CSV / TSV output,  Next: FODS output,  Prev: HTML output,  Up: Output format--5.2.3 CSV / TSV output-------------------------In CSV or TSV output, digit group marks (such as thousands separators)-are disabled automatically.---File: hledger.info,  Node: FODS output,  Next: Beancount output,  Prev: CSV / TSV output,  Up: Output format--5.2.4 FODS output--------------------FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by-LibreOffice and OpenOffice.  If you use their spreadsheet applications,-this is better than CSV because it works across locales (decimal point-vs.  decimal comma, character encoding stored in XML header, thus no-problems with umlauts), it supports fixed header rows and columns, cell-types (string vs.  number vs.  date), separation of number and currency-(currency is displayed but the cell type is still a number accessible-for computation), styles (bold), borders.  Btw.  you can still extract-CSV from FODS/ODS using various utilities like 'libreoffice --headless'-or ods2csv.---File: hledger.info,  Node: Beancount output,  Next: SQL output,  Prev: FODS output,  Up: Output format--5.2.5 Beancount output-------------------------This is Beancount's journal format.  You can use this to export your-hledger data to Beancount, eg to use the Fava web app.--   hledger will try to adjust your data to suit Beancount,-automatically.  Be cautious and check the conversion until you are-confident it is good.  If you plan to export to Beancount often, you may-want to follow its conventions, for a cleaner conversion:--   * use Beancount-friendly account names-   * use currency codes instead of currency symbols-   * use cost notation instead of equity conversion postings-   * avoid virtual postings--   There is one big adjustment you must handle yourself: for Beancount,-the top level account names must be 'Assets', 'Liabilities', 'Equity',-'Income', and/or 'Expenses'.  You can use account aliases to rewrite-your account names temporarily, if needed, as in this-hledger2beancount.conf config file.--* Menu:--* Beancount account names::-* Beancount commodity names::-* Beancount virtual postings::-* Beancount metadata::-* Beancount costs::-* Beancount operating currency::---File: hledger.info,  Node: Beancount account names,  Next: Beancount commodity names,  Up: Beancount output--5.2.5.1 Beancount account names-...............................--Aside from the top-level names, hledger will adjust your account names-to make valid Beancount account names, by capitalising each part,-replacing spaces with '-', replacing other unsupported characters with-'C<HEXBYTES>', prepending 'A' to account name parts which don't begin-with a letter or digit, and appending ':A' to account names which have-only one part.---File: hledger.info,  Node: Beancount commodity names,  Next: Beancount virtual postings,  Prev: Beancount account names,  Up: Beancount output--5.2.5.2 Beancount commodity names-.................................--hledger will adjust your commodity names to make valid Beancount-commodity/currency names, which must be 2-24 uppercase letters, digits,-or ''', '.', '_', '-', beginning with a letter and ending with a letter-or digit.  hledger will convert known currency symbols to ISO 4217-currency codes, capitalise letters, replace spaces with '-', replace-other unsupported characters with 'C<HEXBYTES>', and prepend or append-'C' if needed.---File: hledger.info,  Node: Beancount virtual postings,  Next: Beancount metadata,  Prev: Beancount commodity names,  Up: Beancount output--5.2.5.3 Beancount virtual postings-..................................--Beancount doesn't allow virtual postings; if you have any, they will be-omitted from beancount output.---File: hledger.info,  Node: Beancount metadata,  Next: Beancount costs,  Prev: Beancount virtual postings,  Up: Beancount output--5.2.5.4 Beancount metadata-..........................--hledger tags will be converted to Beancount metadata (except for tags-whose name begins with '_').  Metadata names will be adjusted to be-Beancount-compatible: beginning with a lowercase letter, at least two-characters long, and with unsupported characters encoded.  Metadata-values will use Beancount's string type.--   In hledger, objects can have the same tag repeated with multiple-values.  Eg an 'assets:cash' account might have both 'type:Asset' and-'type:Cash' tags.  For Beancount these will be combined into one, with-the values combined, comma separated.  Eg: 'type: "Asset, Cash"'.---File: hledger.info,  Node: Beancount costs,  Next: Beancount operating currency,  Prev: Beancount metadata,  Up: Beancount output--5.2.5.5 Beancount costs-.......................--Beancount doesn't allow redundant costs and conversion postings as-hledger does.  If you have any of these, the conversion postings will be-omitted.  Currently we support at most one cost + conversion postings-group per transaction.---File: hledger.info,  Node: Beancount operating currency,  Prev: Beancount costs,  Up: Beancount output--5.2.5.6 Beancount operating currency-....................................--Declaring an operating currency (or several) improves Beancount and Fava-reports.  Currently hledger will declare each currency used in cost-amounts as an operating currency.  If needed, replace these with your-own declaration, like--option "operating_currency" "USD"---File: hledger.info,  Node: SQL output,  Next: JSON output,  Prev: Beancount output,  Up: Output format--5.2.6 SQL output-------------------SQL output is expected to work at least with SQLite, MySQL and Postgres.--   The SQL statements are expected to be executed in the empty database.-If you already have tables created via SQL output of hledger, you would-probably want to either clear data from these (via 'delete' or-'truncate' SQL statements) or 'drop' the tables completely before-import; otherwise your postings would be duplicated.--   For SQLite, it is 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' | ...--   This is not yet much used; feedback is welcome.---File: hledger.info,  Node: JSON output,  Prev: SQL output,  Up: Output format--5.2.7 JSON output--------------------Our JSON is rather large and verbose, since it is a faithful-representation of hledger's internal data types.  To understand its-structure, read the Haskell type definitions, which are mostly in-https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.-hledger-web's OpenAPI specification may also be relevant.--   hledger stores numbers with sometimes up to 255 significant digits.-This is too many digits for most JSON consumers, so in JSON output we-round numbers to at most 10 decimal places.  (We don't limit the number-of integer digits.)  If you find this causing problems, please let us-know.  Related: #1195--   This is not yet much used; feedback is welcome.---File: hledger.info,  Node: Commodity styles,  Next: Debug output,  Prev: Output format,  Up: Output--5.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.--   In some cases hledger will adjust number formatting to improve their-parseability (such as adding trailing decimal marks when needed).---File: hledger.info,  Node: Debug output,  Prev: Commodity styles,  Up: Output--5.4 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--   (This option doesn't work in a config file yet.)---File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top--6 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.--   *HLEDGER_LESS* If 'less' is your pager, this variable specifies the-'less' options hledger should use.  (Otherwise, 'LESS' + custom options-are used.)--   *LEDGER_FILE* The main journal file to use when not specified with-'-f/--file'.  Default: '$HOME/.hledger.journal'.--   *NO_COLOR* If this environment variable exists (with any value,-including empty), hledger will not use ANSI color codes in terminal-output, unless overridden by an explicit '--color=y' or '--colour=y'-option.---File: hledger.info,  Node: PART 2 DATA FORMATS,  Next: Journal,  Prev: Environment,  Up: Top--7 PART 2: DATA FORMATS-**********************---File: hledger.info,  Node: Journal,  Next: CSV,  Prev: PART 2 DATA FORMATS,  Up: Top--8 Journal-*********--hledger's usual data source is a plain text file containing journal-entries in hledger 'journal' format.  If you're looking for a quick-reference, jump ahead to the journal cheatsheet (or use the table of-contents at https://hledger.org/hledger.html).--   This file represents an accounting General Journal.  The '.journal'-file extension is most often used, though not strictly 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 add-ons-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.--   A hledger journal file can contain three kinds of thing: comment-lines, transactions, and/or directives (including periodic transaction-rules and auto posting rules).  Understanding the journal file format-will also give you a good understanding of hledger's data model.  Here's-a quick cheatsheet/overview, followed by detailed descriptions of each-part.--* Menu:--* Journal cheatsheet::-* Comments::-* Transactions::-* Dates::-* Status::-* Code::-* Description::-* Transaction comments::-* Postings::-* Account names::-* Amounts::-* Balance assertions::-* Posting comments::-* Transaction balancing::-* 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: Comments,  Up: Journal--8.1 Journal cheatsheet-======================--# Here is the main syntax of hledger's journal format-# (omitting extra Ledger compatibility syntax).--###############################################################################--# 1. These are comment lines, for notes or temporarily disabling things.-; They begin with # or ;--comment-Or, lines can be enclosed within "comment" / "end comment".-This is a block of -commented lines.-end comment--# Some journal entries can have semicolon comments at end of line  ; like this-# Some of them require 2 or more spaces before the semicolon.--###############################################################################--# 2. Directives customise processing or output in some way.-# You don't need any directives to get started.-# But they can add more error checking, or change how things are displayed.-# They begin with a word, letter, or symbol. -# They are most often placed at the top, before transactions.--account assets             ; Declare valid account names and display order.-account assets:savings     ; A subaccount. This one represents a bank account.-account assets:checking    ; Another. Note, 2+ spaces after the account name.-account assets:receivable  ; Accounting type is inferred from english names,-account passifs            ; or declared with a "type" tag, type:L-account expenses           ; type:X-                           ; A follow-on comment line, indented.-account expenses:rent      ; Expense and revenue categories are also accounts.-                           ; Subaccounts inherit their parent's type.--commodity $0.00         ; Declare valid commodities and their display styles.-commodity 1.000,00 EUR--decimal-mark .          ; The decimal mark used in this file (if ambiguous).--payee Whole Foods       ; Declare a valid payee name.--tag trip                ; Declare a valid tag name.--P 2024-03-01 AAPL $179  ; Declare a market price for AAPL in $ on this date.--include other.journal   ; Include another journal file here.--# Declare a recurring "periodic transaction", for budget/forecast reports-~ monthly  set budget goals  ; <- Note, 2+ spaces before the description.-    (expenses:rent)      $1000-    (expenses:food)       $500--# Declare an auto posting rule, to modify existing transactions in reports-= revenues:consulting-    liabilities:tax:2024:us          *0.25  ; Add a tax liability & expense-    expenses:tax:2024:us            *-0.25  ; for 25% of the revenue.--###############################################################################--# 3. Transactions are what it's all about.-# They are dated events, usually movements of money between 2 or more accounts.-# They begin with a numeric date.-# Here is their basic shape:-#-# DATE DESCRIPTION    ; The transaction's date and optional description.-#   ACCOUNT1  AMOUNT  ; A posting of an amount to/from this account, indented.-#   ACCOUNT2  AMOUNT  ; A second posting, balancing the first.-#   ...               ; More if needed. Amounts must sum to zero.-#                     ; Note, 2+ spaces between account names and amounts.--2024-01-01 opening balances         ; At the start, declare pre-existing balances this way.-    assets:savings          $10000  ; Account names can be anything. lower case is easy to type.-    assets:checking          $1000  ; assets, liabilities, equity, revenues, expenses are common.-    liabilities:credit card  $-500  ; liabilities, equity, revenues balances are usually negative.-    equity:start                    ; One amount can be left blank. $-10500 is inferred here.-                                    ; Some of these accounts we didn't declare above,-                                    ; so -s/--strict would complain.--2024-01-03 ! (12345) pay rent-    ; Additional transaction comment lines, indented.-    ; There can be a ! or * after the date meaning "pending" or "cleared".-    ; There can be a parenthesised (code) after the date/status.-                                    ; Amounts' sign shows direction of flow.-    assets:checking          $-500  ; Minus means removed from this account (credit).-    expenses:rent             $500  ; Plus means added to this account (debit).--; Keeping transactions in date order is optional (but helps error checking).--2024-01-02 Gringott's Bank | withdrawal  ; Description can be PAYEE | NOTE-    assets:bank:gold       -10 gold-    assets:pouch            10 gold--2024-01-02 shopping-    expenses:clothing        1 gold-    expenses:wands           5 gold-    assets:pouch            -6 gold--2024-01-02 receive gift-    revenues:gifts          -3 "Chocolate Frogs"  ; Complex commodity symbols-    assets:pouch             3 "Chocolate Frogs"  ; must be in double quotes.--2024-01-15 buy some shares, in two lots                 ; Cost can be noted.-    assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  means per-unit cost-    assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ means total cost-                      ; ^ Per-lot subaccounts are sometimes useful.-    assets:checking                 $-7--2024-01-15 assert some account balances on this date-    ; Balances can be asserted in any transaction, with =, for extra error checking.-    ; Assertion txns like this one can be made with hledger close --assert --show-costs-    ;-    assets:savings                    $0                   = $10000-    assets:checking                   $0                   =   $493-    assets:bank:gold                   0 gold              =    -10 gold-    assets:pouch                       0 gold              =      4 gold-    assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"-    assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50-    assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4-    liabilities:credit card           $0                   =  $-500--2024-02-01 note some event, or a transaction not yet fully entered, on this date-    ; Postings are not required.--; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).-2024.01.01-2024/1/1---File: hledger.info,  Node: Comments,  Next: Transactions,  Prev: Journal cheatsheet,  Up: Journal--8.2 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--8.3 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--8.4 Dates-=========--* Menu:--* Simple dates::-* Posting dates::---File: hledger.info,  Node: Simple dates,  Next: Posting dates,  Up: Dates--8.4.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--8.4.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--8.5 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 (and you can combine these, eg-'-UP' to match all except cleared things).  Or you can use the-'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in-hledger-ui.--   (Note: in Ledger the "unmarked" state is called "uncleared"; in-hledger we renamed it to "unmarked" for semantic clarity.)--   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--8.6 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--8.7 Description-===============--After the date, status mark and/or code fields, the rest of the line (or-until a comment is begun with ';') is the transaction's description.-Here you can describe the transaction (called the "narration" in-traditional bookkeeping), or you can record a payee/payer name, or you-can leave it empty.--   Transaction descriptions show up in print output and in register-reports, and can be listed with the descriptions command.--   You can query by description with 'desc:DESCREGEX', or pivot on-description with '--pivot desc'.--* Menu:--* Payee and note::---File: hledger.info,  Node: Payee and note,  Up: Description--8.7.1 Payee and note-----------------------Sometimes people want a dedicated payee/payer field that can be queried-and checked more strictly.  If you want that, you can write a '|' (pipe)-character in the description.  This divides it into a "payee" field on-the left, and a "note" field on the right.  (Either can be empty.)--   You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX',-list their values with the payees and notes commands, or pivot on-'payee' or 'note'.--   Note: in transactions with no '|' character, description, payee, and-note all have the same value.  Once a '|' is added, they become-distinct.  (If you'd like to change this behaviour, please propose it on-the mail list.)--   If you want more strict error checking, you can declare the valid-payee names with payee directives, and then enforce these with hledger-check payees.  (Note: because of the above, for this you'll need to-ensure every transaction description contains a '|' and therefore a-checkable payee name, even if it's empty.)---File: hledger.info,  Node: Transaction comments,  Next: Postings,  Prev: Description,  Up: Journal--8.8 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--8.9 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.--   If the amount is positive, it is being added to the account; if-negative, it is being removed from the account.--   The posting amounts in a transaction must sum up to zero, indicating-that the inflows and outflows are equal.  We call this a balanced-transaction.  (You can read more about the nitty-gritty details of "sum-up to zero" in Transaction balancing below.)--   As a convenience, you can optionally leave one amount blank; hledger-will infer what it should be so as to balance the transaction.--* Menu:--* Debits and credits::-* The two space delimiter::---File: hledger.info,  Node: Debits and credits,  Next: The two space delimiter,  Up: Postings--8.9.1 Debits and credits---------------------------The traditional accounting concepts of debit and credit of course exist-in hledger, but we represent them with numeric sign, as described above.-Positive and negative posting amounts represent debits and credits-respectively.--   You don't need to remember that, but if you would like to - eg for-helping newcomers or for talking with your accountant - here's a handy-mnemonic:--   _'debit / plus / left / short words'_-_'credit / minus / right / longer words'_---File: hledger.info,  Node: The two space delimiter,  Prev: Debits and credits,  Up: Postings--8.9.2 The two space delimiter--------------------------------Be sure to notice the unusual separator between the account name and the-following amount.  Because hledger allows account names with spaces in-them, you must separate the account name and amount (if any) by *two or-more spaces* (or tabs).  It's easy to forget at first.  If you ever see-the amount being treated as part of the account name, you'll know you-probably need to add another space between them.---File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: Journal--8.10 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: Balance assertions,  Prev: Account names,  Up: Journal--8.11 Amounts-============--After the account name, there is usually an amount.  (Remember: 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::-* Costs::---File: hledger.info,  Node: Decimal marks,  Next: Digit group marks,  Up: Amounts--8.11.1 Decimal marks-----------------------A _decimal mark_ can be written as a period or a comma:--1.23-1,23--   Both of these are common in international number formats, so hledger-is not biased towards one or the other.  Because hledger also supports-digit group marks (eg thousands separators), this means that a number-like '1,000' or '1.000' containing just one period or comma is-ambiguous.  In such cases, hledger by default assumes it is a decimal-mark, and will parse both of those as 1.--   To help hledger parse such ambiguous numbers more accurately, if you-use digit group marks, we recommend declaring the decimal mark-explicitly.  The best way is to add a 'decimal-mark' directive at the-top of each data file, like this:--decimal-mark .--   Or you can declare it per commodity with 'commodity' directives,-described below.--   hledger also accepts numbers like '10.' with no digits after the-decimal mark (and will sometimes display numbers that way to-disambiguate them - see Trailing decimal marks).---File: hledger.info,  Node: Digit group marks,  Next: Commodity,  Prev: Decimal marks,  Up: Amounts--8.11.2 Digit group marks---------------------------In the integer part of the amount quantity (left of the decimal mark),-groups of digits can optionally be separated by a _digit group mark_ - a-comma or period (whichever is not used as decimal mark), or a space-(several Unicode space variants, like no-break space, are also-accepted).  So these are all valid amounts in a journal file:--     $1,000,000.00-  EUR 2.000.000,00-INR 9,99,99,999.00-      1 000 000.00   ; <- ordinary space  -      1 000 000.00   ; <- no-break space---File: hledger.info,  Node: Commodity,  Next: Costs,  Prev: Digit group marks,  Up: Amounts--8.11.3 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.--   By default, the format of amounts in the journal influences how-hledger displays them in output.  This is explained in Commodity display-style below.---File: hledger.info,  Node: Costs,  Prev: Commodity,  Up: Amounts--8.11.4 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.---File: hledger.info,  Node: Balance assertions,  Next: Posting comments,  Prev: Amounts,  Up: Journal--8.12 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 costs::-* Assertions and commodities::-* Assertions and subaccounts::-* Assertions and status::-* 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--8.12.1 Assertions and ordering---------------------------------hledger calculates and checks an account's balance assertions in date-order (and when there are multiple assertions on the same day, in parse-order).  Note this is different from Ledger, which checks assertions-always in parse order, ignoring dates.--   This means in hledger you can freely reorder transactions, postings,-or files, and balance assertions will usually keep working.  The-exception is when you reorder multiple postings on the same day, to the-same account, which have balance assertions; those will likely need-updating.---File: hledger.info,  Node: Assertions and multiple included files,  Next: Assertions and multiple -f files,  Prev: Assertions and ordering,  Up: Balance assertions--8.12.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 costs,  Prev: Assertions and multiple included files,  Up: Balance assertions--8.12.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 costs,  Next: Assertions and commodities,  Prev: Assertions and multiple -f files,  Up: Balance assertions--8.12.4 Assertions and costs------------------------------Balance assertions ignore costs, and should normally be written without-one:--2019/1/1-  (a)     $1 @ €1 = $1--   We do allow costs to be written in balance assertion amounts,-however, and print shows them, but 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-costs), and because balance _assignments_ do use costs (see below).---File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and subaccounts,  Prev: Assertions and costs,  Up: Balance assertions--8.12.5 Assertions and commodities------------------------------------The balance assertions described so far are "*single commodity balance-assertions*": they assert and check the balance in one commodity,-ignoring any others that may be present.  This is how balance assertions-work in Ledger also.--   If an account contains multiple commodities, you can assert their-balances by writing multiple postings with balance assertions, one for-each commodity:--2013/1/1-  usd   $-1-  eur   €-1-  both--2013/1/2-  both    0 = $1-  both    0 = €1--   In hledger you can make a stronger "*sole commodity balance-assertion*" by writing two equals signs ('== EXPECTEDBALANCE').  This-also asserts that there are no other commodities in the account besides-the asserted one (or at least, that their current balance is zero):--2013/1/1-  usd   $-1  == $-1  ; these sole commodity assertions succeed-  eur   €-1  == €-1-  both      ;==  $1  ; this one would fail because 'both' contains $ and €--   It's less easy to make a "*sole commodities balance assertion*" (note-the plural) - ie, asserting that an account contains two or more-specified commodities and no others.  It can be done by--  1. isolating each commodity in a subaccount, and asserting those-  2. and also asserting there are no commodities in the parent account-     itself:--2013/1/1-  usd       $-1-  eur       €-1-  both        0 == 0   ; nothing up my sleeve-  both:usd   $1 == $1  ; a dollar here-  both:eur   €1 == €1  ; a euro there---File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and status,  Prev: Assertions and commodities,  Up: Balance assertions--8.12.6 Assertions and subaccounts------------------------------------All of the balance assertions above (both '=' and '==') are-"*subaccount-exclusive balance assertions*"; they ignore any balances-that exist in deeper subaccounts.--   In hledger you can make "*subaccount-inclusive balance assertions*"-by adding a star after the equals ('=*' or '==*'):--2019/1/1-  equity:start-  assets:checking  $10-  assets:savings   $10-  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else---File: hledger.info,  Node: Assertions and status,  Next: Assertions and virtual postings,  Prev: Assertions and subaccounts,  Up: Balance assertions--8.12.7 Assertions and status-------------------------------Balance assertions always consider postings of all statuses (unmarked,-pending, or cleared); they are not affected by the '-U'/'--unmarked' /-'-P'/'--pending' / '-C'/'--cleared' flags or the 'status:' query.---File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and status,  Up: Balance assertions--8.12.8 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--8.12.9 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--8.12.10 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: Transaction balancing,  Prev: Balance assertions,  Up: Journal--8.13 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: Transaction balancing,  Next: Tags,  Prev: Posting comments,  Up: Journal--8.14 Transaction balancing-==========================--How exactly does hledger decide when a transaction is balanced ?  The-general goal is that if you look at the journal entry and calculate the-amounts' sum perfectly with pencil and paper, hledger should agree with-you.--   Real world transactions, especially for investments or-cryptocurrencies, often involve imprecise costs, complex decimals,-and/or infinitely-recurring decimals, which are difficult or-inconvenient to handle on a computer.  So to be a practical accounting-system, hledger allows some imprecision when checking transaction-balancedness.  The question is, how much imprecision should be allowed ?--   hledger currently decides it based on the commodity display styles:-if the postings' sum would appear to be zero when displayed with the-standard display precisions, the transaction is considered balanced.--   Or equivalently: if the journal entry is displayed with amounts-rounded to the standard display precisions (with 'hledger print---round=hard'), and a human with pencil and paper would agree that those-displayed amounts add up to zero, the transaction is considered-balanced.--   This has some advantages: it is fairly intuitive, general not-hard-coded, yet configurable when needed.  On the downside it means that-transaction balancedness is related to commodity display precisions, so-eg when using '-c/--commodity-style' to display things with more than-usual precision, you might need to fix some of your journal entries (ie,-add decimal digits to make them balance more precisely).--   Other PTA tools (Ledger, Beancount..)  have their own ways of doing-it.  Possible improvements are discussed at #1964.--   Note: if you have multiple journal files, and are relying on-commodity directives to make imprecise journal entries balance, the-directives' placement might be important - see 'commodity' directive.---File: hledger.info,  Node: Tags,  Next: Directives,  Prev: Transaction balancing,  Up: Journal--8.15 Tags-=========--Tags are a way to add extra labels or data fields to transactions,-postings, or accounts.  They are usually a word or hyphenated word,-immediately followed by a full colon, written within the comment of a-transaction, a posting, or an 'account' directive.  (Yes, storing data-in comments is slightly weird!)--   You can write each tag on its own comment line, or multiple tags on-one line, separated by commas.  Tags can also have a value, which is any-text after the colon until the next comma or end of line, excluding-surrounding whitespace.  (hledger tag values can't contain commas.)  If-the same tag name appears multiple times in a comment, each name:value-pair is preserved.--   An example: in this journal there are six tags, one of them with a-value:--account assets:checking         ; accounttag:-account expenses:food--2017/1/16 bought groceries      ; transactiontag:-    ; transactiontag2:-    assets:checking        $-1-     ; posting-tag-1:, (belongs to the posting above)-    expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value--* Menu:--* Querying with tags::-* Displaying tags::-* When to use tags ?::-* Tag names::-* Special tags::---File: hledger.info,  Node: Querying with tags,  Next: Displaying tags,  Up: Tags--8.15.1 Querying with tags----------------------------Tags are most often used to select a subset of data; you can match-tagged things by tag name and or tag value with a 'tag:' query.  (See-queries below.)--   When querying for tag names or values, note that postings inherit-tags from their transaction and from their account, and transactions-acquire tags from their postings.  So in the example above, - the-assets:checking posting effectively has four tags (one of its own, one-from the account, two from the transaction) - the expenses:food posting-effectively has four tags (two of its own, two from the transaction) --the transaction effectively has all six tags (two of its own, and two-from each posting)---File: hledger.info,  Node: Displaying tags,  Next: When to use tags ?,  Prev: Querying with tags,  Up: Tags--8.15.2 Displaying tags-------------------------You can use the 'tags' command to list tag names or values.--   The 'print' command also shows tags.--   You can use -pivot to display tag values in other reports, in various-ways (eg appended to account names, like pseudo subaccounts).---File: hledger.info,  Node: When to use tags ?,  Next: Tag names,  Prev: Displaying tags,  Up: Tags--8.15.3 When to use tags ?----------------------------Tags provide more dimensions of categorisation, complementing accounts-and transaction descriptions.  When to use each of these is somewhat a-matter of taste.  Accounts have the most built-in support, and regex-queries on descriptions are also quite powerful.  So you may not need-tags at all.  But if you want to track multiple cross-cutting-categories, they can be a good fit.  For example, you could tag-trip-related transactions with 'trip: YEAR:PLACE', without disturbing-your usual account categories.---File: hledger.info,  Node: Tag names,  Next: Special tags,  Prev: When to use tags ?,  Up: Tags--8.15.4 Tag names-------------------What is allowed in a tag name ?  Currently, most non-whitespace-characters.  Eg '😀:' is a valid tag.--   For extra error checking, you can declare valid tag names with the-'tag' directive, and then enforce these with the 'check' command.--   But note that tags are detected quite loosely at present, sometimes-where you didn't intend them.  Eg '; see https://foo.com' contains a-'https' tag with value '//foo.com'.---File: hledger.info,  Node: Special tags,  Prev: Tag names,  Up: Tags--8.15.5 Special tags----------------------Some tag names have special significance to hledger.  They are explained-elsewhere, but here's a quick reference:-- type                   -- declares an account's type- date                   -- overrides a posting's date- date2                  -- overrides a posting's secondary date- assert                 -- appears on txns generated by close --assert- retain                 -- appears on txns generated by close --retain- start                  -- appears on txns generated by close --migrate/--close/--open/--assign- t                      -- appears on postings generated from timedot letters-- generated-transaction  -- appears on txns generated by a periodic rule- modified-transaction   -- appears on txns which have had auto postings added- generated-posting      -- appears on generated postings- cost-posting           -- appears on postings which have (or could have) a cost,-                           and which have equivalent conversion postings in the transaction- conversion-posting     -- appears on postings which are to a V/Conversion account-                           and which have an equivalent cost posting in the transaction--   The second group above (generated-transaction, etc.)  are normally-hidden, with a '_' prefix added.  This means 'print' doesn't show them-by default; but you can still use them in queries.  You can add the-'--verbose-tags' flag to make them visible, which can be useful for-troubleshooting.---File: hledger.info,  Node: Directives,  Next: account directive,  Prev: Tags,  Up: Journal--8.16 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--8.16.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--8.16.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,N,Y,Y-     all amounts in all files 2.  the display style for all amounts-     of this commodity 3.  the decimal mark for parsing amounts of-     this commodity, in the rest of this file and its children, if-     there is no 'decimal-mark' directive 4.  the precision to use-     for balanced-transaction checking in this commodity, in this-     file and its children.  Takes precedence over 'D'.-     Subdirectives: 'format' (ignored).  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--8.17 '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.-   * They can store additional account information as comments, or as-     tags which can be used to filter or pivot reports.-   * They can restrict which accounts may be posted to by transactions,-     eg in strict mode, which helps prevent errors.-   * They influence account display order in reports, allowing-     non-alphabetic sorting (eg Revenues to appear above Expenses).-   * They can help hledger know your accounts' types (asset, liability,-     equity, revenue, expense), enabling reports like balancesheet and-     incomestatement.-   * They help with account name completion (in hledger add,-     hledger-web, hledger-iadd, ledger-mode, etc.)--   They are written as the word 'account' followed by a hledger-style-account name.  Eg:--account assets:bank:checking--   Ledger-style indented subdirectives are also accepted, but ignored:--account assets:bank:checking-  format subdirective  ; currently ignored--* Menu:--* Account comments::-* Account error checking::-* Account display order::-* Account types::---File: hledger.info,  Node: Account comments,  Next: Account error checking,  Up: account directive--8.17.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 error checking,  Next: Account display order,  Prev: Account comments,  Up: account directive--8.17.2 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, or when you-run 'hledger check accounts', 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.-   * If you use the -infer-equity flag, you will also need declarations-     for the account names it generates.---File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive--8.17.3 Account display order-------------------------------Account directives also cause hledger to display accounts in a-particular order, not just alphabetically.  Eg, here is a conventional-ordering for the top-level accounts:--account assets-account liabilities-account equity-account revenues-account expenses--   Now hledger displays them in that order:--$ hledger accounts-assets-liabilities-equity-revenues-expenses--   If there are undeclared accounts, those will be displayed last, in-alphabetical order.--   Sorting is done within each group of sibling accounts, at each level-of the account tree.  Eg, a declaration like 'account parent:child'-influences 'child''s position among its siblings.--   Note, it does not affect 'parent''s position; for that, you need an-'account parent' declaration.--   Sibling accounts are always displayed together; hledger won't display-'x:y' in between 'a:b' and 'a:c'.--   An account directive both declares an account as a valid posting-target, and declares its display order; you can't easily do one without-the other.---File: hledger.info,  Node: Account types,  Prev: Account display order,  Up: account directive--8.17.4 Account types-----------------------hledger knows that accounts come in several types: assets, liabilities,-expenses and so on.  This enables easy reports like balancesheet and-incomestatement, and filtering by account type with the 'type:' query.--   As a convenience, hledger will detect these account types-automatically if you are using common english-language top-level account-names (described below).  But it's more robust to declare accounts'-types explicitly, by adding 'type:' tags to their account directives.-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).)--   Subaccounts inherit their parent's type, or they can override it.-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--8.18 '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--8.18.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--8.18.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--8.18.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--8.18.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--8.18.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--8.18.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--8.18.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--8.19 '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 how all amounts in this commodity should be displayed,-     eg how many decimals to show.  See Commodity display style above.--  3. (If no 'decimal-mark' directive is in effect:) It sets the decimal-     mark to expect (period or comma) when parsing amounts in this-     commodity, in this file and files it includes, from the directive-     until end of current file.  See Decimal marks above.--  4. It declares the precision with which this commodity's amounts-     should be compared when checking for balanced transactions,-     anywhere in this file and files it includes, until end of current-     file.--   Declaring commodities solves several common parsing/display problems,-so we recommend it.--   Note that effects 3 and 4 above end at the end of the directive's-file, and will not affect sibling or parent files.  So if you are-relying on them (especially 4) and using multiple files, placing your-commodity directives in a top-level parent file might be important.  Or,-keep your decimal marks unambiguous and your entries well balanced and-precise.--   (Related: #793)--* Menu:--* Commodity directive syntax::-* Commodity error checking::---File: hledger.info,  Node: Commodity directive syntax,  Next: Commodity error checking,  Up: commodity directive--8.19.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--8.19.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--8.20 '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--8.21 '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--8.22 '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--8.23 '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--8.24 '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; 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--8.25 Periodic transactions-==========================--The '~' directive declares a "periodic rule" which generates temporary-extra transactions, usually recurring at some interval, when hledger is-run with the '--forecast' flag.  These "forecast transactions" are-useful for forecasting future activity.  They exist only for the-duration of the report, and only when '--forecast' is used; they are not-saved in the journal file by hledger.--   Periodic rules also have a second use: with the '--budget' flag they-set budget goals for budgeting.--   Periodic rules can be a little tricky, so before you use them, read-this whole section, or at least the following 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--8.25.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--8.25.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--8.25.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--8.26 Auto postings-==================--The '=' directive declares an "auto posting rule", which adds extra-postings to existing transactions.  (Remember, postings are the account-name & amount lines below a transaction's date & description.)--   In the journal, an auto posting rule looks quite like a transaction,-but instead of date and description it has '=' (mnemonic: "match") and a-query, like this:--= QUERY-    ACCOUNT    AMOUNT-    ...--   Queries are just like command line queries; an account name substring-is most common.  Query terms containing spaces should be enclosed in-single or double quotes.--   Each '=' rule works like this: when hledger is run with the '--auto'-flag, wherever the QUERY matches a posting in the journal, the rule's-postings are added to that transaction, immediately below the matched-posting.  Note these generated postings are temporary, existing only for-the duration of the report, and only when '--auto' is used; they are not-saved in the journal file by hledger.--   Generated postings' amounts can depend on the matched posting's-amount.  So auto postings can be useful for, eg, adding tax postings-with a standard percentage.  AMOUNT can be:--   * a number with no commodity symbol, like '2'.  The matched posting's-     commodity symbol will be added to this.--   * a normal amount with a commodity symbol, like '$2'.  This will be-     used as-is.--   * an asterisk followed by a number, like '*2'.  This will multiply-     the matched posting's amount (and total price, if any) by the-     number.--   * an asterisk followed by an amount with commodity symbol, like-     '*$2'.  This multiplies and also replaces the commodity symbol with-     this new one.--   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--   Note that depending fully on generated data such as this has some-drawbacks - it's less portable, less future-proof, less auditable by-others, and less robust (eg your balance assertions will depend on-whether you use or don't use '--auto').  An alternative is to use auto-postings in "one time" fashion - use them to help build a complex-journal entry, view it with 'hledger print --auto', and then copy that-output into the journal file to make it permanent.--* Menu:--* Auto postings and multiple files::-* 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 multiple files,  Next: Auto postings and dates,  Up: Auto postings--8.26.1 Auto postings and multiple files------------------------------------------An auto posting rule can affect any transaction in the current file, or-in any parent file or child file.  Note, currently it will not affect-sibling files (when multiple '-f'/'--file' are used - see #1212).---File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Prev: Auto postings and multiple files,  Up: Auto postings--8.26.2 Auto postings and dates---------------------------------A posting date (or secondary date) in the matched posting, or (taking-precedence) a posting date in the auto posting rule itself, will also be-used in the generated posting.---File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings--8.26.3 Auto postings and transaction balancing / inferred amounts /----------------------------------------------------------------------balance assertions Currently, auto postings are added:--   * after missing amounts are inferred, and transactions are checked-     for balancedness,-   * but before balance assertions are checked.--   Note this means that journal entries must be balanced both before and-after auto postings are added.  This changed in hledger 1.12+; see #893-for background.--   This also means that you cannot have more than one auto-posting with-a missing amount applied to a given transaction, as it will be unable to-infer amounts.---File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings--8.26.4 Auto posting tags---------------------------Automated postings will have some extra tags:--   * 'generated-posting:= QUERY' - shows this was generated by an auto-     posting rule, and the query-   * '_generated-posting:= QUERY' - a hidden tag, which does not appear-     in hledger's output.  This can be used to match postings generated-     "just now", rather than generated in the past and saved to the-     journal.--   Also, any transaction that has been changed by auto posting rules-will have these tags added:--   * 'modified:' - this transaction was modified-   * '_modified:' - a hidden tag not appearing in the comment; this-     transaction was modified "just now".---File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings--8.26.5 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--8.27 Other syntax-=================--hledger journal format supports quite a few other features, mainly to-make interoperating with or converting from Ledger easier.  Note some of-the features below are powerful and can be useful in special cases, but-in general, features in this section are considered less important or-even not recommended for most users.  Downsides are mentioned to help-you decide if you want to use them.--* Menu:--* Balance assignments::-* Bracketed posting dates::-* D directive::-* apply account directive::-* Y directive::-* Secondary dates::-* Star comments::-* Valuation expressions::-* Virtual postings::-* Other Ledger directives::-* Other cost/lot notations::---File: hledger.info,  Node: Balance assignments,  Next: Bracketed posting dates,  Up: Other syntax--8.27.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 costs::-* Balance assignments and multiple files::---File: hledger.info,  Node: Balance assignments and costs,  Next: Balance assignments and multiple files,  Up: Balance assignments--8.27.1.1 Balance assignments and costs-......................................--A cost in a balance assignment will cause the calculated amount to have-that cost 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 costs,  Up: Balance assignments--8.27.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--8.27.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--8.27.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 current file.--   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--8.27.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--8.27.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--8.27.6 Secondary dates-------------------------A secondary date is written after the primary date, following an equals-sign: 'DATE1=DATE2'.  If the year is omitted, the primary date's year is-assumed.  When running reports, the primary (left side) date is used by-default, but with the '--date2' flag ('--aux-date' or'--effective' also-work, for Ledger users), the secondary (right side) date will be used-instead.--   The meaning of secondary dates is up to you.  Eg it could be "primary-is the bank's clearing date, secondary is the date the transaction was-initiated, if different".--   In practice, this feature usually adds confusion:--   * You have to remember the primary and secondary dates' meaning, and-     follow that consistently.-   * It splits your bookkeeping into two modes, and you have to remember-     which mode is appropriate for a given report.-   * Usually your balance assertions will work with only one of these-     modes.-   * It makes your financial data more complicated, less portable, and-     less clear in an audit.-   * It interacts with every feature, creating an ongoing cost for-     implementors.-   * It distracts new users and supporters.-   * Posting dates are simpler and work better.--   So secondary dates are officially deprecated in hledger, remaining-only as a Ledger compatibility aid; we recommend using posting dates-instead.---File: hledger.info,  Node: Star comments,  Next: Valuation expressions,  Prev: Secondary dates,  Up: Other syntax--8.27.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--8.27.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--8.27.9 Virtual postings--------------------------A posting with parentheses around the account name, like '(some:account)-10', is called an _unbalanced virtual posting_.  These 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,  Next: Other cost/lot notations,  Prev: Virtual postings,  Up: Other syntax--8.27.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: Other cost/lot notations,  Prev: Other Ledger directives,  Up: Other syntax--8.27.11 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: CSV,  Next: Timeclock,  Prev: Journal,  Up: Top--9 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 expects this rules file to be named like the CSV-file, with an extra '.rules' extension added, 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' option.--   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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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.--   Posting comments can also contain a posting date.  A secondary date,-or a year-less date, will be ignored.---File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names--9.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--9.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--9.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--9.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 the Working with CSV tips below for more about setting amounts-and currency.---File: hledger.info,  Node: if block,  Next: Matchers,  Prev: Field names,  Up: CSV--9.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--9.14 Matchers-=============--There are two kinds of matcher:--  1. A whole record matcher is simplest: it is just a word, single-line-     text fragment, or other regular expression, which hledger will try-     to match case-insensitively anywhere within the CSV record.-     Eg: 'whole foods'.--  2. A field matcher has a percent-prefixed CSV field number or name-     before the pattern.-     Eg: '%3 whole foods' or '%description whole foods'.-     hledger will try to match the pattern just within the named CSV-     field.--   When using these, there's two things to be aware of:--  1. Whole record matchers don't see the exact original record; they see-     a reconstruction of it, in which values are comma-separated, and-     quotes enclosing values and whitespace outside those quotes are-     removed.-     Eg when reading an SSV record like: '2023-01-01 ; "Acme, Inc. " ;-     1,000'-     the whole record matcher sees instead: '2023-01-01,Acme, Inc.-     ,1,000'--  2. Field matchers expect either a CSV field number, or a CSV field-     name declared with 'fields'.  (Don't use a hledger field name here,-     unless it is also a CSV field name.)  A non-CSV field name will-     cause the matcher to match against '""' (the empty string), and-     does not raise an error, allowing easier reuse of common rules with-     different CSV files.--   You can also prefix a matcher with '!' (and optional space) to negate-it.  Eg '! whole foods', '! %3 whole foods', '!%description whole foods'-will match if "whole foods" is NOT present.  _Added in 1.32._--   The pattern 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 with it, see "Regular-expressions" in the hledger manual-(https://hledger.org/hledger.html#regular-expressions).--* Menu:--* Multiple matchers::-* Match groups::---File: hledger.info,  Node: Multiple matchers,  Next: Match groups,  Up: Matchers--9.14.1 Multiple matchers---------------------------When an if block has multiple matchers, each on its own line,--   * By default they are OR'd (any of them can match).-   * Matcher lines beginning with '&' (and optional space) are AND'ed-     with the matcher above (all in the AND'ed group must match).--   _(Since 1.41:)_ You can use a negated '!' matcher on a '&' line,-meaning AND NOT.---File: hledger.info,  Node: Match groups,  Prev: Multiple matchers,  Up: Matchers--9.14.2 Match groups----------------------_Added in 1.32_--   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--9.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,...-; Comment line that explains MATCHERC-MATCHERC,VALUE1,VALUE2,...-<empty line>--   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).  You can use the-comment lines in the table body.  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; If multiple lines match, later-lines will override fields assigned by the earlier ones - just like the-sequence of 'if' blocks would behave.--   If table presented above is equivalent to this sequence of if blocks:--if MATCHERA-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--if MATCHERB-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--; Comment line which explains MATCHERC-if MATCHERC-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--   Example:--if,account2,comment-atm transaction fee,expenses:business:banking,deductible? check it-%description groceries,expenses:groceries,-;; Comment line that desribes why this particular date is special-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--9.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--9.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--9.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--9.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--9.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--9.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--9.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--9.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 specify a rules file with '--rules', 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--9.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--9.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--9.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--9.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--9.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--9.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--9.18.12 Amount decimal places--------------------------------When you are reading CSV data, eg with a command like 'hledger -f-foo.csv print', hledger will infer each commodity's decimal precision-(and other commodity display styles) from the amounts - much as when-reading a journal file without 'commodity' directives (see the link).--   Note, the commodity styles are not inferred from the numbers in the-original CSV data; rather, they are inferred from the amounts generated-by the CSV rules.--   When you are importing CSV data with the 'import' command, eg-'hledger import foo.csv', there's another step: 'import' tries to make-the new entries conform to the journal's existing styles.  So for each-commodity - let's say it's EUR - 'import' will choose:--  1. the style declared for EUR by a 'commodity' directive in the-     journal-  2. otherwise, the style inferred from EUR amounts in the journal-  3. otherwise, the style inferred from EUR amounts generated by the CSV-     rules.--   TLDR: if 'import' is not generating the precisions or styles you-want, add a 'commodity' directive to specify them.---File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Working with CSV--9.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--9.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--9.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--9.19 CSV rules examples-=======================--* Menu:--* Bank of Ireland::-* Coinbase::-* Amazon::-* Paypal::---File: hledger.info,  Node: Bank of Ireland,  Next: Coinbase,  Up: CSV rules examples--9.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--9.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--9.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--9.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--10 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 these shell aliases at the command line:--     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 Emacs's built-in timeclock.el, or the extended timeclock-x.el,-     and perhaps the extras in ledgerutils.el--   * 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--11 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.--        * _Added in 1.32_ 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.--   Timedot files don't support directives like journal files.  So a-common pattern is to have a main journal file (eg 'time.journal') that-contains any needed directives, and then includes the timedot file-('include time.timedot').--* Menu:--* Timedot examples::---File: hledger.info,  Node: Timedot examples,  Up: Timedot--11.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: Time periods,  Prev: Timedot,  Up: Top--12 PART 3: REPORTING CONCEPTS-*****************************---File: hledger.info,  Node: Time periods,  Next: Depth,  Prev: PART 3 REPORTING CONCEPTS,  Up: Top--13 Time periods-***************--* Menu:--* Report start & end date::-* Smart dates::-* Report intervals::-* Date adjustments::-* Period headings::-* Period expressions::---File: hledger.info,  Node: Report start & end date,  Next: Smart dates,  Up: Time periods--13.1 Report start & end date-============================--Most hledger reports will by default show the full time period-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 period, such as the current-month.  You can specify a start and/or end date with the '-b/--begin',-'-e/--end', or '-p/--period' options, or a 'date:' query argument,-described below.  All of these accept the smart date syntax, also-described below.--   End dates are exclusive; specify the day after the last day you want-to see in the report.--   When dates are specified by multiple options, the last (right-most)-option wins.  And when 'date:' queries and date options are combined,-the report period will be their intersection.--   Examples:--'-b 2016/3/17'--     beginning on St.  Patrick's day 2016-'-e 12/1'--     ending at the start of December 1st in the current year-'-p 'this month''--     during the current month-'-p thismonth'--     same as above, spaces are optional-'-b 2023'--     beginning on the first day of 2023-'date:2023..' or 'date:2023-'--     same as above--   '-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020' :-during January 2020 (the smallest common period, with the -p overriding--b and -e)---File: hledger.info,  Node: Smart dates,  Next: Report intervals,  Prev: Report start & end date,  Up: Time periods--13.2 Smart dates-================--In hledger's user interfaces (though not in the journal file), you can-optionally use "smart date" syntax.  Smart dates can be written with-english words, can be relative, and can have parts omitted.  Missing-parts are inferred as 1, when needed.  Smart dates can be interpreted as-dates or periods depending on context.--   Examples:--   '2004-01-01', '2004/10/1', '2004.9.1', '20240504' :-Exact dates.  The year must have at least four digits, the month must be-1-12, the day must be 1-31, the separator can be '-' or '/' or '.' or-nothing.--'2004-10'--     start of month-'2004'--     start of year-'10/1' or 'oct' or 'october'--     October 1st in current year-'21'--     21st day in current month-'yesterday, today, tomorrow'--     -1, 0, 1 days from today-'last/this/next day/week/month/quarter/year'--     -1, 0, 1 periods from the current period-'in n days/weeks/months/quarters/years'--     n periods from the current period-'n days/weeks/months/quarters/years ahead'--     n periods from the current period-'n days/weeks/months/quarters/years ago'--     -n periods from the current period-'20181201'--     8 digit YYYYMMDD with valid year month and day-'201812'--     6 digit YYYYMM with valid year and month--   Dates with no separators are allowed but might give surprising-results if mistyped:--   * '20181301' (YYYYMMDD with an invalid month) is parsed as an-     eight-digit year-   * '20181232' (YYYYMMDD with an invalid day) gives a parse error-   * '201801012' (a valid YYYYMMDD followed by additional digits) gives-     a parse error--   The meaning of relative dates depends on today's date.  If you need-to test or reproduce old reports, you can use the '--today' option to-override that.  (Except for periodic transaction rules, which are not-affected by '--today'.)---File: hledger.info,  Node: Report intervals,  Next: Date adjustments,  Prev: Smart dates,  Up: Time periods--13.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 adjustments,  Next: Period headings,  Prev: Report intervals,  Up: Time periods--13.4 Date adjustments-=====================--* Menu:--* Start date adjustment::-* End date adjustment::---File: hledger.info,  Node: Start date adjustment,  Next: End date adjustment,  Up: Date adjustments--13.4.1 Start date adjustment-------------------------------If you let hledger infer a report's start date, it will adjust the date-to the previous natural boundary of the report interval, for convenient-periodic reports.  (If you don't want that, specify a start date.)--   For example, if the journal's first transaction is on january 10th,--   * 'hledger register' (no report interval) will start the report on-     january 10th.-   * 'hledger register --monthly' will start the report on the previous-     month boundary, january 1st.-   * 'hledger register --monthly --begin 1/5' will start the report on-     january 5th [1].--   Also if you are generating transactions or budget goals with periodic-transaction rules, their start date may be adjusted in a similar way (in-certain situations).---File: hledger.info,  Node: End date adjustment,  Prev: Start date adjustment,  Up: Date adjustments--13.4.2 End date adjustment-----------------------------A report's end date is always adjusted to include a whole number of-intervals, so that the last subperiod has the same length as the others.--   For example, if the journal's last transaction is on february 20th,--   * 'hledger register' will end the report on february 20th.-   * 'hledger register --monthly' will end the report at the end of-     february.-   * 'hledger register --monthly --end 2/14' also will end the report at-     the end of february.-   * 'hledger register --monthly --begin 1/5 --end 2/14' will end the-     report on march 4th [1].--   [1] Since hledger 1.29.---File: hledger.info,  Node: Period headings,  Next: Period expressions,  Prev: Date adjustments,  Up: Time periods--13.5 Period headings-====================--With non-standard subperiods, hledger will show "STARTDATE..ENDDATE"-headings.  With standard subperiods (ie, starting on a natural interval-boundary), you'll see more compact headings, which are usually-preferable.  (Though month names will be in english, currently.)--   So if you are specifying a start date and you want compact headings:-choose a start of year for yearly reports, a start of quarter for-quarterly reports, a start of month for monthly reports, etc.-(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start-of year, or '2024-04' or '202404' or 'Apr' for a start of month or-quarter.)--   For weekly reports, choose a date that's a Monday.  (You can try-different dates until you see the short headings, or write eg '-b '3-weeks ago''.)---File: hledger.info,  Node: Period expressions,  Prev: Period headings,  Up: Time periods--13.6 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--13.6.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--13.6.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]' ('31st day' will be adjusted to each-     month's last day)-   * 'every Nth WEEKDAYNAME [of month]'--   Yearly on a custom month and 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--13.6.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--14 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.--   In place of a single number which limits the depth for all accounts,-you can also provide separate depth limits for different accounts using-regular expressions _(since 1.41)_.--   For example, '--depth assets=2' (or, equivalently: 'depth:assets=2')-will collapse accounts matching the regular expression 'assets' to depth-2.  So 'assets:bank:savings' would be collapsed to 'assets:bank', while-'liabilities:bank:credit card' would not be affected.  This can be-combined with a flat depth to collapse other accounts not matching the-regular expression, so '--depth assets=2 --depth 1' would collapse-'assets:bank:savings' to 'assets:bank' and 'liabilities:bank:credit-card' to 'liabilities'.--   You can supply multiple depth arguments and they will all be applied,-so '--depth assets=2 --depth liabilities=3 --depth 1' would collapse:--   * accounts matching 'assets' to depth 2,-   * accounts matching 'liabilities' to depth 3,-   * all other accounts to depth 1.--   If an account is matched by more than one regular expression depth-argument then the more specific one will used.  For example, if '--depth-assets=1 --depth assets:bank:savings=2' is provided, then-'assets:bank:savings' will be collapsed to depth 2 rather than depth 1.-This is because 'assets:bank:savings' matches at level 3 in the account-name, while 'assets' matches at level 1.  The same would be true with-the argument '--depth assets=1 --depth savings=2'.---File: hledger.info,  Node: Queries,  Next: Pivoting,  Prev: Depth,  Up: Top--15 Queries-**********--One of hledger's strengths is being able to quickly report on a precise-subset of your data.  Most hledger commands accept query arguments, to-restrict their scope.  Multiple query terms can be provided to build up-a more complex query.--   * By default, a query term is interpreted as a case-insensitive-     substring pattern for matching account names:--     'car:fuel'-     'dining groceries'--   * Patterns containing spaces or other special characters must be-     enclosed in single or double quotes:--     ''personal care''--   * These patterns are actually regular expressions, so you can add-     regexp metacharacters for more precision (see "Regular expressions"-     above for details):--     ''^expenses\b''-     ''food$''-     ''fuel|repair''-     ''accounts (payable|receivable)''--   * To match something other than account name, add one of the query-     type prefixes described in "Query types" below:--     'date:202312-'-     'status:'-     'desc:amazon'-     'cur:USD'-     'cur:\\$'-     'amt:'>0''--   * Add a 'not:' prefix to negate a term:--     'not:status:'*''-     'not:desc:'opening|closing''-     'not:cur:USD'--   * Terms with different types are AND-ed, terms with the same type are-     OR-ed (mostly; see "Combining query terms" below).  The following-     query:--     'date:2022 desc:amazon desc:amzn'--     is interpreted as:--     _date is in 2022 AND ( transaction description contains "amazon" OR-     "amzn" )_--* Menu:--* Query types::-* Combining query terms::-* Queries and command options::-* Queries and account aliases::-* Queries and valuation::---File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: Queries--15.1 Query types-================--Here are the types of query term available.--* Menu:--* acct query::-* amt query::-* code query::-* cur query::-* desc query::-* date query::-* date2 query::-* depth query::-* expr query::-* not query::-* note query::-* payee query::-* real query::-* status query::-* type query::-* tag query::---File: hledger.info,  Node: acct query,  Next: amt query,  Up: Query types--15.1.1 acct: query---------------------*'acct:REGEX'*, or just *'REGEX'*-Match account names containing this case insensitive regular expression.-This is the default query type, so we usually don't bother writing the-"acct:" prefix.---File: hledger.info,  Node: amt query,  Next: code query,  Prev: acct query,  Up: Query types--15.1.2 amt: query--------------------*'amt:N, amt:'<N', 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.  'amt:'-needs quotes to hide the less than/greater than sign from the command-line shell.---File: hledger.info,  Node: code query,  Next: cur query,  Prev: amt query,  Up: Query types--15.1.3 code: query---------------------*'code:REGEX'*-Match by transaction code (eg check number).---File: hledger.info,  Node: cur query,  Next: desc query,  Prev: code query,  Up: Query types--15.1.4 cur: query--------------------*'cur:REGEX'*-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX. (Contrary to-hledger's usual infix matching.  To do infix matching, write-'.*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 will usually need one more level-of escaping.  Eg to match the dollar sign: 'cur:\\$' or 'cur:'\$''---File: hledger.info,  Node: desc query,  Next: date query,  Prev: cur query,  Up: Query types--15.1.5 desc: query---------------------*'desc:REGEX'*-Match transaction descriptions.---File: hledger.info,  Node: date query,  Next: date2 query,  Prev: desc query,  Up: Query types--15.1.6 date: query---------------------*'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'.---File: hledger.info,  Node: date2 query,  Next: depth query,  Prev: date query,  Up: Query types--15.1.7 date2: query----------------------*'date2:PERIODEXPR'*-If you use secondary dates: this matches secondary dates within the-specified period.  It is not affected by the '--date2' flag.---File: hledger.info,  Node: depth query,  Next: expr query,  Prev: date2 query,  Up: Query types--15.1.8 depth: query----------------------*'depth:[REGEXP=]N'*-Match (or display, depending on command) accounts at or above this-depth, optionally only for accounts matching a provided regular-expression.  See Depth for detailed rules.---File: hledger.info,  Node: expr query,  Next: not query,  Prev: depth query,  Up: Query types--15.1.9 expr: query---------------------*'expr:'QUERYEXPR''*-'expr' lets you write more complicated query expressions with AND, OR,-NOT, and parentheses.-Eg: 'expr:'date:lastmonth and not (food or rent)''-The expression should be enclosed in quotes.  See Combining query terms-below.---File: hledger.info,  Node: not query,  Next: note query,  Prev: expr query,  Up: Query types--15.1.10 not: query---------------------*'not:QUERYTERM'*-You can prepend *'not:'* to any other query term to negate the match.-Eg: 'not:equity', 'not:desc:apple'-(Also, a trick: 'not:not:...' can sometimes solve query problems-conveniently..)---File: hledger.info,  Node: note query,  Next: payee query,  Prev: not query,  Up: Query types--15.1.11 note: query----------------------*'note:REGEX'*-Match transaction notes (the part of the description right of '|', or-the whole description if there's no '|').---File: hledger.info,  Node: payee query,  Next: real query,  Prev: note query,  Up: Query types--15.1.12 payee: query-----------------------*'payee:REGEX'*-Match transaction payee/payer names (the part of the description left of-'|', or the whole description if there's no '|').---File: hledger.info,  Node: real query,  Next: status query,  Prev: payee query,  Up: Query types--15.1.13 real: query----------------------*'real:, real:0'*-Match real or virtual postings respectively.---File: hledger.info,  Node: status query,  Next: type query,  Prev: real query,  Up: Query types--15.1.14 status: query------------------------*'status:, status:!, status:*'*-Match unmarked, pending, or cleared transactions respectively.---File: hledger.info,  Node: type query,  Next: tag query,  Prev: status query,  Up: Query types--15.1.15 type: query----------------------*'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.---File: hledger.info,  Node: tag query,  Prev: type query,  Up: Query types--15.1.16 tag: query---------------------*'tag:NAMEREGEX[=VALREGEX]'*-Match by tag name, and optionally also by tag value.  Note:--   * Both regular expressions do infix matching.  If you need a complete-     match, use '^' and '$'.-     Eg: 'tag:'^fullname$'', 'tag:'^fullname$=^fullvalue$'-   * To match values, ignoring names, do 'tag:.=VALREGEX'-   * 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.---File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries--15.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 query terms using 'and', 'or', 'not' keywords-(case insensitive), and to group them by enclosing in parentheses.--   Some examples:--   * Exclude account names containing 'food':--     'expr:"not food"' ('not:food' is equivalent)--   * Match things which have 'cool' in the description and the 'A' tag:--     'expr:"desc:cool and tag:A"' ('expr:"desc:cool tag:A"' is-     equivalent)--   * Match things which either do not reference the 'expenses:food'-     account, or do have the 'A' tag:--     'expr:"not expenses:food or tag:A"'--   * Match things which either do not reference the 'expenses:food'-     account, or which reference the 'expenses:drink' account and also-     have the 'A' tag:--     'expr:"expenses:food or (expenses:drink and tag:A)"'--   'expr:' has a restriction: 'date:' queries may not be used inside-'or' expressions.  That would allow disjoint report periods or disjoint-result sets, with unclear semantics for our reports.---File: hledger.info,  Node: Queries and command options,  Next: Queries and account aliases,  Prev: Combining query terms,  Up: Queries--15.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 account aliases,  Next: Queries and valuation,  Prev: Queries and command options,  Up: Queries--15.4 Queries and account aliases-================================--When account names are rewritten with '--alias' or 'alias', 'acct:' will-match either the old or the new account name.---File: hledger.info,  Node: Queries and valuation,  Prev: Queries and account aliases,  Up: Queries--15.5 Queries and valuation-==========================--When amounts are converted to other commodities in cost or value-reports, 'cur:' and 'amt:' match the old commodity symbol and the old-amount quantity, not the new ones.  (Except in hledger 1.22, #1625.)---File: hledger.info,  Node: Pivoting,  Next: Generating data,  Prev: Queries,  Up: Top--16 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--17 Generating data-******************--hledger can enrich the data provided to it, or generate new data, in a-number of ways.  Mostly, this is done only if you request it:--   * Missing amounts or missing costs in transactions are inferred-     automatically when possible.-   * The '--infer-equity' flag infers missing conversion equity postings-     from @/@@ costs.-   * The '--infer-costs' flag infers missing costs from conversion-     equity postings.-   * The '--infer-market-prices' flag infers 'P' price directives from-     costs.-   * The '--auto' flag adds extra postings to transactions matched by-     auto posting rules.-   * The '--forecast' option generates transactions from periodic-     transaction rules.-   * The 'balance --budget' report infers budget goals from periodic-     transaction rules.-   * Commands like 'close', 'rewrite', and 'hledger-interest' generate-     transactions or postings.-   * CSV data is converted to transactions by applying CSV conversion-     rules..  etc.--   Such generated data is temporary, existing only at report time.  You-can convert it to permanent recorded data by, eg, capturing the output-of 'hledger print' and saving it in your journal file.  This can-sometimes be useful as a data entry aid.--   If you are curious what data is being generated and why, run 'hledger-print -x --verbose-tags'.  '-x/--explicit' shows inferred amounts and-'--verbose-tags' adds tags like 'generated-transaction' (from periodic-rules) and 'generated-posting', 'modified' (from auto posting rules).-Similar hidden tags (with an underscore prefix) are always present,-also, so you can always match such data with queries like-'tag:generated' or 'tag:modified'.---File: hledger.info,  Node: Forecasting,  Next: Budgeting,  Prev: Generating data,  Up: Top--18 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--18.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.--   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--18.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 occurrence 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--18.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--18.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--18.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--18.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: Amount formatting,  Prev: Forecasting,  Up: Top--19 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: Amount formatting,  Next: Cost reporting,  Prev: Budgeting,  Up: Top--20 Amount formatting-********************--* Menu:--* Commodity display style::-* Rounding::-* Trailing decimal marks::-* Amount parseability::---File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Up: Amount formatting--20.1 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.  Here's an example:--# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive)-# 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--   But for convenience, 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,  Next: Trailing decimal marks,  Prev: Commodity display style,  Up: Amount formatting--20.2 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: Trailing decimal marks,  Next: Amount parseability,  Prev: Rounding,  Up: Amount formatting--20.3 Trailing decimal marks-===========================--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 Decimal 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---File: hledger.info,  Node: Amount parseability,  Prev: Trailing decimal marks,  Up: Amount formatting--20.4 Amount parseability-========================--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: Cost reporting,  Next: Value reporting,  Prev: Amount formatting,  Up: Top--21 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--21.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--21.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--21.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--21.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.--   Note you will need to add account declarations for these to your-journal, if you use 'check accounts' or 'check --strict'.---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--21.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:--   * 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--21.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--21.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--22 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::-* --value Flexible valuation::-* 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--22.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--22.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--22.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--22.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--22.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: --value Flexible valuation,  Prev: --infer-market-prices market prices from transactions,  Up: Value reporting--22.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: --value Flexible valuation,  Next: Valuation examples,  Prev: Valuation commodity,  Up: Value reporting--22.7 -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: Valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: Value reporting--22.8 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--   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: Valuation examples,  Up: Value reporting--22.9 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.--   Related: #1625---File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: Value reporting--22.10 Effect of valuation on reports-====================================--Here is a reference for how valuation is supposed to affect each part of-hledger's reports.  (It's wide, you may need to scroll sideways.)  It-may be useful when troubleshooting.  If you find problems, please report-them, ideally with a reproducible example.  Related: #329, #1083.--   First, a quick 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).--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.---File: hledger.info,  Node: PART 4 COMMANDS,  Next: Help commands,  Prev: Value reporting,  Up: Top--23 PART 4: COMMANDS-*******************--Here are the standard commands, which you can list by running 'hledger'.-If you have installed more add-on commands, they also will be listed.--   *Help commands*--   * help - show the hledger manual with info/man/pager-   * demo - show small hledger demos in the terminal--   *User interface commands*--   * ui - (if installed) run hledger's terminal UI-   * web - (if installed) run hledger's web UI--   *Data entry commands*--   * add - add transactions using terminal prompts-   * import - add new transactions from other files, eg CSV files--   *Basic report commands*--   * accounts - show account names-   * 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--   *Standard report commands*--   * print - show transactions or export journal data-   * aregister (areg) - show transactions in a particular account-   * register (reg) - show postings in one or more accounts & running-     total-   * 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--   *Advanced report commands*--   * balance (bal) - show balance changes, end balances, budgets,-     gains..-   * roi - show return on investments--   *Chart commands*--   * activity - show bar charts of posting counts per period--   *Data generation commands*--   * close - generate balance-zeroing/restoring transactions-   * rewrite - generate auto postings, like print -auto--   *Maintenance commands*--   * check - check for various kinds of error in the data-   * diff - compare account transactions in two journal files-   * test - run self tests--   Next, these commands are described in detail.---File: hledger.info,  Node: Help commands,  Next: User interface commands,  Prev: PART 4 COMMANDS,  Up: Top--24 Help commands-****************--* Menu:--* help::-* demo::---File: hledger.info,  Node: help,  Next: demo,  Up: Help commands--24.1 help-=========--Show the hledger user manual with 'info', 'man', or a pager.  With a-(case insensitive) TOPIC argument, try to open it at that section-heading.--Flags:-  -i                       show the manual with info-  -m                       show the manual with man-  -p                       show the manual with $PAGER or less-                           (less is always used if TOPIC is specified)--   This command shows the hledger manual built in to your hledger-executable.  It can be useful when offline, or when you prefer the-terminal to a web browser, or when the appropriate hledger manual or-viewers are not installed properly on your system.--   By default it chooses the best viewer found in $PATH, trying in this-order: 'info', 'man', '$PAGER', 'less', 'more', stdout.  (If a TOPIC is-specified, '$PAGER' and 'more' are not tried.)  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 if running non-interactively, it just prints the manual-to stdout.--   When using 'info', TOPIC can match either the full heading or a-prefix.  If your 'info --version' is < 6, you'll need to upgrade it, eg-with ''brew install texinfo'' on mac.--   When using 'man' or 'less', TOPIC must match the full heading.  For a-prefix match, you can write ''TOPIC.*''.--   Examples--$ hledger help -h                 # show the help command's usage-$ hledger help                    # show the manual with info, man or $PAGER-$ hledger help 'time periods'     # show the manual's "Time periods" topic-$ hledger help 'time periods' -m  # use man, even if info is installed---File: hledger.info,  Node: demo,  Prev: help,  Up: Help commands--24.2 demo-=========--Play demos of hledger usage in the terminal, if asciinema is installed.--Flags:-  -s --speed=SPEED         playback speed (1 is original speed, .5 is half, 2-                           is double, etc (default: 2))--   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: User interface commands,  Next: Data entry commands,  Prev: Help commands,  Up: Top--25 User interface commands-**************************--* Menu:--* ui::-* web::---File: hledger.info,  Node: ui,  Next: web,  Up: User interface commands--25.1 ui-=======--Runs hledger-ui (if installed).---File: hledger.info,  Node: web,  Prev: ui,  Up: User interface commands--25.2 web-========--Runs hledger-web (if installed).---File: hledger.info,  Node: Data entry commands,  Next: Basic report commands,  Prev: User interface commands,  Up: Top--26 Data entry commands-**********************--* Menu:--* add::-* import::---File: hledger.info,  Node: add,  Next: import,  Up: Data entry commands--26.1 add-========--Record new transactions with interactive prompting in the console.--Flags:-     --no-new-accounts      don't allow creating new accounts--   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.-   * 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.--   Notes:--   * If you enter a number with no commodity symbol, and you have-     declared a default commodity with a 'D' directive, you might expect-     'add' to add this symbol for you.  It does not do this; we assume-     that if you are using a 'D' directive you prefer not to see the-     commodity symbol repeated on amounts in the journal.--   Examples:--   * Record new transactions, saving to the default journal file:--     'hledger add'--   * Add transactions to 2024.journal, but also load 2023.journal for-     completions:--     'hledger add --file 2024.journal --file 2023.journal'--   * Provide answers for the first four prompts:--     'hledger add today 'best buy' expenses:supplies '$20''--   There is a detailed tutorial at https://hledger.org/add.html.---File: hledger.info,  Node: import,  Prev: add,  Up: Data entry commands--26.2 import-===========--Import new transactions from one or more data files to the main journal.--Flags:-     --catchup              just mark all transactions as already imported-     --dry-run              just show the transactions to be imported--   This command detects new transactions in one or more data files-specified as arguments, and appends them to the main journal.--   You can import from any input file format hledger supports, but-CSV/SSV/TSV files, downloaded from financial institutions, are the most-common import source.--   The import destination is the default journal file, or another-specified in the usual way with '$LEDGER_FILE' or '-f/--file'.  It-should be in journal format.--   Examples:--$ hledger import bank1-checking.csv bank1-savings.csv--$ hledger import *.csv--* Menu:--* Import preview::-* Overlap detection::-* First import::-* Importing balance assignments::-* Import and commodity styles::-* Import special cases::---File: hledger.info,  Node: Import preview,  Next: Overlap detection,  Up: import--26.2.1 Import preview------------------------It's useful to preview the import by running first with '--dry-run', to-sanity check the range of dates being imported, and to check the effect-of your conversion rules if converting from CSV. Eg:--$ hledger import bank.csv --dry-run--   The dry run output is valid journal format, so hledger can re-parse-it.  If the output is large, you could show just the uncategorised-transactions like so:--$ hledger import --dry-run bank.csv | hledger -f- -I print unknown--   You could also run this repeatedly to see the effect of edits to your-conversion rules:--$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'--   Once the conversion and dates look good enough to import to your-journal, perhaps with some manual fixups to follow, you would do the-actual import:--$ hledger import bank.csv---File: hledger.info,  Node: Overlap detection,  Next: First import,  Prev: Import preview,  Up: import--26.2.2 Overlap detection---------------------------Reading CSV files is built in to hledger, and not specific to 'import';-so you could also import by doing 'hledger -f bank.csv print->>$LEDGER_FILE'.--   But 'import' is easier and provides some advantages.  The main one is-that it avoids re-importing transactions it has seen on previous runs.-This means you don't have to worry about overlapping data in successive-downloads of your bank CSV; just download and 'import' as often as you-like, and only the new transactions will be imported each time.--   We don't call this "deduplication", as it's generally not possible to-reliably detect duplicates in bank CSV. Instead, 'import' remembers the-latest date processed previously in each CSV file (saving it in a hidden-file), and skips any records prior to that date.  This works well for-most real-world CSV, where:--  1. the data file name is stable (does not change) across imports-  2. the item dates are stable across imports-  3. the order of same-date items is stable across imports-  4. the newest items have the newest dates--   (Occasional violations of 2-4 are often harmless; you can reduce the-chance of disruption by downloading and importing more often.)--   Overlap detection is automatic, and shouldn't require much attention-from you, except perhaps at first import (see below).  But here's how it-works:--   * For each 'FILE' being imported from:--       1. hledger reads a file named '.latest.FILE' file in the same-          directory, if any.  This file contains the latest record date-          previously imported from FILE, in YYYY-MM-DD format.  If-          multiple records with that date were imported, the date is-          repeated on N lines.--       2. hledger reads records from FILE. If a latest date was found in-          step 1, any records before that date, and the first N records-          on that date, are skipped.--   * After a successful import from all FILEs, without error and without-     '--dry-run', hledger updates each FILE's '.latest.FILE' for next-     time.--   If this goes wrong, it's relatively easy to repair:--   * You'll notice it before import when you preview with 'import-     --dry-run'.-   * Or after import when you try to reconcile your hledger account-     balances with your bank.-   * 'hledger print -f FILE.csv' will show all recently downloaded-     transactions.  Compare these with your journal.  Copy/paste if-     needed.-   * Update your conversion rules and print again, if needed.-   * You can manually update or remove the .latest file, or use 'import-     --catchup FILE'.-   * Download and import more often, eg twice a week, at least while you-     are learning.  It's easier to review and troubleshoot when there-     are fewer transactions.---File: hledger.info,  Node: First import,  Next: Importing balance assignments,  Prev: Overlap detection,  Up: import--26.2.3 First import----------------------The first time you import from a file, when no corresponding .latest-file has been created yet, all of the records will be imported.--   But perhaps you have been entering the data manually, so you know-that all of these transactions are already recorded in the journal.  In-this case you can run 'hledger import --catchup' once.  This will create-a .latest file containing the latest CSV record date, so that none of-those records will be re-imported.--   Or, if you know that some but not all of the transactions are in the-journal, you can create the .latest file yourself.  Eg, let's say you-previously recorded foobank transactions up to 2024-10-31 in the-journal.  Then in the directory where you'll be saving 'foobank.csv',-you would create a '.latest.foobank.csv' file containing--2024-10-31--   Or if you had three foobank transactions recorded with that date, you-would repeat the date that many times:--2024-10-31-2024-10-31-2024-10-31--   Then 'hledger import foobank.csv [--dry-run]' will import only the-newer records.---File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: First import,  Up: import--26.2.4 Importing balance assignments---------------------------------------Journal entries added by import will have all posting amounts made-explicit (like 'print -x').--   This means that any balance assignments in the imported entries would-need to be evaluated.  But this generally isn't possible, as the main-file's account balances are not visible during import.  So try to avoid-generating balance assignments with your CSV rules, or importing from a-journal that contains balance assignments.  (Balance assignments are-best avoided anyway.)--   But if you must use them, eg because your CSV includes only balances:-you can import with 'print', which leaves implicit amounts implicit.-('print' can also do overlap detection like import, with the '--new'-flag):--$ hledger print --new -f bank.csv >> $LEDGER_FILE--   (If you think 'import' should preserve implicit balances, please test-that and send a pull request.)---File: hledger.info,  Node: Import and commodity styles,  Next: Import special cases,  Prev: Importing balance assignments,  Up: import--26.2.5 Import and commodity styles-------------------------------------Amounts in entries added by import will be formatted according to the-journal's canonical commodity styles, as declared by 'commodity'-directives or inferred from the journal's amounts.--   Related: CSV > Amount decimal places.---File: hledger.info,  Node: Import special cases,  Prev: Import and commodity styles,  Up: import--26.2.6 Import special cases------------------------------If you have a download whose file name varies, you could rename it to a-fixed name after each download.  Or you could use a CSV 'source' rule-with a suitable glob pattern, and import from the .rules file instead of-the data file.--   Here's a situation where you would need to run 'import' with care:-say you download 'bank.csv', but forget to import it or delete it.  And-next month you download it again.  This time your web browser may save-it as 'bank (2).csv'.  So now each of these may have data not included-in the other.  And a 'source' rule with a glob pattern would match only-the most recent file.  So in this case you should import from each one-in turn, in the correct order, taking care to use the same filename each-time:--$ hledger import bank.csv-$ mv 'bank (2).csv' bank.csv-$ hledger import bank.csv--   Here are two kinds of "deduplication" which 'import' does not handle-(and generally should not, since these can happen legitimately in-financial data):--   * Two or more of the new CSV records are identical, and generate-     identical new journal entries.-   * A new CSV record generates a journal entry identical to one(s)-     already in the journal.---File: hledger.info,  Node: Basic report commands,  Next: Standard report commands,  Prev: Data entry commands,  Up: Top--27 Basic report commands-************************--* Menu:--* accounts::-* codes::-* commodities::-* descriptions::-* files::-* notes::-* payees::-* prices::-* stats::-* tags::---File: hledger.info,  Node: accounts,  Next: codes,  Up: Basic report commands--27.1 accounts-=============--List account names.--Flags:-  -u --used                 show only accounts used by transactions-  -d --declared             show only accounts declared by account directive-     --unused               show only accounts declared but not used-     --undeclared           show only accounts used but not declared-     --types                also show account types when known-     --positions            also show where accounts were declared-     --directives           show as account directives, for use in journals-     --find                 find the first account matched by the first-                            argument (a case-insensitive infix regexp or-                            account name)-  -l --flat                 show accounts as a flat list (default)-  -t --tree                 show accounts as a tree-     --drop=N               flat mode: omit N leading account name parts--   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: codes,  Next: commodities,  Prev: accounts,  Up: Basic report commands--27.2 codes-==========--List the codes seen in transactions, in the order parsed.--Flags:-no command-specific flags--   This command prints the value of each transaction's code field, in-the order transactions were parsed.  The transaction code is an optional-value written in parentheses between the date and description, often-used to store a cheque number, order number or similar.--   Transactions aren't required to have a code, and missing or empty-codes will not be shown by default.  With the '-E'/'--empty' flag, they-will be printed as blank lines.--   You can add a query to select a subset of transactions.--   Examples:--2022/1/1 (123) Supermarket   - Food       $5.00- Checking    --2022/1/2 (124) Post Office- Postage    $8.32- Checking--2022/1/3 Supermarket- Food      $11.23- Checking --2022/1/4 (126) Post Office- Postage    $3.21- Checking--$ hledger codes-123-124-126--$ hledger codes -E-123-124--126---File: hledger.info,  Node: commodities,  Next: descriptions,  Prev: codes,  Up: Basic report commands--27.3 commodities-================--List all commodity/currency symbols used or declared in the journal.--Flags:-no command-specific flags---File: hledger.info,  Node: descriptions,  Next: files,  Prev: commodities,  Up: Basic report commands--27.4 descriptions-=================--List the unique descriptions that appear in transactions.--Flags:-no command-specific flags--   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: files,  Next: notes,  Prev: descriptions,  Up: Basic report commands--27.5 files-==========--List all files included in the journal.  With a REGEX argument, only-file names matching the regular expression (case sensitive) are shown.--Flags:-no command-specific flags---File: hledger.info,  Node: notes,  Next: payees,  Prev: files,  Up: Basic report commands--27.6 notes-==========--List the unique notes that appear in transactions.--Flags:-no command-specific flags--   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: Basic report commands--27.7 payees-===========--List the unique payee/payer names that appear in transactions.--Flags:-     --declared             show payees declared with payee directives-     --used                 show payees referenced by 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: stats,  Prev: payees,  Up: Basic report commands--27.8 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.--Flags:-     --show-reverse         also show the 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: stats,  Next: tags,  Prev: prices,  Up: Basic report commands--27.9 stats-==========--Show journal and performance statistics.--Flags:-  -v --verbose              show more detailed output-  -o --output-file=FILE     write output to FILE.--   The stats command shows summary information for the whole journal, or-a matched part of it.  With a reporting interval, it shows a report for-each report period.--   The default output is fairly impersonal, though it reveals the main-file name.  With '-v/--verbose', more details are shown, like file-paths, included files, and commodity names.--   It also shows some run time statistics:--   * elapsed time-   * throughput: the number of transactions processed per second-   * live: the peak memory in use by the program to do its work-   * alloc: the peak memory allocation from the OS as seen by GHC.-     Measuring this externally, eg with GNU time, is more accurate;-     usually that will be a larger number; sometimes (with swapping?)-     smaller.--   The 'stats' command's run time is similar to that of a balance-report.--   Example:--$ hledger stats -f examples/1ktxns-1kaccts.journal -Main file           : .../1ktxns-1kaccts.journal-Included files      : 0-Txns span           : 2000-01-01 to 2002-09-27 (1000 days)-Last txn            : 2002-09-26 (7827 days ago)-Txns                : 1000 (1.0 per day)-Txns last 30 days   : 0 (0.0 per day)-Txns last 7 days    : 0 (0.0 per day)-Payees/descriptions : 1000-Accounts            : 1000 (depth 10)-Commodities         : 26-Market prices       : 1000-Runtime stats       : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc--   This command supports the -o/-output-file option (but not--O/-output-format).---File: hledger.info,  Node: tags,  Prev: stats,  Up: Basic report commands--27.10 tags-==========--List the tags used in the journal, or their values.--Flags:-     --values               list tag values instead of tag names-     --parsed               show tags/values in the order they were parsed,-                            including duplicates--   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: Standard report commands,  Next: Advanced report commands,  Prev: Basic report commands,  Up: Top--28 Standard report commands-***************************--* Menu:--* print::-* aregister::-* register::-* balancesheet::-* balancesheetequity::-* cashflow::-* incomestatement::---File: hledger.info,  Node: print,  Next: aregister,  Up: Standard report commands--28.1 print-==========--Show full journal entries, representing transactions.--Flags:-  -x --explicit             show all amounts explicitly-     --show-costs           show transaction prices even with conversion-                            postings-     --round=TYPE           how much rounding or padding should be done when-                            displaying amounts ?-                            none - show original decimal digits,-                                   as in journal-                            soft - just add or remove decimal zeros-                                   to match precision (default)-                            hard - round posting amounts to precision-                                   (can unbalance transactions)-                            all  - also round cost amounts to precision-                                   (can unbalance transactions)-     --new                  show only newer-dated transactions added in each-                            file since last run-  -m --match=DESC           fuzzy search for one recent transaction with-                            description closest to DESC-     --base-url=URLPREFIX   in html output, generate links to hledger-web,-                            with this prefix. (Usually the base url shown by-                            hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, beancount, csv, tsv, html, fods, json, sql.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   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--28.1.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--28.1.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' (_Added in 1.32_) 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--28.1.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--28.1.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--28.1.5 print output format-----------------------------This command also supports the output destination and output format-options The output formats supported are 'txt', 'beancount' (_Added in-1.32_), 'csv', 'tsv' (_Added in 1.32_), 'json' and 'sql'.--   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: aregister,  Next: register,  Prev: print,  Up: Standard report commands--28.2 aregister-==============--(areg)--   Show the transactions and running balances in one account, with each-transaction on one line.--Flags:-     --txn-dates            filter strictly by transaction date, not posting-                            date. Warning: this can show a wrong running-                            balance.-     --no-elide             don't show only 2 commodities per amount-     --cumulative           show running total from report start date-  -H --historical           show historical running total/balance (includes-                            postings before report start date) (default)-                            -     --invert               display all amounts with reversed sign-     --heading=YN           show heading row above table: yes (default) or no-  -w --width=N              set output width (default: terminal width or-                            $COLUMNS). -wN,M sets description width as well.-     --align-all            guarantee alignment across all lines (slower)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, html, csv, tsv, json.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   '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 included in the running balance ('--historical' mode is the-default).  You can suppress this behaviour using the '--cumulative'-option.--   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.--   By default, 'aregister' shows a heading above the data.  However,-when reporting in a language different from English, it is easier to-omit this heading and prepend your own one.  For this purpose, use the-'--heading=no' option.--   This command also supports the output destination and output format-options.  The output formats supported are 'txt', 'csv', 'tsv' (_Added-in 1.32_), 'html', 'fods' (_Added in 1.41_) and 'json'.--* Menu:--* aregister and posting dates::---File: hledger.info,  Node: aregister and posting dates,  Up: aregister--28.2.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: register,  Next: balancesheet,  Prev: aregister,  Up: Standard report commands--28.3 register-=============--(reg)--   Show postings and their running total.--Flags:-     --cumulative           show running total from report start date-                            (default)-  -H --historical           show historical running total/balance (includes-                            postings before report start date)-  -A --average              show running average of posting amounts instead-                            of total (implies --empty)-  -m --match=DESC           fuzzy search for one recent posting with-                            description closest to DESC-  -r --related              show postings' siblings instead-     --invert               display all amounts with reversed sign-     --sort=FIELDS          sort by: date, desc, account, amount, absamount,-                            or a comma-separated combination of these. For a-                            descending sort, prefix with -. (Default: date)-  -w --width=N              set output width (default: terminal width or-                            $COLUMNS). -wN,M sets description width as well.-     --align-all            guarantee alignment across all lines (slower)-     --base-url=URLPREFIX   in html output, generate links to hledger-web,-                            with this prefix. (Usually the base url shown by-                            hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, csv, tsv, html, fods, json.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   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:--   The '--sort=FIELDS' flag sorts by the fields given, which can be any-of 'account', 'amount', 'absamount', 'date', or 'desc'/'description',-optionally separated by commas.  For example, '--sort account,amount'-will group all transactions in each account, sorted by transaction-amount.  Each field can be negated by a preceding '-', so '--sort--amount' will show transactions ordered from smallest amount to largest-amount.--$ 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--28.3.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' (_Added in-1.32_), and 'json'.---File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: register,  Up: Standard report commands--28.4 balancesheet-=================--(bs)--   Show the end balances in asset and liability accounts.  Amounts are-shown with normal positive sign, as in conventional financial-statements.--Flags:-     --sum                  show sum of posting amounts (default)-     --valuechange          show total change of period-end historical-                            balance value (caused by deposits, withdrawals,-                            market price fluctuations)-     --gain                 show unrealised capital gain/loss (historical-                            balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions-     --count                show the count of postings-     --change               accumulate amounts from column start to column-                            end (in multicolumn reports)-     --cumulative           accumulate amounts from report start (specified-                            by e.g. -b/--begin) to column end-  -H --historical           accumulate amounts from journal start to column-                            end (includes postings before report start date)-                            (default)-  -l --flat                 show accounts as a flat list (default). Amounts-                            exclude subaccount amounts, except where the-                            account is depth-clipped.-  -t --tree                 show accounts as a tree. Amounts include-                            subaccount amounts.-     --drop=N               flat mode: omit N leading account name parts-     --declared             include non-parent declared accounts (best used-                            with -E)-  -A --average              show a row average column (in multicolumn-                            reports)-  -T --row-total            show a row total column (in multicolumn reports)-     --summary-only         display only row summaries (e.g. row total,-                            average) (in multicolumn reports)-  -N --no-total             omit the final total row-     --no-elide             don't squash boring parent accounts (in tree-                            mode)-     --format=FORMATSTR     use this custom line format (in simple reports)-  -S --sort-amount          sort by amount instead of account code/name-  -% --percent              express values in percentage of each column's-                            total-     --layout=ARG           how to show multi-commodity amounts:-                            'wide[,WIDTH]': all commodities on one line-                            'tall'        : each commodity on a new line-                            'bare'        : bare numbers, symbols in a column-     --base-url=URLPREFIX   in html output, generate hyperlinks to-                            hledger-web, with this prefix. (Usually the base-                            url shown by hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, html, csv, tsv, json.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   This command displays a balance sheet, showing historical ending-balances of asset and liability accounts.  (To see equity as well, use-the balancesheetequity command.)--   Accounts declared with the 'Asset', 'Cash' or 'Liability' type are-shown (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 2008-12-31--                    || 2008-12-31 -====================++============- Assets             ||            ---------------------++------------- assets:bank:saving ||         $1 - assets:cash        ||        $-2 ---------------------++-------------                    ||        $-1 -====================++============- Liabilities        ||            ---------------------++------------- liabilities:debts  ||        $-1 ---------------------++-------------                    ||        $-1 -====================++============- Net:               ||          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' (_Added in-1.32_), 'html', and 'json'.---File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: Standard report commands--28.5 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.--Flags:-     --sum                  show sum of posting amounts (default)-     --valuechange          show total change of period-end historical-                            balance value (caused by deposits, withdrawals,-                            market price fluctuations)-     --gain                 show unrealised capital gain/loss (historical-                            balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions-     --count                show the count of postings-     --change               accumulate amounts from column start to column-                            end (in multicolumn reports)-     --cumulative           accumulate amounts from report start (specified-                            by e.g. -b/--begin) to column end-  -H --historical           accumulate amounts from journal start to column-                            end (includes postings before report start date)-                            (default)-  -l --flat                 show accounts as a flat list (default). Amounts-                            exclude subaccount amounts, except where the-                            account is depth-clipped.-  -t --tree                 show accounts as a tree. Amounts include-                            subaccount amounts.-     --drop=N               flat mode: omit N leading account name parts-     --declared             include non-parent declared accounts (best used-                            with -E)-  -A --average              show a row average column (in multicolumn-                            reports)-  -T --row-total            show a row total column (in multicolumn reports)-     --summary-only         display only row summaries (e.g. row total,-                            average) (in multicolumn reports)-  -N --no-total             omit the final total row-     --no-elide             don't squash boring parent accounts (in tree-                            mode)-     --format=FORMATSTR     use this custom line format (in simple reports)-  -S --sort-amount          sort by amount instead of account code/name-  -% --percent              express values in percentage of each column's-                            total-     --layout=ARG           how to show multi-commodity amounts:-                            'wide[,WIDTH]': all commodities on one line-                            'tall'        : each commodity on a new line-                            'bare'        : bare numbers, symbols in a column-     --base-url=URLPREFIX   in html output, generate hyperlinks to-                            hledger-web, with this prefix. (Usually the base-                            url shown by hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, html, csv, tsv, json.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   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 2008-12-31--                    || 2008-12-31 -====================++============- Assets             ||            ---------------------++------------- assets:bank:saving ||         $1 - assets:cash        ||        $-2 ---------------------++-------------                    ||        $-1 -====================++============- Liabilities        ||            ---------------------++------------- liabilities:debts  ||        $-1 ---------------------++-------------                    ||        $-1 -====================++============- Equity             ||            ---------------------++---------------------------------++-------------                    ||          0 -====================++============- Net:               ||          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 report is the easiest way to see if the accounting equation-(A+L+E = 0) is satisfied (after you have done a 'close --retain' to-merge revenues and expenses with equity, and perhaps added-'--infer-equity' to balance your commodity conversions).--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'tsv', 'html',-and 'json'.---File: hledger.info,  Node: cashflow,  Next: incomestatement,  Prev: balancesheetequity,  Up: Standard report commands--28.6 cashflow-=============--(cf)--   This command displays a (simple) 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.--Flags:-     --sum                  show sum of posting amounts (default)-     --valuechange          show total change of period-end historical-                            balance value (caused by deposits, withdrawals,-                            market price fluctuations)-     --gain                 show unrealised capital gain/loss (historical-                            balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions-     --count                show the count of postings-     --change               accumulate amounts from column start to column-                            end (in multicolumn reports) (default)-     --cumulative           accumulate amounts from report start (specified-                            by e.g. -b/--begin) to column end-  -H --historical           accumulate amounts from journal start to column-                            end (includes postings before report start date)-  -l --flat                 show accounts as a flat list (default). Amounts-                            exclude subaccount amounts, except where the-                            account is depth-clipped.-  -t --tree                 show accounts as a tree. Amounts include-                            subaccount amounts.-     --drop=N               flat mode: omit N leading account name parts-     --declared             include non-parent declared accounts (best used-                            with -E)-  -A --average              show a row average column (in multicolumn-                            reports)-  -T --row-total            show a row total column (in multicolumn reports)-     --summary-only         display only row summaries (e.g. row total,-                            average) (in multicolumn reports)-  -N --no-total             omit the final total row-     --no-elide             don't squash boring parent accounts (in tree-                            mode)-     --format=FORMATSTR     use this custom line format (in simple reports)-  -S --sort-amount          sort by amount instead of account code/name-  -% --percent              express values in percentage of each column's-                            total-     --layout=ARG           how to show multi-commodity amounts:-                            'wide[,WIDTH]': all commodities on one line-                            'tall'        : each commodity on a new line-                            'bare'        : bare numbers, symbols in a column-     --base-url=URLPREFIX   in html output, generate hyperlinks to-                            hledger-web, with this prefix. (Usually the base-                            url shown by hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, html, csv, tsv, json.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   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 2008--                    || 2008 -====================++======- Cash flows         ||      ---------------------++------- assets:bank:saving ||   $1 - assets:cash        ||  $-2 ---------------------++-------                    ||  $-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' (_Added in-1.32_), 'html', and 'json'.---File: hledger.info,  Node: incomestatement,  Prev: cashflow,  Up: Standard report commands--28.7 incomestatement-====================--(is)--   Show revenue inflows and expense outflows during the report period.-Amounts are shown with normal positive sign, as in conventional-financial statements.--Flags:-     --sum                  show sum of posting amounts (default)-     --valuechange          show total change of period-end historical-                            balance value (caused by deposits, withdrawals,-                            market price fluctuations)-     --gain                 show unrealised capital gain/loss (historical-                            balance value minus cost basis)-     --budget               show sum of posting amounts compared to budget-                            goals defined by periodic transactions-     --count                show the count of postings-     --change               accumulate amounts from column start to column-                            end (in multicolumn reports) (default)-     --cumulative           accumulate amounts from report start (specified-                            by e.g. -b/--begin) to column end-  -H --historical           accumulate amounts from journal start to column-                            end (includes postings before report start date)-  -l --flat                 show accounts as a flat list (default). Amounts-                            exclude subaccount amounts, except where the-                            account is depth-clipped.-  -t --tree                 show accounts as a tree. Amounts include-                            subaccount amounts.-     --drop=N               flat mode: omit N leading account name parts-     --declared             include non-parent declared accounts (best used-                            with -E)-  -A --average              show a row average column (in multicolumn-                            reports)-  -T --row-total            show a row total column (in multicolumn reports)-     --summary-only         display only row summaries (e.g. row total,-                            average) (in multicolumn reports)-  -N --no-total             omit the final total row-     --no-elide             don't squash boring parent accounts (in tree-                            mode)-     --format=FORMATSTR     use this custom line format (in simple reports)-  -S --sort-amount          sort by amount instead of account code/name-  -% --percent              express values in percentage of each column's-                            total-     --layout=ARG           how to show multi-commodity amounts:-                            'wide[,WIDTH]': all commodities on one line-                            'tall'        : each commodity on a new line-                            'bare'        : bare numbers, symbols in a column-     --base-url=URLPREFIX   in html output, generate hyperlinks to-                            hledger-web, with this prefix. (Usually the base-                            url shown by hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, html, csv, tsv, json.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   This command displays an income statement, showing revenues and-expenses during one or more periods.--   It 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 2008--                   || 2008 -===================++======- Revenues          ||      --------------------++------- income:gifts      ||   $1 - income:salary     ||   $1 --------------------++-------                   ||   $2 -===================++======- Expenses          ||      --------------------++------- expenses:food     ||   $1 - expenses:supplies ||   $1 --------------------++-------                   ||   $2 -===================++======- Net:              ||    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' (_Added in-1.32_), 'html', and 'json'.---File: hledger.info,  Node: Advanced report commands,  Next: Chart commands,  Prev: Standard report commands,  Up: Top--29 Advanced report commands-***************************--* Menu:--* balance::-* roi::---File: hledger.info,  Node: balance,  Next: roi,  Up: Advanced report commands--29.1 balance-============--(bal)--   A flexible, general purpose "summing" report that shows accounts with-some kind of numeric data.  This can be balance changes per period, end-balances, budget performance, unrealised capital gains, etc.--Flags:-     --sum                  show sum of posting amounts (default)-     --valuechange          show total change of value of period-end-                            historical balances (caused by deposits,-                            withdrawals, market price fluctuations)-     --gain                 show unrealised capital gain/loss (historical-                            balance value minus cost basis)-     --budget[=DESCPAT]     show sum of posting amounts together with budget-                            goals defined by periodic-                            transactions. With a DESCPAT argument (must be-                            separated by = not space),-                            use only periodic transactions with matching-                            description-                            (case insensitive substring match).-     --count                show the count of postings-     --change               accumulate amounts from column start to column-                            end (in multicolumn reports, default)-     --cumulative           accumulate amounts from report start (specified-                            by e.g. -b/--begin) to column end-  -H --historical           accumulate amounts from journal start to column-                            end (includes postings before report start date)-  -l --flat                 show accounts as a flat list (default). Amounts-                            exclude subaccount amounts, except where the-                            account is depth-clipped.-  -t --tree                 show accounts as a tree. Amounts include-                            subaccount amounts.-     --drop=N               omit N leading account name parts (in flat mode)-     --declared             include non-parent declared accounts (best used-                            with -E)-  -A --average              show a row average column (in multicolumn-                            reports)-  -T --row-total            show a row total column (in multicolumn reports)-     --summary-only         display only row summaries (e.g. row total,-                            average) (in multicolumn reports)-  -N --no-total             omit the final total row-     --no-elide             don't squash boring parent accounts (in tree-                            mode)-     --format=FORMATSTR     use this custom line format (in simple reports)-  -S --sort-amount          sort by amount instead of account code/name (in-                            flat mode). With multiple columns, sorts by the row-                            total, or by row average if that is displayed.-  -% --percent              express values in percentage of each column's-                            total-  -r --related              show the other accounts transacted with, instead-     --invert               display all amounts with reversed sign-     --transpose            switch rows and columns (use vertical time axis)-     --layout=ARG           how to lay out multi-commodity amounts and the-                            overall table:-                            'wide[,WIDTH]': commodities on one line-                            'tall'        : commodities on separate lines-                            'bare'        : commodity symbols in one column-                            'tidy'        : every attribute in its own column-     --base-url=URLPREFIX   in html output, generate links to hledger-web,-                            with this prefix. (Usually the base url shown by-                            hledger-web; can also be relative.)-  -O --output-format=FMT    select the output format. Supported formats:-                            txt, html, csv, tsv, json, fods.-  -o --output-file=FILE     write output to FILE. A file extension matching-                            one of the above formats selects that format.--   '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::-* Balance report output::-* Some useful balance reports::---File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance--29.1.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 balance changes from sibling postings ('--related'/'-r')-   * 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' (_Added in 1.32_),-'json', and (multi-period reports only:) 'html', 'fods' (_Added in-1.40_).  In 'txt' output in a colour-supporting terminal, negative-amounts are shown in red.---File: hledger.info,  Node: Simple balance report,  Next: Balance report line format,  Prev: balance features,  Up: balance--29.1.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--29.1.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--29.1.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--29.1.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--29.1.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--29.1.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--29.1.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--29.1.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--29.1.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--29.1.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.-   * 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.-   * The '--summary-only' flag ('--summary' also works) hides all but-     the Total and Average columns (those should be enabled with-     '--row-total' and '-A/--average').--   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'-   * Filter to a single currency with 'cur:'-   * Convert to a single currency with '-V [--infer-market-price]'-   * Use a more compact layout like '--layout=bare'-   * 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--29.1.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--29.1.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--29.1.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--29.1.13.2 Accumulation type-...........................--How amounts should accumulate across a report's subperiods/columns.-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, cashflow,-     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*)---File: hledger.info,  Node: Valuation type,  Next: Combining balance report types,  Prev: Accumulation type,  Up: Balance report types--29.1.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--29.1.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--29.1.14 Budget report------------------------The '--budget' report type is like a regular balance report, but with-two main differences:--   * Budget goals and performance percentages are also shown, in-     brackets-   * Accounts which don't have budget goals are hidden by default.--   This is useful for comparing planned and actual income, expenses,-time usage, etc.--   Periodic transaction rules are used to define budget goals.  For-example, here's a periodic rule defining monthly goals for bus travel-and food expenses:--;; Budget-~ monthly-  (expenses:bus)              $30-  (expenses:food)            $400--   After recording some actual expenses,--;; Two months worth of expenses-2017-11-01-  income                   $-1950-  expenses:bus                $35-  expenses:food:groceries    $310-  expenses:food:dining        $42-  expenses:movies             $38-  assets:bank:checking--2017-12-01-  income                   $-2100-  expenses:bus                $53-  expenses:food:groceries    $380-  expenses:food:dining        $32-  expenses:gifts             $100-  assets:bank:checking--   we can see a budget report like this:--$ hledger bal -M --budget-Budget performance in 2017-11-01..2017-12-31:--               ||                  Nov                   Dec -===============++============================================- <unbudgeted>  || $-425                 $-565                - expenses      ||  $425 [ 99% of $430]   $565 [131% of $430] - expenses:bus  ||   $35 [117% of  $30]    $53 [177% of  $30] - expenses:food ||  $352 [ 88% of $400]   $412 [103% of $400] ----------------++---------------------------------------------               ||     0 [  0% of $430]      0 [  0% of $430] --   This is "goal-based budgeting"; you define goals for accounts and-periods, often recurring, and hledger shows performance relative to the-goals.  This contrasts with "envelope budgeting", which is more detailed-and strict - useful when cash is tight, but also quite a bit more work.-https://plaintextaccounting.org/Budgeting has more on this topic.--* Menu:--* Using the budget report::-* Budget date surprises::-* Selecting budget goals::-* Budgeting vs forecasting::---File: hledger.info,  Node: Using the budget report,  Next: Budget date surprises,  Up: Budget report--29.1.14.1 Using the budget report-.................................--Historically this report has been confusing and fragile.  hledger's-version should be relatively robust and intuitive, but you may still-find surprises.  Here are more notes to help with learning and-troubleshooting.--   * In the above example, 'expenses:bus' and 'expenses:food' are shown-     because they have budget goals during the report period.--   * Their parent 'expenses' is also shown, with budget goals aggregated-     from the children.--   * The subaccounts 'expenses:food:groceries' and-     'expenses:food:dining' are not shown since they have no budget goal-     of their own, but they contribute to 'expenses:food''s actual-     amount.--   * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also-     not shown, but they contribute to 'expenses''s actual amount.--   * The other unbudgeted accounts 'income' and 'assets:bank:checking'-     are grouped as '<unbudgeted>'.--   * '--depth' or 'depth:' can be used to limit report depth in the-     usual way (but will not reveal unbudgeted subaccounts).--   * Amounts are always inclusive of subaccounts (even in '-l/--list'-     mode).--   * Numbers displayed in a -budget report will not always agree with-     the totals, because of hidden unbudgeted accounts; this is normal.-     '-E/--empty' can be used to reveal the hidden accounts.--   * In the periodic rules used for setting budget goals, unbalanced-     postings are convenient.--   * You can filter budget reports with the usual queries, eg to focus-     on particular accounts.  It's common to restrict them to just-     expenses.  (The '<unbudgeted>' account is occasionally hard to-     exclude; this is because of date surprises, discussed below.)--   * When you have multiple currencies, you may want to convert them to-     one ('-X COMM --infer-market-prices') and/or show just one at a-     time ('cur:COMM').  If you do need to show multiple currencies at-     once, '--layout bare' can be helpful.--   * You can "roll over" amounts (actual and budgeted) to the next-     period with '--cumulative'.--   See also: https://hledger.org/budgeting.html.---File: hledger.info,  Node: Budget date surprises,  Next: Selecting budget goals,  Prev: Using the budget report,  Up: Budget report--29.1.14.2 Budget date surprises-...............................--With small data, or when starting out, some of the generated budget goal-transaction dates might fall outside the report periods.  Eg with the-following journal and report, the first period appears to have no-'expenses:food' budget.  (Also the '<unbudgeted>' account should be-excluded by the 'expenses' query, but isn't.):--~ monthly in 2020-  (expenses:food)  $500--2020-01-15-  expenses:food    $400-  assets:checking--$ hledger bal --budget expenses-Budget performance in 2020-01-15:--               ||         2020-01-15 -===============++====================- <unbudgeted>  || $400               - expenses:food ||    0 [ 0% of $500] ----------------++---------------------               || $400 [80% of $500] --   In this case, the budget goal transactions are generated on first-days of of month (this can be seen with 'hledger print --forecast-tag:generated expenses').  Whereas the report period defaults to just-the 15th day of january (this can be seen from the report table's column-headings).--   To fix this kind of thing, be more explicit about the report period-(and/or the periodic rules' dates).  In this case, adding '-b 2020' does-the trick.---File: hledger.info,  Node: Selecting budget goals,  Next: Budgeting vs forecasting,  Prev: Budget date surprises,  Up: Budget report--29.1.14.3 Selecting budget goals-................................--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 between period-expression and description), and then select from multiple budgets-defined in your journal.---File: hledger.info,  Node: Budgeting vs forecasting,  Prev: Selecting budget goals,  Up: Budget report--29.1.14.4 Budgeting vs forecasting-..................................--'--forecast' and '--budget' both use the periodic transaction rules in-the journal to generate temporary transactions for reporting purposes.-However they are separate features - though you can use both at the same-time if you want.  Here are some differences between them:---forecast                                -budget----------------------------------------------------------------------------is a general option; it enables          is a balance command option;-forecasting with all reports             it selects the balance-                                         report's budget mode-generates visible transactions which     generates invisible-appear in reports                        transactions which produce-                                         goal amounts-generates forecast transactions from     generates budget goal-after the last regular transaction, to   transactions throughout the-the end of the report period; or with    report period, optionally-an argument '--forecast=PERIODEXPR'      restricted by periods-generates them throughout the            specified in the periodic-specified period, both optionally        transaction rules-restricted by periods specified in the-periodic transaction rules-uses all periodic rules                  uses all periodic rules; or-                                         with an argument-                                         '--budget=DESCPAT' uses just-                                         the rules matched by DESCPAT---File: hledger.info,  Node: Balance report layout,  Next: Balance report output,  Prev: Budget report,  Up: balance--29.1.15 Balance report layout--------------------------------The '--layout' option affects how 'balance' and the other balance-like-commands show multi-commodity amounts and commodity symbols.  It can-improve readability, for humans and/or machines (other software).  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.  (This one is currently supported only-     by the 'balance' command.)--   Here are the '--layout' modes supported by each output format 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:--* Menu:--* Wide layout::-* Tall layout::-* Bare layout::-* Tidy layout::---File: hledger.info,  Node: Wide layout,  Next: Tall layout,  Up: Balance report layout--29.1.15.1 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 --   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.. ---File: hledger.info,  Node: Tall layout,  Next: Bare layout,  Prev: Wide layout,  Up: Balance report layout--29.1.15.2 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 ---File: hledger.info,  Node: Bare layout,  Next: Tidy layout,  Prev: Tall layout,  Up: Balance report layout--29.1.15.3 Bare layout-.....................--Commodity symbols are kept in one column, each commodity has its own-row, amounts are bare numbers, 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"--   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).---File: hledger.info,  Node: Tidy layout,  Prev: Bare layout,  Up: Balance report layout--29.1.15.4 Tidy layout-.....................--This produces normalised "tidy data" (see-https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)-where every variable has its own column and each row represents a single-data point.  This is the easiest kind of data for other software to-consume:--$ 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: Balance report output,  Next: Some useful balance reports,  Prev: Balance report layout,  Up: balance--29.1.16 Balance report output--------------------------------As noted in Output format, if you choose HTML output (by using '-O html'-or '-o somefile.html'), it will use the UTF-8 text encoding, And you can-create a 'hledger.css' file in the same directory to customise the-report's appearance.--   The HTML and FODS output formats can generate hyperlinks to a-'hledger-web' register view for each account and period.  E.g.  if your-'hledger-web' server is reachable at 'http://localhost:5000' then you-might run the 'balance' command with the extra option-'--base-url=http://localhost:5000'.  You can also produce relative-links, like '--base-url="some/path"' or '--base-url=""'.)--   The balance reports' HTML output currently does not indent tree mode-reports properly (#1846).  So in HTML balance reports, use list mode for-now (it is the default).---File: hledger.info,  Node: Some useful balance reports,  Prev: Balance report output,  Up: balance--29.1.17 Some 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: roi,  Prev: balance,  Up: Advanced report commands--29.2 roi-========--Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on-your investments.--Flags:-     --cashflow                 show all amounts that were used to compute-                                returns-     --investment=QUERY         query to select your investment transactions-     --profit-loss=QUERY --pnl  query to select profit-and-loss or-                                appreciation/valuation transactions--   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--29.2.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--29.2.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--29.2.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: Chart commands,  Next: Data generation commands,  Prev: Advanced report commands,  Up: Top--30 Chart commands-*****************--* Menu:--* activity::---File: hledger.info,  Node: activity,  Up: Chart commands--30.1 activity-=============--Show an ascii barchart of posting counts per interval.--Flags:-no command-specific flags--   The activity command displays an ascii histogram showing transaction-counts by day, week, month or other reporting interval (by day is the-default).  With query arguments, it counts only matched transactions.--   Examples:--$ hledger activity --quarterly-2008-01-01 **-2008-04-01 *******-2008-07-01 -2008-10-01 **---File: hledger.info,  Node: Data generation commands,  Next: Maintenance commands,  Prev: Chart commands,  Up: Top--31 Data generation commands-***************************--* Menu:--* close::-* rewrite::---File: hledger.info,  Node: close,  Next: rewrite,  Up: Data generation commands--31.1 close-==========--(equity)--   'close' generates several kinds of "closing" and/or "opening"-transactions, useful in certain situations, including migrating balances-to a new journal file, retaining earnings into equity, consolidating-balances, or viewing lots.  Like 'print', it prints valid journal-entries.  You can append or copy these to your journal file(s) when you-are happy with how they look.--Flags:-     --migrate[=NEW]        show closing and opening transactions, for Asset-                            and Liability accounts by default, tagged for easy-                            matching. The tag's default value can be overridden-                            by providing NEW.-     --close[=NEW]          (default) show a closing transaction-     --open[=NEW]           show an opening transaction-     --assign[=NEW]         show opening balance assignments-     --assert[=NEW]         show closing balance assertions-     --retain[=NEW]         show a retain earnings transaction, for Revenue-                            and Expense accounts by default-  -x --explicit             show all amounts explicitly-     --show-costs           show amounts with different costs separately-     --interleaved          show source and destination postings together-     --assertion-type=TYPE  =, ==, =* or ==*-     --close-desc=DESC      set closing transaction's description-     --close-acct=ACCT      set closing transaction's destination account-     --open-desc=DESC       set opening transaction's description-     --open-acct=ACCT       set opening transaction's source account-     --round=TYPE           how much rounding or padding should be done when-                            displaying amounts ?-                            none - show original decimal digits,-                                   as in journal-                            soft - just add or remove decimal zeros-                                   to match precision (default)-                            hard - round posting amounts to precision-                                   (can unbalance transactions)-                            all  - also round cost amounts to precision-                                   (can unbalance transactions)--   'close' currently has six modes, selected by a single mode flag:--* Menu:--* close --migrate::-* close --close::-* close --open::-* close --assert::-* close --assign::-* close --retain::-* close customisation::-* close and balance assertions::-* close examples::---File: hledger.info,  Node: close --migrate,  Next: close --close,  Up: close--31.1.1 close -migrate------------------------This is the most common mode.  It prints a "closing balances"-transaction that zeroes out all asset and liability balances (by-default), and an opposite "opening balances" transaction that restores-them again.  The balancing account will be 'equity:opening/closing-balances' (or another specified by '--close-acct' or '--open-acct').--   This is useful when migrating balances to a new journal file at the-start of a new year.  Essentially, you run 'hledger close---migrate=NEWYEAR -e NEWYEAR' and then copy the closing transaction to-the end of the old file and the opening transaction to the start of the-new file.  The opening transaction sets correct starting balances in the-new file when it is used alone, and the closing transaction keeps-balances correct when you use both old and new files together, by-cancelling out the following opening transaction and preventing buildup-of duplicated opening balances.  Think of the closing/opening pair as-"moving the balances into the next file".--   You can close a different set of accounts by providing a query.  Eg-if you want to include equity, you can add 'assets liabilities equity'-or 'type:ALE' arguments.  (The balancing account is always excluded.)-Revenues and expenses usually are not migrated to a new file directly;-see '--retain' below.--   The generated transactions will have a 'start:' tag, with its value-set to '--migrate''s 'NEW' argument if any, for easier matching or-exclusion.  When 'NEW' is not specified, it will be inferred if possible-by incrementing a number (eg a year number) within the default journal's-main file name.  The other modes behave similarly.---File: hledger.info,  Node: close --close,  Next: close --open,  Prev: close --migrate,  Up: close--31.1.2 close -close----------------------This prints just the closing balances transaction of '--migrate'.  It is-the default behaviour if you specify no mode flag.  Using the-customisation options below, you can move balances from any set of-accounts to a different account.---File: hledger.info,  Node: close --open,  Next: close --assert,  Prev: close --close,  Up: close--31.1.3 close -open---------------------This prints just the opening balances transaction of '--migrate'.  It is-similar to Ledger's equity command.---File: hledger.info,  Node: close --assert,  Next: close --assign,  Prev: close --open,  Up: close--31.1.4 close -assert-----------------------This prints a "closing balances" transaction (with 'balances:' tag),-that just declares balance assertions for the current balances without-changing them.  It could be useful as documention and to guard against-changes.---File: hledger.info,  Node: close --assign,  Next: close --retain,  Prev: close --assert,  Up: close--31.1.5 close -assign-----------------------This prints an "opening balances" transaction that restores the account-balances using balance assignments.  Balance assignments work regardless-of any previous balance, so a preceding closing balances transaction is-not needed.--   However, omitting the closing balances transaction would unbalance-equity.  This is relatively harmless for personal reports, but it-disturbs the accounting equation, removing a source of error detection.-So '--migrate' is generally the best way to set to set balances in new-files, for now.---File: hledger.info,  Node: close --retain,  Next: close customisation,  Prev: close --assign,  Up: close--31.1.6 close -retain-----------------------This is like '--close' with different defaults: it prints a "retain-earnings" transaction (with 'retain:' tag), that transfers revenue and-expense balances to 'equity:retained earnings'.--   This is a different kind of closing, called "retaining earnings" or-"closing the books"; it is traditionally performed by businesses at the-end of each accounting period, to consolidate revenues and expenses into-the main equity balance.  ("Revenues" and "expenses" are actually equity-by another name, kept separate temporarily for reporting purposes.)--   In personal accounting you generally don't need to do this, unless-you want the 'balancesheetequity' report to show a zero total,-demonstrating that the accounting equation (A-L=E) is satisfied.---File: hledger.info,  Node: close customisation,  Next: close and balance assertions,  Prev: close --retain,  Up: close--31.1.7 close customisation-----------------------------In all modes, the following things can be overridden:--   * the accounts to be closed/opened, with account query arguments-   * the balancing account, with '--close-acct=ACCT' and/or-     '--open-acct=ACCT'-   * the transaction descriptions, with '--close-desc=DESC' and-     '--open-desc=DESC'-   * the transaction's tag value, with a '--MODE=NEW' option argument-   * the closing/opening dates, with '-e OPENDATE'--   By default, the closing date is yesterday, or the journal's end date,-whichever is later; and the opening date is always one day after the-closing date.  You can change these by specifying a report end date; the-closing date will be the last day of the report period.  Eg '-e 2024'-means "close on 2023-12-31, open on 2024-01-01".--   With '--x/--explicit', the balancing 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 '--interleaved', each individual transfer is shown with source-and destination postings next to each other (perhaps useful for-troubleshooting).--   With '--show-costs', balances' costs are also shown, with different-costs kept separate.  This may generate very large journal entries, if-you have many currency conversions or investment transactions.  'close---show-costs' is currently the best way to view investment lots with-hledger.  (To move or dispose of lots, see the more capable-'hledger-move' script.)---File: hledger.info,  Node: close and balance assertions,  Next: close examples,  Prev: close customisation,  Up: close--31.1.8 close and balance assertions--------------------------------------'close' adds balance assertions verifying that the accounts have been-reset to zero in a closing transaction or restored to their previous-balances in an opening transaction.  These provide useful error-checking, but you can ignore them temporarily with '-I', or remove them-if you prefer.--   Single-commodity, subaccount-exclusive balance assertions ('=') are-generated by default.  This can be changed with '--assertion-type='==*''-(eg).--   When running 'close' you should probably avoid using '-C', '-R',-'status:' (filtering by status or realness) or '--auto' (generating-postings), since the generated balance assertions would then require-these.--   Transactions with multiple dates (eg posting dates) spanning the file-boundary also can 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 this you can transfer the money to and from a temporary-account, 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: close examples,  Prev: close and balance assertions,  Up: close--31.1.9 close examples------------------------* Menu:--* Retain earnings::-* Migrate balances to a new file::-* More detailed close examples::---File: hledger.info,  Node: Retain earnings,  Next: Migrate balances to a new file,  Up: close examples--31.1.9.1 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--   After this, to see 2022's revenues and expenses you must exclude the-retain earnings transaction:--$ hledger -f 2022.journal is not:desc:'retain earnings'---File: hledger.info,  Node: Migrate balances to a new file,  Next: More detailed close examples,  Prev: Retain earnings,  Up: close examples--31.1.9.2 Migrate balances to a new file-.......................................--Close assets/liabilities 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--   After this, to see 2022's end-of-year balances you must exclude the-closing balances transaction:--$ hledger -f 2022.journal bs not:desc:'closing balances'--   For more flexibility, it helps to tag closing and opening-transactions with eg 'start:NEWYEAR', then you can ensure correct-balances by excluding all opening/closing transactions except the first,-like so:--$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'-$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:start=2021 or not tag:start'-$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:start=2022 or not tag:start'-$ hledger bs -Y -f 2021.j                     expr:'tag:start=2021 or not tag:start'-$ hledger bs -Y -f 2022.j                     expr:'tag:start=2022 or not tag:start'-$ hledger bs -Y -f 2023.j                     # unclosed file, no query needed---File: hledger.info,  Node: More detailed close examples,  Prev: Migrate balances to a new file,  Up: close examples--31.1.9.3 More detailed close examples-.....................................--See examples/multi-year.---File: hledger.info,  Node: rewrite,  Prev: close,  Up: Data generation commands--31.2 rewrite-============--Print all transactions, rewriting the postings of matched transactions.-For now the only rewrite available is adding new postings, like print--auto.--Flags:-     --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be-                                    parenthesised. AMTEXPR is either a literal-                                    amount, or *N which means the transaction's-                                    first matched amount multiplied by N (a-                                    decimal number). Two spaces separate ACCT-                                    and AMTEXPR.-     --diff                         generate diff suitable as an input for-                                    patch tool--   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--31.2.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--31.2.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--31.2.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: Maintenance commands,  Next: PART 5 COMMON TASKS,  Prev: Data generation commands,  Up: Top--32 Maintenance commands-***********************--* Menu:--* check::-* diff::-* test::---File: hledger.info,  Node: check,  Next: diff,  Up: Maintenance commands--32.1 check-==========--Check for various kinds of errors in your data.--Flags:-no command-specific flags--   hledger provides a number of built-in correctness checks to help-validate your data and prevent errors.  Some are run automatically, some-when you enable '--strict' mode; or you can run any of them on demand by-providing them as arguments to the 'check' command.  'check' produces no-output and a zero exit code if all is well.  Eg:--hledger check                      # run basic checks-hledger check -s                   # run basic and strict checks-hledger check ordereddates payees  # run basic checks and two others--   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.  Generally, they are-performed in the order they are shown here (and only the first failure-is reported).--* Menu:--* Basic checks::-* Strict checks::-* Other checks::-* Custom checks::---File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check--32.1.1 Basic checks----------------------These important checks are performed by default, by almost all hledger-commands:--   * *parseable* - data files are in a supported format, with no syntax-     errors and no invalid include directives.  This ensures that all-     files exist and are readable.--   * *autobalanced* - all transactions are balanced, after inferring-     missing amounts and conversion costs where possible, and then-     converting to cost.  This ensures that each individual transaction-     is well formed.--   * *assertions* - all balance assertions in the journal are passing.-     Balance assertions are like canaries in your journal, they catch-     many problems.  They can get in the way sometimes; you can disable-     them temporarily with '-I'/'--ignore-assertions' (unless overridden-     with '-s'/'--strict' or 'hledger check assertions').---File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check--32.1.2 Strict checks-----------------------These additional checks are performed by any command when the-'-s'/'--strict' flag is used (strict mode).  Strict mode always enables-the balance assertions check, also.  These provide extra error-catching-power when you are serious about keeping your data clean and free of-typos:--   * *balanced* - like 'autobalanced', but in conversion transactions,-     costs must be written explicitly.  This ensures some redundancy in-     the entry, which helps prevent typos.--   * *commodities* - all commodity symbols used must be declared.  This-     guards against mistyping or omitting commodity symbols.--   * *accounts* - all account names used must be declared.  This-     prevents the use of mis-spelled or outdated account names.---File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check--32.1.3 Other checks----------------------These other checks are not wanted by everyone, but can be run using the-'check' command:--   * *ordereddates* - within each file, transactions are ordered by-     date.  This is a simple and effective error catcher, and you should-     use it.  Alas!  not everyone wants it.  If you do, use 'hledger-     check -s ordereddates'.  When enabled, this check is performed-     early, before balance assertions (because copy-pasted dates are-     often the root cause of balance assertion failures).--   * *payees* - all payees used by transactions must be declared.  This-     will force you to always use known/declared payee names.  For most-     people this is a bit too restrictive.--   * *tags* - all tags used by transactions must be declared.  This-     prevents mistyped tag names.--   * *recentassertions* - all accounts with balance assertions must have-     a balance assertion within the last 7 days before their latest-     posting.  This encourages you to add balance assertions fairly-     regularly for your active asset/liability accounts, which in turn-     should encourage you to check and reconcile with their real world-     balances fairly regularly.  'close --assert' can be helpful.  (The-     older balance assertions become redundant; you can remove them-     periodically, or leave them in place, perhaps commented, as-     documentation.)--   * *uniqueleafnames* - no two accounts may have the same leaf name.-     The leaf name is the last colon-separated part of an account name,-     eg 'checking' in 'assets:bank:checking'.  This encourages you to-     keep those unique, effectively giving each account a short name-     which is easier to remember and to type in reporting commands.---File: hledger.info,  Node: Custom checks,  Prev: Other checks,  Up: check--32.1.4 Custom checks-----------------------You can build your own custom checks with add-on command scripts.  See-also Cookbook > Scripting.  Here are some examples from hledger/bin/:--   * *hledger-check-tagfiles* - all tag values containing / (a forward-     slash) exist as file paths--   * *hledger-check-fancyassertions* - more complex balance assertions-     are passing---File: hledger.info,  Node: diff,  Next: test,  Prev: check,  Up: Maintenance commands--32.2 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.--Flags:-no command-specific flags--   More precisely: for each posting affecting this account in either-file, this command looks for a corresponding posting in the other file-which posts the same amount to the same account (ignoring date,-description, etc).--   Since it compares postings, not transactions, this also works when-multiple bank transactions have been combined into a single journal-entry.--   This command 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: test,  Prev: diff,  Up: Maintenance commands--32.3 test-=========--Run built-in unit tests.--Flags:-no command-specific flags--   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: Getting help,  Prev: Maintenance commands,  Up: Top--33 PART 5: COMMON TASKS-***********************--Here are some quick examples of how to do some basic tasks with hledger.---File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Prev: PART 5 COMMON TASKS,  Up: Top--34 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: Top--35 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: Top--36 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: Top--37 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"--   When correctly configured, in a new terminal window-'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'.---File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Setting LEDGER_FILE,  Up: Top--38 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: Top--39 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: Top--40 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: Top--41 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,  Next: BUGS,  Prev: Reporting,  Up: Top--42 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: Migrating to a new file,  Up: Top--43 BUGS-*******--We welcome bug reports in the hledger issue tracker (shortcut:-https://bugs.hledger.org), or on the hledger chat or 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--43.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).  On Windows,-     '$env:LEDGER_FILE' should show it.-   * 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 INTERFACE4362-Node: Input4501-Node: Text encoding5593-Node: Data formats6273-Node: Standard input7997-Node: Multiple files8386-Node: Strict mode9123-Node: Commands9957-Node: Add-on commands11143-Node: Options12361-Node: Special characters18935-Node: Escaping shell special characters19885-Node: Escaping on Windows21129-Node: Escaping regular expression special characters21862-Node: Escaping add-on arguments22849-Node: Escaping in other situations23878-Node: Using a wild card24837-Node: Unicode characters25216-Node: Regular expressions26880-Node: hledger's regular expressions30139-Node: Argument files31780-Node: Config files32483-Node: Shell completions35636-Node: Output36161-Node: Output destination36352-Node: Output format36910-Node: Text output38696-Node: Box-drawing characters39893-Node: Colour40393-Node: Paging40979-Node: HTML output42430-Node: CSV / TSV output42884-Node: FODS output43138-Node: Beancount output43942-Node: Beancount account names45140-Node: Beancount commodity names45681-Node: Beancount virtual postings46328-Node: Beancount metadata46644-Node: Beancount costs47424-Node: Beancount operating currency47840-Node: SQL output48290-Node: JSON output49081-Node: Commodity styles49898-Node: Debug output50782-Node: Environment51614-Node: PART 2 DATA FORMATS52463-Node: Journal52606-Node: Journal cheatsheet55084-Node: Comments61298-Node: Transactions62242-Node: Dates63379-Node: Simple dates63531-Node: Posting dates64147-Node: Status65234-Node: Code67000-Node: Description67335-Node: Payee and note68022-Node: Transaction comments69113-Node: Postings69629-Node: Debits and credits70792-Node: The two space delimiter71402-Node: Account names71967-Node: Amounts73771-Node: Decimal marks74800-Node: Digit group marks75904-Node: Commodity76539-Node: Costs77656-Node: Balance assertions79908-Node: Assertions and ordering81171-Node: Assertions and multiple included files81899-Node: Assertions and multiple -f files82659-Node: Assertions and costs83301-Node: Assertions and commodities83951-Node: Assertions and subaccounts85610-Node: Assertions and status86270-Node: Assertions and virtual postings86690-Node: Assertions and auto postings87055-Node: Assertions and precision87930-Node: Posting comments88381-Node: Transaction balancing88921-Node: Tags90923-Node: Querying with tags92217-Node: Displaying tags93016-Node: When to use tags ?93412-Node: Tag names94076-Node: Special tags94629-Node: Directives96194-Node: Directives and multiple files97651-Node: Directive effects98596-Node: account directive101752-Node: Account comments103202-Node: Account error checking103861-Node: Account display order105398-Node: Account types106596-Node: alias directive110370-Node: Basic aliases111581-Node: Regex aliases112456-Node: Combining aliases113503-Node: Aliases and multiple files114957-Node: end aliases directive115740-Node: Aliases can generate bad account names116108-Node: Aliases and account types116941-Node: commodity directive117829-Node: Commodity directive syntax119416-Node: Commodity error checking121052-Node: decimal-mark directive121527-Node: include directive122106-Node: P directive123182-Node: payee directive124216-Node: tag directive124838-Node: Periodic transactions125450-Node: Periodic rule syntax127604-Node: Periodic rules and relative dates128427-Node: Two spaces between period expression and description!129204-Node: Auto postings130165-Node: Auto postings and multiple files133325-Node: Auto postings and dates133730-Node: Auto postings and transaction balancing / inferred amounts / balance assertions134171-Node: Auto posting tags135017-Node: Auto postings on forecast transactions only135912-Node: Other syntax136382-Node: Balance assignments137154-Node: Balance assignments and costs138682-Node: Balance assignments and multiple files139104-Node: Bracketed posting dates139527-Node: D directive140225-Node: apply account directive141998-Node: Y directive142865-Node: Secondary dates143853-Node: Star comments145338-Node: Valuation expressions146030-Node: Virtual postings146329-Node: Other Ledger directives147953-Node: Other cost/lot notations148715-Node: CSV151477-Node: CSV rules cheatsheet153560-Node: source155485-Node: separator156486-Node: skip157137-Node: date-format157787-Node: timezone158630-Node: newest-first159756-Node: intra-day-reversed160469-Node: decimal-mark161069-Node: fields list161547-Node: Field assignment163355-Node: Field names164574-Node: date field165906-Node: date2 field166070-Node: status field166265-Node: code field166455-Node: description field166643-Node: comment field166860-Node: account field167417-Node: amount field168135-Node: currency field170974-Node: balance field171382-Node: if block171905-Node: Matchers173432-Node: Multiple matchers175422-Node: Match groups175898-Node: if table176791-Node: balance-type178792-Node: include179619-Node: Working with CSV180188-Node: Rapid feedback180740-Node: Valid CSV181323-Node: File Extension182199-Node: Reading CSV from standard input182934-Node: Reading multiple CSV files183320-Node: Reading files specified by rule183796-Node: Valid transactions185193-Node: Deduplicating importing186018-Node: Setting amounts187247-Node: Amount signs189774-Node: Setting currency/commodity190839-Node: Amount decimal places192215-Node: Referencing other fields193472-Node: How CSV rules are evaluated194580-Node: Well factored rules196248-Node: CSV rules examples196738-Node: Bank of Ireland196936-Node: Coinbase198533-Node: Amazon199716-Node: Paypal201558-Node: Timeclock209308-Node: Timedot211577-Node: Timedot examples215054-Node: PART 3 REPORTING CONCEPTS217331-Node: Time periods217495-Node: Report start & end date217768-Node: Smart dates219244-Node: Report intervals221187-Node: Date adjustments221761-Node: Start date adjustment221981-Node: End date adjustment222884-Node: Period headings223629-Node: Period expressions224562-Node: Period expressions with a report interval226467-Node: More complex report intervals226915-Node: Multiple weekday intervals229031-Node: Depth230042-Node: Queries231877-Node: Query types233575-Node: acct query233992-Node: amt query234303-Node: code query234920-Node: cur query235115-Node: desc query235721-Node: date query235904-Node: date2 query236300-Node: depth query236591-Node: expr query236927-Node: not query237308-Node: note query237648-Node: payee query237914-Node: real query238195-Node: status query238400-Node: type query238640-Node: tag query239173-Node: Combining query terms239802-Node: Queries and command options241542-Node: Queries and account aliases241996-Node: Queries and valuation242321-Node: Pivoting242683-Node: Generating data244574-Node: Forecasting246374-Node: --forecast247030-Node: Inspecting forecast transactions248131-Node: Forecast reports249464-Node: Forecast tags250573-Node: Forecast period in detail251193-Node: Forecast troubleshooting252281-Node: Budgeting253352-Node: Amount formatting253912-Node: Commodity display style254156-Node: Rounding255997-Node: Trailing decimal marks256602-Node: Amount parseability257535-Node: Cost reporting259116-Node: Recording costs259919-Node: Reporting at cost261646-Node: Equity conversion postings262411-Node: Inferring equity conversion postings265056-Node: Combining costs and equity conversion postings266198-Node: Requirements for detecting equity conversion postings267423-Node: Infer cost and equity by default ?268945-Node: Value reporting269382-Node: -V Value270263-Node: -X Value in specified commodity270590-Node: Valuation date270940-Node: Finding market price271900-Node: --infer-market-prices market prices from transactions273280-Node: Valuation commodity276324-Node: --value Flexible valuation277757-Node: Valuation examples279600-Node: Interaction of valuation and queries281732-Node: Effect of valuation on reports282449-Node: PART 4 COMMANDS290347-Node: Help commands292563-Node: help292736-Node: demo294441-Node: User interface commands295588-Node: ui295782-Node: web295907-Node: Data entry commands296035-Node: add296233-Node: import298688-Node: Import preview299722-Node: Overlap detection300670-Node: First import303556-Node: Importing balance assignments304751-Node: Import and commodity styles305806-Node: Import special cases306244-Node: Basic report commands307579-Node: accounts307880-Node: codes310753-Node: commodities311775-Node: descriptions312019-Node: files312486-Node: notes312783-Node: payees313295-Node: prices314079-Node: stats314971-Node: tags316712-Node: Standard report commands318019-Node: print318324-Node: print explicitness320998-Node: print amount style321918-Node: print parseability323156-Node: print other features324075-Node: print output format324773-Node: aregister328058-Node: aregister and posting dates332558-Node: register333459-Node: Custom register output340646-Node: balancesheet342122-Node: balancesheetequity347034-Node: cashflow352316-Node: incomestatement357020-Node: Advanced report commands361760-Node: balance361968-Node: balance features367138-Node: Simple balance report369214-Node: Balance report line format371024-Node: Filtered balance report373384-Node: List or tree mode373903-Node: Depth limiting375416-Node: Dropping top-level accounts376183-Node: Showing declared accounts376693-Node: Sorting by amount377423-Node: Percentages378260-Node: Multi-period balance report378967-Node: Balance change end balance381719-Node: Balance report types383356-Node: Calculation type384035-Node: Accumulation type384739-Node: Valuation type385840-Node: Combining balance report types387029-Node: Budget report389061-Node: Using the budget report391366-Node: Budget date surprises393642-Node: Selecting budget goals395006-Node: Budgeting vs forecasting395954-Node: Balance report layout397631-Node: Wide layout398836-Node: Tall layout401241-Node: Bare layout402547-Node: Tidy layout404611-Node: Balance report output406155-Node: Some useful balance reports407141-Node: roi408401-Node: Spaces and special characters in --inv and --pnl410648-Node: Semantics of --inv and --pnl411374-Node: IRR and TWR explained413461-Node: Chart commands416872-Node: activity417053-Node: Data generation commands417550-Node: close417756-Node: close --migrate420348-Node: close --close422112-Node: close --open422490-Node: close --assert422739-Node: close --assign423104-Node: close --retain423776-Node: close customisation424672-Node: close and balance assertions426316-Node: close examples427838-Node: Retain earnings428075-Node: Migrate balances to a new file428578-Node: More detailed close examples429930-Node: rewrite430152-Node: Re-write rules in a file432724-Node: Diff output format434034-Node: rewrite vs print --auto435307-Node: Maintenance commands436021-Node: check436230-Node: Basic checks437312-Node: Strict checks438265-Node: Other checks439140-Node: Custom checks440995-Node: diff441450-Node: test442657-Node: PART 5 COMMON TASKS443529-Node: Getting help443762-Node: Constructing command lines444671-Node: Starting a journal file445509-Node: Setting LEDGER_FILE446893-Node: Setting opening balances448151-Node: Recording transactions451473-Node: Reconciling452198-Node: Reporting454587-Node: Migrating to a new file458701-Node: BUGS459150-Node: Troubleshooting460115+This is hledger.info, produced by makeinfo version 7.2 from stdin.++INFO-DIR-SECTION User Applications+START-INFO-DIR-ENTRY+* hledger: (hledger).  Command-line plain text accounting tool.+END-INFO-DIR-ENTRY+++File: hledger.info,  Node: Top,  Next: PART 1 USER INTERFACE,  Up: (dir)++hledger(1)+**********++hledger - a robust, friendly plain text accounting app (command line+version).++   'hledger'+or+'hledger COMMAND [OPTS] [ARGS]'+or+'hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]'++   hledger is a robust, user-friendly, cross-platform set of programs+for tracking money, time, or any other commodity, using double-entry+accounting and a simple, editable file format.  hledger is inspired by+and largely compatible with ledger(1), and largely interconvertible with+beancount(1).++   This manual is for hledger's command line interface, version 1.42.+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 open a built-in+copy, at a point of interest, by running+'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'.++   (And for shorter help, try 'hledger --tldr [CMD]'.)++   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::+* Output::+* Environment::+* PART 2 DATA FORMATS::+* Journal::+* CSV::+* Timeclock::+* Timedot::+* PART 3 REPORTING CONCEPTS::+* Time periods::+* Depth::+* Queries::+* Pivoting::+* Generating data::+* Forecasting::+* Budgeting::+* Amount formatting::+* Cost reporting::+* Value reporting::+* PART 4 COMMANDS::+* Help commands::+* User interface commands::+* Data entry commands::+* Basic report commands::+* Standard report commands::+* Advanced report commands::+* Chart commands::+* Data generation commands::+* Maintenance commands::+* PART 5 COMMON TASKS::+* Getting help::+* Constructing command lines::+* Starting a journal file::+* Setting LEDGER_FILE::+* Setting opening balances::+* Recording transactions::+* Reconciling::+* Reporting::+* Migrating to a new file::+* 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 [-f FILE2 ...] 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:++* Text encoding::+* Data formats::+* Standard input::+* Multiple files::+* Strict mode::+++File: hledger.info,  Node: Text encoding,  Next: Data formats,  Up: Input++2.1 Text encoding+=================++hledger input files containing non-ascii characters must use UTF-8+encoding, with the exception of CSV (SSV, TSV..) files, which can be+read from other encodings (see 'encoding' CSV rule).++   In UTF-8 input files, an optional byte order mark (BOM) at the+beginning of the file is allowed.++   Your system may need to be configured with a locale that understands+the input file's encoding.  Eg on some unix systems, you may need set+the 'LANG' environment variable.  You can read more about this in+Unicode characters, below.++   On some unix systems you can use the 'file' command to show a file's+text encoding.  On mac, you'll need the version from homebrew: 'brew+install file-formula'.++   hledger's text output is always UTF-8 encoded.+++File: hledger.info,  Node: Data formats,  Next: Standard input,  Prev: Text encoding,  Up: Input++2.2 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:                             Automatically used for+                                                  files with extensions:+---------------------------------------------------------------------------+'journal'      hledger journal files and some     '.journal' '.j'+               Ledger journals, for               '.hledger' '.ledger'+               transactions+'timeclock'    timeclock files, for precise       '.timeclock'+               time logging+'timedot'      timedot files, for approximate     '.timedot'+               time logging+'csv'          Comma or other character           '.csv'+               separated values, for data+               import+'ssv'          Semicolon separated values         '.ssv'+'tsv'          Tab separated values               '.tsv'+'rules'        CSV/SSV/TSV/other separated        '.rules'+               values, alternate way++   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 containing+tab separated values:++$ hledger -f tsv:/some/file.dat stats+++File: hledger.info,  Node: Standard input,  Next: Multiple files,  Prev: Data formats,  Up: Input++2.3 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 write the+format as a prefix, like 'timeclock:' here:++$ 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.4 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.5 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 a summary of commands, run 'hledger' with no arguments.  You+can see the same commands summary at the start of 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: Output,  Prev: Commands,  Up: Top++4 Options+*********++Run 'hledger -h' to see general command line help.  Options can be+written either before or after the command name.  These options are+specific to the 'hledger' CLI:++Flags:+     --conf=CONFFILE        Use extra options defined in this config file. If+                            not specified, searches upward and in XDG config+                            dir for hledger.conf (or .hledger.conf in $HOME).+  -n --no-conf              ignore any config file++   And the following general options are common to most hledger+commands:++General input/data transformation flags:+  -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,+                            inferring format from extension or a FMT: prefix.+                            Can be specified more than once. If not specified,+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.+     --rules=RULESFILE      Use rules defined in this rules file for+                            converting subsequent CSV/SSV/TSV files. If not+                            specified, uses FILE.csv.rules for each FILE.csv.+     --alias=A=B|/RGX/=RPL  transform account names from A to B, or by+                            replacing regular expression matches+     --auto                 generate extra postings by applying auto posting+                            rules ("=") to all transactions+     --forecast[=PERIOD]    Generate extra transactions from periodic rules+                            ("~"), from after the latest ordinary transaction+                            until 6 months from now. Or, during the specified+                            PERIOD (the equals is required). Auto posting rules+                            will also be applied to these transactions. In+                            hledger-ui, also make future-dated transactions+                            visible at startup.+  -I --ignore-assertions    don't check balance assertions by default+     --infer-costs          infer conversion equity postings from costs+     --infer-equity         infer costs from conversion equity postings+     --infer-market-prices  infer market prices from costs+     --pivot=TAGNAME        use a different field or tag as account names+  -s --strict               do extra error checks (and override -I)+     --verbose-tags         add tags indicating generated/modified data++General output/reporting flags (supported by some commands):+  -b --begin=DATE           include postings/transactions on/after this date+  -e --end=DATE             include postings/transactions before this date+                            (with a report interval, will be adjusted to+                            following subperiod end)+  -D --daily                multiperiod report with 1 day interval+  -W --weekly               multiperiod report with 1 week interval+  -M --monthly              multiperiod report with 1 month interval+  -Q --quarterly            multiperiod report with 1 quarter interval+  -Y --yearly               multiperiod report with 1 year interval+  -p --period=PERIODEXP     set begin date, end date, and/or report interval,+                            with more flexibility+     --today=DATE           override today's date (affects relative dates)+     --date2                match/use secondary dates instead (deprecated)+  -U --unmarked             include only unmarked postings/transactions+  -P --pending              include only pending postings/transactions+  -C --cleared              include only cleared postings/transactions+                            (-U/-P/-C can be combined)+  -R --real                 include only non-virtual postings+  -E --empty                Show zero items, which are normally hidden.+                            In hledger-ui & hledger-web, do the opposite.+     --depth=DEPTHEXP       if a number (or -NUM): show only top NUM levels+                            of accounts. If REGEXP=NUM, only apply limiting to+                            accounts matching the regular expression.+  -B --cost                 show amounts converted to their cost/sale amount+  -V --market               Show amounts converted to their value at period+                            end(s) in their default valuation commodity.+                            Equivalent to --value=end.+  -X --exchange=COMM        Show amounts converted to their value at period+                            end(s) in the specified commodity.+                            Equivalent to --value=end,COMM.+     --value=WHEN[,COMM]    show amounts converted to their value on the+                            specified date(s) in their default valuation+                            commodity or a specified commodity. WHEN can be:+                            'then':     value on transaction dates+                            'end':      value at period end(s)+                            'now':      value today+                            YYYY-MM-DD: value on given date+  -c --commodity-style=S    Override a commodity's display style.+                            Eg: -c '.' or -c '1.000,00 EUR'+     --pretty[=YN]          Use box-drawing characters in text output? Can be+                            'y'/'yes' or 'n'/'no'.+                            If YN is specified, the equals is required.++General help flags:+  -h --help                 show command line help+     --tldr                 show command examples with tldr+     --info                 show the manual with info+     --man                  show the manual with man+     --version              show version information+     --debug=[1-9]          show this much debug output (default: 1)+     --pager=YN             use a pager when needed ? y/yes (default) or n/no+     --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)++   Usually hledger accepts any unambiguous flag prefix, eg you can write+'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'.++   If the same option appears more than once in a command, usually the+last (right-most) wins.++   With most commands, arguments are interpreted as a hledger query+which filter the data.  Some queries can be expressed either with+options or with arguments.++   Below are more tips for using the command line interface - feel free+to skip these until you need them.++* Menu:++* Special characters::+* Unicode characters::+* Regular expressions::+* Argument files::+* Config files::+* Shell completions::+++File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Up: Options++4.1 Special characters+======================++Here we touch on shell escaping/quoting rules, and give some examples.+This is a slightly complicated topic which you may not need at first,+but you should be aware of it, so you can return here when needed.++   If you are able to minimise the use of special characters in your+data, you won't need escaping as much, and your command lines will be+simpler.  For example, avoiding spaces in account names, and using an+ISO-4217 currency code like 'USD' instead of the '$' currency symbol,+can be helpful.++   But if you want to use spaced account names and '$', go right ahead;+escaping isn't a big deal.++* Menu:++* Escaping shell special characters::+* Escaping on Windows::+* Escaping regular expression special characters::+* Escaping add-on arguments::+* Escaping in other situations::+* Using a wild card::+++File: hledger.info,  Node: Escaping shell special characters,  Next: Escaping on Windows,  Up: Special characters++4.1.1 Escaping shell special characters+---------------------------------------++At the command line, characters which have special meaning for your+shell must be "shell-escaped" (AKA "quoted") if you want hledger to see+them.  Often these include space, '<', '>', '(', ')', '|', '\', '$'+and/or '%'.++   For example, to match an account name containing the phrase "credit+card", don't write this:++$ hledger register credit card++   In that command, "credit" and "card" are treated as separate query+arguments (described below), so this would match accounts containing+either word.  Instead, enclose the phrase in double or single quotes:++$ hledger register "credit card"++   In Unix shells, writing a backslash before the character can also+work.  Eg:++$ hledger register credit\ card++   Some shell characters still have a special meaning inside double+quotes, such as the dollar sign ('$').  Eg in '"assets:$account"', the+bash shell would replace '$account' with the value of a shell variable+with that name.  When you don't want that, use single quotes, which+escape more strongly:++$ hledger balance 'assets:$account'+++File: hledger.info,  Node: Escaping on Windows,  Next: Escaping regular expression special characters,  Prev: Escaping shell special characters,  Up: Special characters++4.1.2 Escaping on Windows+-------------------------++If you are using hledger in a Powershell or Command window on Microsoft+Windows, the escaping rules are different:++   * In a Powershell window ('powershell', blue background), you must+     use double quotes or single quotes (not backslash).+   * In a Command window ('cmd', black background), you must use double+     quotes (not single quotes or backslash).++   The next two sections were written for Unix-like shells, so might+need to be adapted if you're using 'cmd' or 'powershell'.  (Edits+welcome.)+++File: hledger.info,  Node: Escaping regular expression special characters,  Next: Escaping add-on arguments,  Prev: Escaping on Windows,  Up: Special characters++4.1.3 Escaping regular expression special characters+----------------------------------------------------++Many hledger arguments are regular expressions (described below), and+these too have characters which cause special effects.  Some of those+characters are '.', '^', '$', '[', ']', '(', ')', '|', and '\'.  When+you don't want these to cause special effects, you can "regex-escape"+them by writing '\' (a backslash) before them.  But since backslash is+also special to the shell, you may need to also shell-escape the+backslashes.++   Eg, in the bash shell, to match a literal '$' sign, you could write:++$ hledger balance cur:\\$++   or:++$ hledger balance 'cur:\$'++   (The dollar sign is regex-escaped by the backslash preceding it.+Then that backslash is shell-escaped by another backslash, or by single+quotes.)+++File: hledger.info,  Node: Escaping add-on arguments,  Next: Escaping in other situations,  Prev: Escaping regular expression special characters,  Up: Special characters++4.1.4 Escaping add-on arguments+-------------------------------++When you run an external add-on command with 'hledger' (described+below), any options or arguments being passed through to the add-on+executable lose one level of shell-escaping, so you must add an extra+level of shell-escaping to compensate.++   Eg, in the bash shell, to run the 'ui' add-on and match a literal '$'+sign, you need to write:++$ hledger ui cur:'\\$'++   or:++$ hledger ui cur:\\\\$++   If you are wondering why _four_ backslashes:++   * '$' is unescaped+   * '\$' is regex-escaped+   * '\\$' is regex-escaped, then shell-escaped+   * '\\\\$' is regex-escaped, then shell-escaped, then both slashes are+     shell-escaped once more for hledger argument pass-through.++   Or you can avoid such triple-escaping, by running the add-on+executable directly:++$ hledger-ui cur:\\$+++File: hledger.info,  Node: Escaping in other situations,  Next: Using a wild card,  Prev: Escaping add-on arguments,  Up: Special characters++4.1.5 Escaping in other situations+----------------------------------++hledger options and arguments are sometimes used in places other than+the command line, with different escaping rules.  For example,+backslash-quoting generally does not work there.  Here are some more+tips.++In Windows 'cmd'   Use double quotes+In Windows         Use single or double quotes+'powershell'+In hledger-ui's    Use single or double quotes+filter prompt+In hledger-web's   Use single or double quotes+search form+In an argument     Don't use spaces, don't shell-escape, do+file               regex-escape when needed+In a config file   Use single or double quotes, and enclose the whole+                   argument ('"desc:a b"' not 'desc:"a b"')+In 'ghci' (the     Use double quotes, and enclose the whole argument+Haskell REPL)+++File: hledger.info,  Node: Using a wild card,  Prev: Escaping in other situations,  Up: Special characters++4.1.6 Using a wild card+-----------------------++When escaping a special character is too much hassle (or impossible),+you can often just write '.' (period) instead.  In regular expressions,+this means "accept any character here".  Eg:++$ hledger register credit.card+++File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Options++4.2 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.  On Windows, you may need to use Windows+     Terminal and/or enable UTF-8 support.++   * 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: Options++4.3 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++4.3.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.+  7. they may not (I'm guessing not) properly support right-to-left or+     bidirectional text.++   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,  Next: Config files,  Prev: Regular expressions,  Up: Options++4.4 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'.++   An argument file's format is more restrictive than the command line.+Each line should contain just one option or argument.  Don't use spaces+except inside quotes; write '=' or nothing between a flag and its+argument.  If you use quotes, they must enclose the whole line.  For the+special characters mentioned above, use one less level of quoting than+you would at the command line.+++File: hledger.info,  Node: Config files,  Next: Shell completions,  Prev: Argument files,  Up: Options++4.5 Config files+================++With hledger 1.40+, you can save extra command line options and+arguments in a more featureful hledger config file.  Here's a small+example:++# General options are listed first, and used with hledger commands that support them.+--pretty++# Options following a `[COMMAND]` heading are used with that hledger command only.+[print]+--explicit --show-costs++   To use a config file, specify it with the '--conf' option.  Its+options will be inserted near the start of your command line, so you can+override them with command line options if needed.++   Or, you can set up an automatic config file that is used whenever you+run hledger, by creating 'hledger.conf' in the current directory or+above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or+'hledger.conf' in your XDG config directory+('~/.config/hledger/hledger.conf').++   Here is another example config you could start with:+https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample++   You can put not only options, but also arguments in a config file.+If the first word in a config file's top (general) section does not+begin with a dash (eg: 'print'), it is treated as the command argument+(overriding any argument on the command line).++   On unix machines, you can add a shebang line at the top of a config+file, set executable permission on the file, and use it like a script.+Eg (the '-S' is needed on some operating systems):++#!/usr/bin/env -S hledger --conf++   You can ignore config files by adding the '-n'/'--no-conf' flag to+the command line.  This is useful when using hledger in scripts, or when+troubleshooting.  When both '--conf' and '--no-conf' options are used,+the right-most wins.++   To inspect the processing of config files, use '--debug' or+'--debug=8'.++   *Warning!*++   There aren't many hledger features that need a warning, but this is+one!++   Automatic config files, while convenient, also make hledger less+predictable and dependable.  It's easy to make a config file that+changes a report's behaviour, or breaks your hledger-using+scripts/applications, in ways that will surprise you later.++   If you don't want this,++  1. Just don't create a hledger.conf file on your machine.+  2. Also be alert to downloaded directories which may contain a+     hledger.conf file.+  3. Also if you are sharing scripts or examples or support, consider+     that others may have a hledger.conf file.++   Conversely, once you decide to use this feature, try to remember:++  1. Whenever a hledger command does not work as expected, try it again+     with '-n' ('--no-conf') to see if a config file was to blame.+  2. Whenever you call hledger from a script, consider whether that call+     should use '-n' or not.+  3. Be conservative about what you put in your config file; try to+     consider the effect on all your reports.+  4. To troubleshoot the effect of config files, run with '--debug' or+     '--debug 8'.++   The config file feature was added in hledger 1.40 and is considered+_experimental_.+++File: hledger.info,  Node: Shell completions,  Prev: Config files,  Up: Options++4.6 Shell completions+=====================++If you use the bash or zsh shells, you can optionally set up+context-sensitive autocompletion for hledger command lines.  Try+pressing 'hledger<SPACE><TAB><TAB>' (should list all hledger commands)+or 'hledger reg acct:<TAB><TAB>' (should list your top-level account+names).  If completions aren't working, or for more details, see Install+> Shell completions.+++File: hledger.info,  Node: Output,  Next: Environment,  Prev: Options,  Up: Top++5 Output+********++* Menu:++* Output destination::+* Output format::+* Commodity styles::+* Debug output::+++File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output++5.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++5.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:++command               txt   html   csv/tsv   fods   beancount    sql   json+------------------------------------------------------------------------------+aregister             Y     Y      Y         Y                         Y+balance               Y     Y      Y         Y                         Y+balancesheet          Y     Y      Y         Y                         Y+balancesheetequity    Y     Y      Y         Y                         Y+cashflow              Y     Y      Y         Y                         Y+incomestatement       Y     Y      Y         Y                         Y+print                 Y     Y      Y         Y      Y            Y     Y+register              Y     Y      Y         Y                         Y++   You can also see which output formats a command supports by running+'hledger CMD -h' and looking for the '-O'/'--output-format=FMT' option,++   You can select the output format by using that option:++$ hledger print -O csv    # print CSV to standard output++   or by choosing a suitable filename extension 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++   Here are some notes about the various output formats.++* Menu:++* Text output::+* HTML output::+* CSV / TSV output::+* FODS output::+* Beancount output::+* SQL output::+* JSON output::+++File: hledger.info,  Node: Text output,  Next: HTML output,  Up: Output format++5.2.1 Text output+-----------------++This is the default: human readable, plain text report output, suitable+for viewing with a monospace font in a terminal.  If your data contains+unicode or wide characters, you'll need a terminal and font that render+those correctly.  (This can be challenging on MS Windows.)++   Some reports ('register', 'aregister') will normally use the full+window width.  If this isn't working or you want to override it, you can+use the '-w'/'--width' option.++   Balance reports ('balance', 'balancesheet', 'incomestatement'...)+use whatever width they need.  Multi-period multi-currency reports can+often be wider than the window.  Besides using a pager, helpful+techniques for this situation include '--layout=bare', '-V', 'cur:',+'--transpose', '--tree', '--depth', '--drop', switching to html output,+etc.++* Menu:++* Box-drawing characters::+* Colour::+* Paging::+++File: hledger.info,  Node: Box-drawing characters,  Next: Colour,  Up: Text output++5.2.1.1 Box-drawing characters+..............................++hledger draws simple table borders by default, to minimise the risk of+display problems caused by a terminal/font not supporting box-drawing+characters.++   But your terminal and font probably do support them, so we recommend+using the '--pretty' flag to show prettier tables in the terminal.  This+is a good flag to add to your hledger config file.+++File: hledger.info,  Node: Colour,  Next: Paging,  Prev: Box-drawing characters,  Up: Text output++5.2.1.2 Colour+..............++hledger tries to automatically detect ANSI colour and text styling+support and use it when appropriate.  (Currently, it is used rather+minimally: some reports show negative numbers in red, and help output+uses bold text for emphasis.)++   You can override this by setting the 'NO_COLOR' environment variable+to disable it, or by using the '--color/--colour' option, perhaps in+your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or+off.+++File: hledger.info,  Node: Paging,  Prev: Colour,  Up: Text output++5.2.1.3 Paging+..............++In unix-like environments, when displaying large output (in any output+format) in the terminal, hledger tries to use a pager when appropriate.+(You can disable this with the '--pager=no' option, perhaps in your+config file.)++   The pager shows one page of text at a time, and lets you scroll+around to see more.  While it is active, usually 'SPACE' shows the next+page, 'h' shows help, and 'q' quits.  The home/end/page up/page+down/cursor keys, and mouse scrolling, may also work.++   hledger will use the pager specified by the 'PAGER' environment+variable, otherwise 'less' if available, otherwise 'more' if available.+(With one exception: 'hledger help -p TOPIC' will always use 'less', so+that it can scroll to the topic.)++   The pager is expected to display hledger's ANSI colour and text+styling.  If you see junk characters, you might need to configure your+pager to handle ANSI codes.  Or you could disable colour as described+above.++   If you are using the 'less' pager, hledger automatically appends a+number of options to the 'LESS' variable to enable ANSI colour and a+number of other conveniences.  (At the time of writing: -chop-long-lines+-hilite-unread -ignore-case -mouse -no-init -quit-at-eof+-quit-if-one-screen -RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines+-use-backslash ).  If these don't work well, you can set your preferred+options in the 'HLEDGER_LESS' variable, which will be used instead.+++File: hledger.info,  Node: HTML output,  Next: CSV / TSV output,  Prev: Text output,  Up: Output format++5.2.2 HTML output+-----------------++HTML output can be styled by an optional 'hledger.css' file in the same+directory.++   HTML output will be UTF-8 encoded.  If your web browser is showing+junk characters, you may need to change its text encoding to UTF-8.  Eg+in Safari, see View -> Text Encoding and Settings -> Advanced -> Default+Encoding.+++File: hledger.info,  Node: CSV / TSV output,  Next: FODS output,  Prev: HTML output,  Up: Output format++5.2.3 CSV / TSV output+----------------------++In CSV or TSV output, digit group marks (such as thousands separators)+are disabled automatically.+++File: hledger.info,  Node: FODS output,  Next: Beancount output,  Prev: CSV / TSV output,  Up: Output format++5.2.4 FODS output+-----------------++FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by+LibreOffice and OpenOffice.  If you use their spreadsheet applications,+this is better than CSV because it works across locales (decimal point+vs.  decimal comma, character encoding stored in XML header, thus no+problems with umlauts), it supports fixed header rows and columns, cell+types (string vs.  number vs.  date), separation of number and currency+(currency is displayed but the cell type is still a number accessible+for computation), styles (bold), borders.  Btw.  you can still extract+CSV from FODS/ODS using various utilities like 'libreoffice --headless'+or ods2csv.+++File: hledger.info,  Node: Beancount output,  Next: SQL output,  Prev: FODS output,  Up: Output format++5.2.5 Beancount output+----------------------++This is Beancount's journal format.  You can use this to export your+hledger data to Beancount, eg to use the Fava web app.++   hledger will try to adjust your data to suit Beancount,+automatically.  Be cautious and check the conversion until you are+confident it is good.  If you plan to export to Beancount often, you may+want to follow its conventions, for a cleaner conversion:++   * use Beancount-friendly account names+   * use currency codes instead of currency symbols+   * use cost notation instead of equity conversion postings+   * avoid virtual postings++   There is one big adjustment you must handle yourself: for Beancount,+the top level account names must be 'Assets', 'Liabilities', 'Equity',+'Income', and/or 'Expenses'.  You can use account aliases to rewrite+your account names temporarily, if needed, as in this+hledger2beancount.conf config file.++   2024-12-20: Some more things not yet handled for you:++   * P directives are not converted automatically - convert those+     yourself+   * Balance assignments are not converted (Beancount doesnt support+     them) - replace those with explicit amounts++* Menu:++* Beancount account names::+* Beancount commodity names::+* Beancount virtual postings::+* Beancount metadata::+* Beancount costs::+* Beancount operating currency::+++File: hledger.info,  Node: Beancount account names,  Next: Beancount commodity names,  Up: Beancount output++5.2.5.1 Beancount account names+...............................++Aside from the top-level names, hledger will adjust your account names+to make valid Beancount account names, by capitalising each part,+replacing spaces with '-', replacing other unsupported characters with+'C<HEXBYTES>', prepending 'A' to account name parts which don't begin+with a letter or digit, and appending ':A' to account names which have+only one part.+++File: hledger.info,  Node: Beancount commodity names,  Next: Beancount virtual postings,  Prev: Beancount account names,  Up: Beancount output++5.2.5.2 Beancount commodity names+.................................++hledger will adjust your commodity names to make valid Beancount+commodity/currency names, which must be 2-24 uppercase letters, digits,+or ''', '.', '_', '-', beginning with a letter and ending with a letter+or digit.  hledger will convert known currency symbols to ISO 4217+currency codes, capitalise letters, replace spaces with '-', replace+other unsupported characters with 'C<HEXBYTES>', and prepend or append+'C' if needed.+++File: hledger.info,  Node: Beancount virtual postings,  Next: Beancount metadata,  Prev: Beancount commodity names,  Up: Beancount output++5.2.5.3 Beancount virtual postings+..................................++Beancount doesn't allow virtual postings; if you have any, they will be+omitted from beancount output.+++File: hledger.info,  Node: Beancount metadata,  Next: Beancount costs,  Prev: Beancount virtual postings,  Up: Beancount output++5.2.5.4 Beancount metadata+..........................++hledger tags will be converted to Beancount metadata (except for tags+whose name begins with '_').  Metadata names will be adjusted to be+Beancount-compatible: beginning with a lowercase letter, at least two+characters long, and with unsupported characters encoded.  Metadata+values will use Beancount's string type.++   In hledger, objects can have the same tag repeated with multiple+values.  Eg an 'assets:cash' account might have both 'type:Asset' and+'type:Cash' tags.  For Beancount these will be combined into one, with+the values combined, comma separated.  Eg: 'type: "Asset, Cash"'.+++File: hledger.info,  Node: Beancount costs,  Next: Beancount operating currency,  Prev: Beancount metadata,  Up: Beancount output++5.2.5.5 Beancount costs+.......................++Beancount doesn't allow redundant costs and conversion postings as+hledger does.  If you have any of these, the conversion postings will be+omitted.  Currently we support at most one cost + conversion postings+group per transaction.+++File: hledger.info,  Node: Beancount operating currency,  Prev: Beancount costs,  Up: Beancount output++5.2.5.6 Beancount operating currency+....................................++Declaring an operating currency (or several) improves Beancount and Fava+reports.  Currently hledger will declare each currency used in cost+amounts as an operating currency.  If needed, replace these with your+own declaration, like++option "operating_currency" "USD"+++File: hledger.info,  Node: SQL output,  Next: JSON output,  Prev: Beancount output,  Up: Output format++5.2.6 SQL output+----------------++SQL output is expected to work at least with SQLite, MySQL and Postgres.++   The SQL statements are expected to be executed in the empty database.+If you already have tables created via SQL output of hledger, you would+probably want to either clear data from these (via 'delete' or+'truncate' SQL statements) or 'drop' the tables completely before+import; otherwise your postings would be duplicated.++   For SQLite, it is 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' | ...++   This is not yet much used; feedback is welcome.+++File: hledger.info,  Node: JSON output,  Prev: SQL output,  Up: Output format++5.2.7 JSON output+-----------------++Our JSON is rather large and verbose, since it is a faithful+representation of hledger's internal data types.  To understand its+structure, read the Haskell type definitions, which are mostly in+https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.+hledger-web's OpenAPI specification may also be relevant.++   hledger stores numbers with sometimes up to 255 significant digits.+This is too many digits for most JSON consumers, so in JSON output we+round numbers to at most 10 decimal places.  (We don't limit the number+of integer digits.)  If you find this causing problems, please let us+know.  Related: #1195++   This is not yet much used; feedback is welcome.+++File: hledger.info,  Node: Commodity styles,  Next: Debug output,  Prev: Output format,  Up: Output++5.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 be repeated to set the display style for multiple+commodities/currencies.  Its argument is as described in the commodity+directive.++   In some cases hledger will adjust number formatting to improve their+parseability (such as adding trailing decimal marks when needed).+++File: hledger.info,  Node: Debug output,  Prev: Commodity styles,  Up: Output++5.4 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++   (This option doesn't work in a config file yet.)+++File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top++6 Environment+*************++These environment variables affect hledger:++   *HLEDGER_LESS* If 'less' is your pager, this variable specifies the+'less' options hledger should use.  (Otherwise, 'LESS' + custom options+are used.)++   *LEDGER_FILE* The main journal file to use when not specified with+'-f/--file'.  Default: '$HOME/.hledger.journal'.++   *NO_COLOR* If this environment variable exists (with any value,+including empty), hledger will not use ANSI color codes in terminal+output, unless overridden by an explicit '--color=y' or '--colour=y'+option.+++File: hledger.info,  Node: PART 2 DATA FORMATS,  Next: Journal,  Prev: Environment,  Up: Top++7 PART 2: DATA FORMATS+**********************+++File: hledger.info,  Node: Journal,  Next: CSV,  Prev: PART 2 DATA FORMATS,  Up: Top++8 Journal+*********++hledger's usual data source is a plain text file containing journal+entries in hledger 'journal' format.  If you're looking for a quick+reference, jump ahead to the journal cheatsheet (or use the table of+contents at https://hledger.org/hledger.html).++   This file represents an accounting General Journal.  The '.journal'+file extension is most often used, though not strictly 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 add-ons+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.++   A hledger journal file can contain three kinds of thing: comment+lines, transactions, and/or directives (including periodic transaction+rules and auto posting rules).  Understanding the journal file format+will also give you a good understanding of hledger's data model.  Here's+a quick cheatsheet/overview, followed by detailed descriptions of each+part.++* Menu:++* Journal cheatsheet::+* Comments::+* Transactions::+* Dates::+* Status::+* Code::+* Description::+* Transaction comments::+* Postings::+* Account names::+* Amounts::+* Balance assertions::+* Posting comments::+* Transaction balancing::+* 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: Comments,  Up: Journal++8.1 Journal cheatsheet+======================++# Here is the main syntax of hledger's journal format+# (omitting extra Ledger compatibility syntax).++###############################################################################++# 1. These are comment lines, for notes or temporarily disabling things.+; They begin with # or ;++comment+Or, lines can be enclosed within "comment" / "end comment".+This is a block of +commented lines.+end comment++# Some journal entries can have semicolon comments at end of line  ; like this+# Some of them require 2 or more spaces before the semicolon.++###############################################################################++# 2. Directives customise processing or output in some way.+# You don't need any directives to get started.+# But they can add more error checking, or change how things are displayed.+# They begin with a word, letter, or symbol. +# They are most often placed at the top, before transactions.++account assets             ; Declare valid account names and display order.+account assets:savings     ; A subaccount. This one represents a bank account.+account assets:checking    ; Another. Note, 2+ spaces after the account name.+account assets:receivable  ; Accounting type is inferred from english names,+account passifs            ; or declared with a "type" tag, type:L+account expenses           ; type:X+                           ; A follow-on comment line, indented.+account expenses:rent      ; Expense and revenue categories are also accounts.+                           ; Subaccounts inherit their parent's type.++commodity $0.00         ; Declare valid commodities and their display styles.+commodity 1.000,00 EUR++decimal-mark .          ; The decimal mark used in this file (if ambiguous).++payee Whole Foods       ; Declare a valid payee name.++tag trip                ; Declare a valid tag name.++P 2024-03-01 AAPL $179  ; Declare a market price for AAPL in $ on this date.++include other.journal   ; Include another journal file here.++# Declare a recurring "periodic transaction", for budget/forecast reports+~ monthly  set budget goals  ; <- Note, 2+ spaces before the description.+    (expenses:rent)      $1000+    (expenses:food)       $500++# Declare an auto posting rule, to modify existing transactions in reports+= revenues:consulting+    liabilities:tax:2024:us          *0.25  ; Add a tax liability & expense+    expenses:tax:2024:us            *-0.25  ; for 25% of the revenue.++###############################################################################++# 3. Transactions are what it's all about.+# They are dated events, usually movements of money between 2 or more accounts.+# They begin with a numeric date.+# Here is their basic shape:+#+# DATE DESCRIPTION    ; The transaction's date and optional description.+#   ACCOUNT1  AMOUNT  ; A posting of an amount to/from this account, indented.+#   ACCOUNT2  AMOUNT  ; A second posting, balancing the first.+#   ...               ; More if needed. Amounts must sum to zero.+#                     ; Note, 2+ spaces between account names and amounts.++2024-01-01 opening balances         ; At the start, declare pre-existing balances this way.+    assets:savings          $10000  ; Account names can be anything. lower case is easy to type.+    assets:checking          $1000  ; assets, liabilities, equity, revenues, expenses are common.+    liabilities:credit card  $-500  ; liabilities, equity, revenues balances are usually negative.+    equity:start                    ; One amount can be left blank. $-10500 is inferred here.+                                    ; Some of these accounts we didn't declare above,+                                    ; so -s/--strict would complain.++2024-01-03 ! (12345) pay rent+    ; Additional transaction comment lines, indented.+    ; There can be a ! or * after the date meaning "pending" or "cleared".+    ; There can be a parenthesised (code) after the date/status.+                                    ; Amounts' sign shows direction of flow.+    assets:checking          $-500  ; Minus means removed from this account (credit).+    expenses:rent             $500  ; Plus means added to this account (debit).++; Keeping transactions in date order is optional (but helps error checking).++2024-01-02 Gringott's Bank | withdrawal  ; Description can be PAYEE | NOTE+    assets:bank:gold       -10 gold+    assets:pouch            10 gold++2024-01-02 shopping+    expenses:clothing        1 gold+    expenses:wands           5 gold+    assets:pouch            -6 gold++2024-01-02 receive gift+    revenues:gifts          -3 "Chocolate Frogs"  ; Complex commodity symbols+    assets:pouch             3 "Chocolate Frogs"  ; must be in double quotes.++2024-01-15 buy some shares, in two lots                 ; Cost can be noted.+    assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  means per-unit cost+    assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ means total cost+                      ; ^ Per-lot subaccounts are sometimes useful.+    assets:checking                 $-7++2024-01-15 assert some account balances on this date+    ; Balances can be asserted in any transaction, with =, for extra error checking.+    ; Assertion txns like this one can be made with hledger close --assert --show-costs+    ;+    assets:savings                    $0                   = $10000+    assets:checking                   $0                   =   $493+    assets:bank:gold                   0 gold              =    -10 gold+    assets:pouch                       0 gold              =      4 gold+    assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"+    assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50+    assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4+    liabilities:credit card           $0                   =  $-500++2024-02-01 note some event, or a transaction not yet fully entered, on this date+    ; Postings are not required.++; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).+2024.01.01+2024/1/1+++File: hledger.info,  Node: Comments,  Next: Transactions,  Prev: Journal cheatsheet,  Up: Journal++8.2 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++8.3 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++8.4 Dates+=========++* Menu:++* Simple dates::+* Posting dates::+++File: hledger.info,  Node: Simple dates,  Next: Posting dates,  Up: Dates++8.4.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++8.4.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++8.5 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 (and you can combine these, eg+'-UP' to match all except cleared things).  Or you can use the+'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in+hledger-ui.++   (Note: in Ledger the "unmarked" state is called "uncleared"; in+hledger we renamed it to "unmarked" for semantic clarity.)++   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++8.6 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++8.7 Description+===============++After the date, status mark and/or code fields, the rest of the line (or+until a comment is begun with ';') is the transaction's description.+Here you can describe the transaction (called the "narration" in+traditional bookkeeping), or you can record a payee/payer name, or you+can leave it empty.++   Transaction descriptions show up in print output and in register+reports, and can be listed with the descriptions command.++   You can query by description with 'desc:DESCREGEX', or pivot on+description with '--pivot desc'.++* Menu:++* Payee and note::+++File: hledger.info,  Node: Payee and note,  Up: Description++8.7.1 Payee and note+--------------------++Sometimes people want a dedicated payee/payer field that can be queried+and checked more strictly.  If you want that, you can write a '|' (pipe)+character in the description.  This divides it into a "payee" field on+the left, and a "note" field on the right.  (Either can be empty.)++   You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX',+list their values with the payees and notes commands, or pivot on+'payee' or 'note'.++   Note: in transactions with no '|' character, description, payee, and+note all have the same value.  Once a '|' is added, they become+distinct.  (If you'd like to change this behaviour, please propose it on+the mail list.)++   If you want more strict error checking, you can declare the valid+payee names with payee directives, and then enforce these with hledger+check payees.  (Note: because of the above, for this you'll need to+ensure every transaction description contains a '|' and therefore a+checkable payee name, even if it's empty.)+++File: hledger.info,  Node: Transaction comments,  Next: Postings,  Prev: Description,  Up: Journal++8.8 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++8.9 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.++   If the amount is positive, it is being added to the account; if+negative, it is being removed from the account.++   The posting amounts in a transaction must sum up to zero, indicating+that the inflows and outflows are equal.  We call this a balanced+transaction.  (You can read more about the nitty-gritty details of "sum+up to zero" in Transaction balancing below.)++   As a convenience, you can optionally leave one amount blank; hledger+will infer what it should be so as to balance the transaction.++* Menu:++* Debits and credits::+* The two space delimiter::+++File: hledger.info,  Node: Debits and credits,  Next: The two space delimiter,  Up: Postings++8.9.1 Debits and credits+------------------------++The traditional accounting concepts of debit and credit of course exist+in hledger, but we represent them with numeric sign, as described above.+Positive and negative posting amounts represent debits and credits+respectively.++   You don't need to remember that, but if you would like to - eg for+helping newcomers or for talking with your accountant - here's a handy+mnemonic:++   _'debit / plus / left / short words'_+_'credit / minus / right / longer words'_+++File: hledger.info,  Node: The two space delimiter,  Prev: Debits and credits,  Up: Postings++8.9.2 The two space delimiter+-----------------------------++Be sure to notice the unusual separator between the account name and the+following amount.  Because hledger allows account names with spaces in+them, you must separate the account name and amount (if any) by *two or+more spaces* (or tabs).  It's easy to forget at first.  If you ever see+the amount being treated as part of the account name, you'll know you+probably need to add another space between them.+++File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: Journal++8.10 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: Balance assertions,  Prev: Account names,  Up: Journal++8.11 Amounts+============++After the account name, there is usually an amount.  (Remember: 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::+* Costs::+++File: hledger.info,  Node: Decimal marks,  Next: Digit group marks,  Up: Amounts++8.11.1 Decimal marks+--------------------++A _decimal mark_ can be written as a period or a comma:++1.23+1,23++   Both of these are common in international number formats, so hledger+is not biased towards one or the other.  Because hledger also supports+digit group marks (eg thousands separators), this means that a number+like '1,000' or '1.000' containing just one period or comma is+ambiguous.  In such cases, hledger by default assumes it is a decimal+mark, and will parse both of those as 1.++   To help hledger parse such ambiguous numbers more accurately, if you+use digit group marks, we recommend declaring the decimal mark+explicitly.  The best way is to add a 'decimal-mark' directive at the+top of each data file, like this:++decimal-mark .++   Or you can declare it per commodity with 'commodity' directives,+described below.++   hledger also accepts numbers like '10.' with no digits after the+decimal mark (and will sometimes display numbers that way to+disambiguate them - see Trailing decimal marks).+++File: hledger.info,  Node: Digit group marks,  Next: Commodity,  Prev: Decimal marks,  Up: Amounts++8.11.2 Digit group marks+------------------------++In the integer part of the amount quantity (left of the decimal mark),+groups of digits can optionally be separated by a _digit group mark_ - a+comma or period (whichever is not used as decimal mark), or a space+(several Unicode space variants, like no-break space, are also+accepted).  So these are all valid amounts in a journal file:++     $1,000,000.00+  EUR 2.000.000,00+INR 9,99,99,999.00+      1 000 000.00   ; <- ordinary space  +      1 000 000.00   ; <- no-break space+++File: hledger.info,  Node: Commodity,  Next: Costs,  Prev: Digit group marks,  Up: Amounts++8.11.3 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.++   By default, the format of amounts in the journal influences how+hledger displays them in output.  This is explained in Commodity display+style below.+++File: hledger.info,  Node: Costs,  Prev: Commodity,  Up: Amounts++8.11.4 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.+++File: hledger.info,  Node: Balance assertions,  Next: Posting comments,  Prev: Amounts,  Up: Journal++8.12 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 costs::+* Assertions and commodities::+* Assertions and subaccounts::+* Assertions and status::+* 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++8.12.1 Assertions and ordering+------------------------------++hledger calculates and checks an account's balance assertions in date+order (and when there are multiple assertions on the same day, in parse+order).  Note this is different from Ledger, which checks assertions+always in parse order, ignoring dates.++   This means in hledger you can freely reorder transactions, postings,+or files, and balance assertions will usually keep working.  The+exception is when you reorder multiple postings on the same day, to the+same account, which have balance assertions; those will likely need+updating.+++File: hledger.info,  Node: Assertions and multiple included files,  Next: Assertions and multiple -f files,  Prev: Assertions and ordering,  Up: Balance assertions++8.12.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 costs,  Prev: Assertions and multiple included files,  Up: Balance assertions++8.12.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 costs,  Next: Assertions and commodities,  Prev: Assertions and multiple -f files,  Up: Balance assertions++8.12.4 Assertions and costs+---------------------------++Balance assertions ignore costs, and should normally be written without+one:++2019/1/1+  (a)     $1 @ €1 = $1++   We do allow costs to be written in balance assertion amounts,+however, and print shows them, but 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+costs), and because balance _assignments_ do use costs (see below).+++File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and subaccounts,  Prev: Assertions and costs,  Up: Balance assertions++8.12.5 Assertions and commodities+---------------------------------++The balance assertions described so far are "*single commodity balance+assertions*": they assert and check the balance in one commodity,+ignoring any others that may be present.  This is how balance assertions+work in Ledger also.++   If an account contains multiple commodities, you can assert their+balances by writing multiple postings with balance assertions, one for+each commodity:++2013/1/1+  usd   $-1+  eur   €-1+  both++2013/1/2+  both    0 = $1+  both    0 = €1++   In hledger you can make a stronger "*sole commodity balance+assertion*" by writing two equals signs ('== EXPECTEDBALANCE').  This+also asserts that there are no other commodities in the account besides+the asserted one (or at least, that their current balance is zero):++2013/1/1+  usd   $-1  == $-1  ; these sole commodity assertions succeed+  eur   €-1  == €-1+  both      ;==  $1  ; this one would fail because 'both' contains $ and €++   It's less easy to make a "*sole commodities balance assertion*" (note+the plural) - ie, asserting that an account contains two or more+specified commodities and no others.  It can be done by++  1. isolating each commodity in a subaccount, and asserting those+  2. and also asserting there are no commodities in the parent account+     itself:++2013/1/1+  usd       $-1+  eur       €-1+  both        0 == 0   ; nothing up my sleeve+  both:usd   $1 == $1  ; a dollar here+  both:eur   €1 == €1  ; a euro there+++File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and status,  Prev: Assertions and commodities,  Up: Balance assertions++8.12.6 Assertions and subaccounts+---------------------------------++All of the balance assertions above (both '=' and '==') are+"*subaccount-exclusive balance assertions*"; they ignore any balances+that exist in deeper subaccounts.++   In hledger you can make "*subaccount-inclusive balance assertions*"+by adding a star after the equals ('=*' or '==*'):++2019/1/1+  equity:start+  assets:checking  $10+  assets:savings   $10+  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else+++File: hledger.info,  Node: Assertions and status,  Next: Assertions and virtual postings,  Prev: Assertions and subaccounts,  Up: Balance assertions++8.12.7 Assertions and status+----------------------------++Balance assertions always consider postings of all statuses (unmarked,+pending, or cleared); they are not affected by the '-U'/'--unmarked' /+'-P'/'--pending' / '-C'/'--cleared' flags or the 'status:' query.+++File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and status,  Up: Balance assertions++8.12.8 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++8.12.9 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++8.12.10 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: Transaction balancing,  Prev: Balance assertions,  Up: Journal++8.13 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: Transaction balancing,  Next: Tags,  Prev: Posting comments,  Up: Journal++8.14 Transaction balancing+==========================++How exactly does hledger decide when a transaction is balanced ?  The+general goal is that if you look at the journal entry and calculate the+amounts' sum perfectly with pencil and paper, hledger should agree with+you.++   Real world transactions, especially for investments or+cryptocurrencies, often involve imprecise costs, complex decimals,+and/or infinitely-recurring decimals, which are difficult or+inconvenient to handle on a computer.  So to be a practical accounting+system, hledger allows some imprecision when checking transaction+balancedness.  The question is, how much imprecision should be allowed ?++   hledger currently decides it based on the commodity display styles:+if the postings' sum would appear to be zero when displayed with the+standard display precisions, the transaction is considered balanced.++   Or equivalently: if the journal entry is displayed with amounts+rounded to the standard display precisions (with 'hledger print+--round=hard'), and a human with pencil and paper would agree that those+displayed amounts add up to zero, the transaction is considered+balanced.++   This has some advantages: it is fairly intuitive, general not+hard-coded, yet configurable when needed.  On the downside it means that+transaction balancedness is related to commodity display precisions, so+eg when using '-c/--commodity-style' to display things with more than+usual precision, you might need to fix some of your journal entries (ie,+add decimal digits to make them balance more precisely).++   Other PTA tools (Ledger, Beancount..)  have their own ways of doing+it.  Possible improvements are discussed at #1964.++   Note: if you have multiple journal files, and are relying on+commodity directives to make imprecise journal entries balance, the+directives' placement might be important - see 'commodity' directive.+++File: hledger.info,  Node: Tags,  Next: Directives,  Prev: Transaction balancing,  Up: Journal++8.15 Tags+=========++Tags are a way to add extra labels or data fields to transactions,+postings, or accounts.  They are usually a word or hyphenated word,+immediately followed by a full colon, written within the comment of a+transaction, a posting, or an 'account' directive.  (Yes, storing data+in comments is slightly weird!)++   You can write each tag on its own comment line, or multiple tags on+one line, separated by commas.  Tags can also have a value, which is any+text after the colon until the next comma or end of line, excluding+surrounding whitespace.  (hledger tag values can't contain commas.)  If+the same tag name appears multiple times in a comment, each name:value+pair is preserved.++   An example: in this journal there are six tags, one of them with a+value:++account assets:checking         ; accounttag:+account expenses:food++2017/1/16 bought groceries      ; transactiontag:+    ; transactiontag2:+    assets:checking        $-1+     ; posting-tag-1:, (belongs to the posting above)+    expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value++* Menu:++* Querying with tags::+* Displaying tags::+* When to use tags ?::+* Tag names::+* Special tags::+++File: hledger.info,  Node: Querying with tags,  Next: Displaying tags,  Up: Tags++8.15.1 Querying with tags+-------------------------++Tags are most often used to select a subset of data; you can match+tagged things by tag name and or tag value with a 'tag:' query.  (See+queries below.)++   When querying for tag names or values, note that postings inherit+tags from their transaction and from their account, and transactions+acquire tags from their postings.  So in the example above, - the+assets:checking posting effectively has four tags (one of its own, one+from the account, two from the transaction) - the expenses:food posting+effectively has four tags (two of its own, two from the transaction) -+the transaction effectively has all six tags (two of its own, and two+from each posting)+++File: hledger.info,  Node: Displaying tags,  Next: When to use tags ?,  Prev: Querying with tags,  Up: Tags++8.15.2 Displaying tags+----------------------++You can use the 'tags' command to list tag names or values.++   The 'print' command also shows tags.++   You can use -pivot to display tag values in other reports, in various+ways (eg appended to account names, like pseudo subaccounts).+++File: hledger.info,  Node: When to use tags ?,  Next: Tag names,  Prev: Displaying tags,  Up: Tags++8.15.3 When to use tags ?+-------------------------++Tags provide more dimensions of categorisation, complementing accounts+and transaction descriptions.  When to use each of these is somewhat a+matter of taste.  Accounts have the most built-in support, and regex+queries on descriptions are also quite powerful.  So you may not need+tags at all.  But if you want to track multiple cross-cutting+categories, they can be a good fit.  For example, you could tag+trip-related transactions with 'trip: YEAR:PLACE', without disturbing+your usual account categories.+++File: hledger.info,  Node: Tag names,  Next: Special tags,  Prev: When to use tags ?,  Up: Tags++8.15.4 Tag names+----------------++What is allowed in a tag name ?  Currently, most non-whitespace+characters.  Eg '😀:' is a valid tag.++   For extra error checking, you can declare valid tag names with the+'tag' directive, and then enforce these with the 'check' command.++   But note that tags are detected quite loosely at present, sometimes+where you didn't intend them.  Eg '; see https://foo.com' contains a+'https' tag with value '//foo.com'.+++File: hledger.info,  Node: Special tags,  Prev: Tag names,  Up: Tags++8.15.5 Special tags+-------------------++Some tag names have special significance to hledger.  They are explained+elsewhere, but here's a quick reference:++ type                   -- declares an account's type+ date                   -- overrides a posting's date+ date2                  -- overrides a posting's secondary date+ assert                 -- appears on txns generated by close --assert+ retain                 -- appears on txns generated by close --retain+ start                  -- appears on txns generated by close --migrate/--close/--open/--assign+ t                      -- appears on postings generated from timedot letters++ generated-transaction  -- appears on txns generated by a periodic rule+ modified-transaction   -- appears on txns which have had auto postings added+ generated-posting      -- appears on generated postings+ cost-posting           -- appears on postings which have (or could have) a cost,+                           and which have equivalent conversion postings in the transaction+ conversion-posting     -- appears on postings which are to a V/Conversion account+                           and which have an equivalent cost posting in the transaction++   The second group above (generated-transaction, etc.)  are normally+hidden, with a '_' prefix added.  This means 'print' doesn't show them+by default; but you can still use them in queries.  You can add the+'--verbose-tags' flag to make them visible, which can be useful for+troubleshooting.+++File: hledger.info,  Node: Directives,  Next: account directive,  Prev: Tags,  Up: Journal++8.16 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++8.16.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++8.16.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,N,Y,Y+     all amounts in all files 2.  the display style for all amounts+     of this commodity 3.  the decimal mark for parsing amounts of+     this commodity, in the rest of this file and its children, if+     there is no 'decimal-mark' directive 4.  the precision to use+     for balanced-transaction checking in this commodity, in this+     file and its children.  Takes precedence over 'D'.+     Subdirectives: 'format' (ignored).  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++8.17 '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.+   * They can store additional account information as comments, or as+     tags which can be used to filter or pivot reports.+   * They can restrict which accounts may be posted to by transactions,+     eg in strict mode, which helps prevent errors.+   * They influence account display order in reports, allowing+     non-alphabetic sorting (eg Revenues to appear above Expenses).+   * They can help hledger know your accounts' types (asset, liability,+     equity, revenue, expense), enabling reports like balancesheet and+     incomestatement.+   * They help with account name completion (in hledger add,+     hledger-web, hledger-iadd, ledger-mode, etc.)++   They are written as the word 'account' followed by a hledger-style+account name.  Eg:++account assets:bank:checking++   Ledger-style indented subdirectives are also accepted, but ignored:++account assets:bank:checking+  format subdirective  ; currently ignored++* Menu:++* Account comments::+* Account error checking::+* Account display order::+* Account types::+++File: hledger.info,  Node: Account comments,  Next: Account error checking,  Up: account directive++8.17.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 error checking,  Next: Account display order,  Prev: Account comments,  Up: account directive++8.17.2 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, or when you+run 'hledger check accounts', 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.+   * If you use the -infer-equity flag, you will also need declarations+     for the account names it generates.+++File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive++8.17.3 Account display order+----------------------------++Account directives also cause hledger to display accounts in a+particular order, not just alphabetically.  Eg, here is a conventional+ordering for the top-level accounts:++account assets+account liabilities+account equity+account revenues+account expenses++   Now hledger displays them in that order:++$ hledger accounts+assets+liabilities+equity+revenues+expenses++   If there are undeclared accounts, those will be displayed last, in+alphabetical order.++   Sorting is done within each group of sibling accounts, at each level+of the account tree.  Eg, a declaration like 'account parent:child'+influences 'child''s position among its siblings.++   Note, it does not affect 'parent''s position; for that, you need an+'account parent' declaration.++   Sibling accounts are always displayed together; hledger won't display+'x:y' in between 'a:b' and 'a:c'.++   An account directive both declares an account as a valid posting+target, and declares its display order; you can't easily do one without+the other.+++File: hledger.info,  Node: Account types,  Prev: Account display order,  Up: account directive++8.17.4 Account types+--------------------++hledger knows that accounts come in several types: assets, liabilities,+expenses and so on.  This enables easy reports like balancesheet and+incomestatement, and filtering by account type with the 'type:' query.++   As a convenience, hledger will detect these account types+automatically if you are using common english-language top-level account+names (described below).  But it's more robust to declare accounts'+types explicitly, by adding 'type:' tags to their account directives.+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).)++   Subaccounts inherit their parent's type, or they can override it.+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++8.18 '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++8.18.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++8.18.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++8.18.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++8.18.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++8.18.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++8.18.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++8.18.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 --types -1 --alias assets=bassetts+++File: hledger.info,  Node: commodity directive,  Next: decimal-mark directive,  Prev: alias directive,  Up: Journal++8.19 '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 how all amounts in this commodity should be displayed,+     eg how many decimals to show.  See Commodity display style above.++  3. (If no 'decimal-mark' directive is in effect:) It sets the decimal+     mark to expect (period or comma) when parsing amounts in this+     commodity, in this file and files it includes, from the directive+     until end of current file.  See Decimal marks above.++  4. It declares the precision with which this commodity's amounts+     should be compared when checking for balanced transactions,+     anywhere in this file and files it includes, until end of current+     file.++   Declaring commodities solves several common parsing/display problems,+so we recommend it.++   Note that effects 3 and 4 above end at the end of the directive's+file, and will not affect sibling or parent files.  So if you are+relying on them (especially 4) and using multiple files, placing your+commodity directives in a top-level parent file might be important.  Or,+keep your decimal marks unambiguous and your entries well balanced and+precise.++   (Related: #793)++* Menu:++* Commodity directive syntax::+* Commodity error checking::+++File: hledger.info,  Node: Commodity directive syntax,  Next: Commodity error checking,  Up: commodity directive++8.19.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+the number's 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++8.19.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++8.20 '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++8.21 '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++8.22 '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++8.23 '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++8.24 '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; 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++8.25 Periodic transactions+==========================++The '~' directive declares a "periodic rule" which generates temporary+extra transactions, usually recurring at some interval, when hledger is+run with the '--forecast' flag.  These "forecast transactions" are+useful for forecasting future activity.  They exist only for the+duration of the report, and only when '--forecast' is used; they are not+saved in the journal file by hledger.++   Periodic rules also have a second use: with the '--budget' flag they+set budget goals for budgeting.++   Periodic rules can be a little tricky, so before you use them, read+this whole section, or at least the following 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++8.25.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++8.25.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++8.25.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++8.26 Auto postings+==================++The '=' directive declares an "auto posting rule", which adds extra+postings to existing transactions.  (Remember, postings are the account+name & amount lines below a transaction's date & description.)++   In the journal, an auto posting rule looks quite like a transaction,+but instead of date and description it has '=' (mnemonic: "match") and a+query, like this:++= QUERY+    ACCOUNT    AMOUNT+    ...++   Queries are just like command line queries; an account name substring+is most common.  Query terms containing spaces should be enclosed in+single or double quotes.++   Each '=' rule works like this: when hledger is run with the '--auto'+flag, wherever the QUERY matches a posting in the journal, the rule's+postings are added to that transaction, immediately below the matched+posting.  Note these generated postings are temporary, existing only for+the duration of the report, and only when '--auto' is used; they are not+saved in the journal file by hledger.++   Generated postings' amounts can depend on the matched posting's+amount.  So auto postings can be useful for, eg, adding tax postings+with a standard percentage.  AMOUNT can be:++   * a number with no commodity symbol, like '2'.  The matched posting's+     commodity symbol will be added to this.++   * a normal amount with a commodity symbol, like '$2'.  This will be+     used as-is.++   * an asterisk followed by a number, like '*2'.  This will multiply+     the matched posting's amount (and total price, if any) by the+     number.++   * an asterisk followed by an amount with commodity symbol, like+     '*$2'.  This multiplies and also replaces the commodity symbol with+     this new one.++   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++   Note that depending fully on generated data such as this has some+drawbacks - it's less portable, less future-proof, less auditable by+others, and less robust (eg your balance assertions will depend on+whether you use or don't use '--auto').  An alternative is to use auto+postings in "one time" fashion - use them to help build a complex+journal entry, view it with 'hledger print --auto', and then copy that+output into the journal file to make it permanent.++* Menu:++* Auto postings and multiple files::+* 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 multiple files,  Next: Auto postings and dates,  Up: Auto postings++8.26.1 Auto postings and multiple files+---------------------------------------++An auto posting rule can affect any transaction in the current file, or+in any parent file or child file.  Note, currently it will not affect+sibling files (when multiple '-f'/'--file' are used - see #1212).+++File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Prev: Auto postings and multiple files,  Up: Auto postings++8.26.2 Auto postings and dates+------------------------------++A posting date (or secondary date) in the matched posting, or (taking+precedence) a posting date in the auto posting rule itself, will also be+used in the generated posting.+++File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings++8.26.3 Auto postings and transaction balancing / inferred amounts /+-------------------------------------------------------------------++balance assertions Currently, auto postings are added:++   * after missing amounts are inferred, and transactions are checked+     for balancedness,+   * but before balance assertions are checked.++   Note this means that journal entries must be balanced both before and+after auto postings are added.  This changed in hledger 1.12+; see #893+for background.++   This also means that you cannot have more than one auto-posting with+a missing amount applied to a given transaction, as it will be unable to+infer amounts.+++File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings++8.26.4 Auto posting tags+------------------------++Automated postings will have some extra tags:++   * 'generated-posting:= QUERY' - shows this was generated by an auto+     posting rule, and the query+   * '_generated-posting:= QUERY' - a hidden tag, which does not appear+     in hledger's output.  This can be used to match postings generated+     "just now", rather than generated in the past and saved to the+     journal.++   Also, any transaction that has been changed by auto posting rules+will have these tags added:++   * 'modified:' - this transaction was modified+   * '_modified:' - a hidden tag not appearing in the comment; this+     transaction was modified "just now".+++File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings++8.26.5 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++8.27 Other syntax+=================++hledger journal format supports quite a few other features, mainly to+make interoperating with or converting from Ledger easier.  Note some of+the features below are powerful and can be useful in special cases, but+in general, features in this section are considered less important or+even not recommended for most users.  Downsides are mentioned to help+you decide if you want to use them.++* Menu:++* Balance assignments::+* Bracketed posting dates::+* D directive::+* apply account directive::+* Y directive::+* Secondary dates::+* Star comments::+* Valuation expressions::+* Virtual postings::+* Other Ledger directives::+* Other cost/lot notations::+++File: hledger.info,  Node: Balance assignments,  Next: Bracketed posting dates,  Up: Other syntax++8.27.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 costs::+* Balance assignments and multiple files::+++File: hledger.info,  Node: Balance assignments and costs,  Next: Balance assignments and multiple files,  Up: Balance assignments++8.27.1.1 Balance assignments and costs+......................................++A cost in a balance assignment will cause the calculated amount to have+that cost 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 costs,  Up: Balance assignments++8.27.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++8.27.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++8.27.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 current file.++   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++8.27.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++8.27.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++8.27.6 Secondary dates+----------------------++A secondary date is written after the primary date, following an equals+sign: 'DATE1=DATE2'.  If the year is omitted, the primary date's year is+assumed.  When running reports, the primary (left side) date is used by+default, but with the '--date2' flag ('--aux-date' or'--effective' also+work, for Ledger users), the secondary (right side) date will be used+instead.++   The meaning of secondary dates is up to you.  Eg it could be "primary+is the bank's clearing date, secondary is the date the transaction was+initiated, if different".++   In practice, this feature usually adds confusion:++   * You have to remember the primary and secondary dates' meaning, and+     follow that consistently.+   * It splits your bookkeeping into two modes, and you have to remember+     which mode is appropriate for a given report.+   * Usually your balance assertions will work with only one of these+     modes.+   * It makes your financial data more complicated, less portable, and+     less clear in an audit.+   * It interacts with every feature, creating an ongoing cost for+     implementors.+   * It distracts new users and supporters.+   * Posting dates are simpler and work better.++   So secondary dates are officially deprecated in hledger, remaining+only as a Ledger compatibility aid; we recommend using posting dates+instead.+++File: hledger.info,  Node: Star comments,  Next: Valuation expressions,  Prev: Secondary dates,  Up: Other syntax++8.27.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++8.27.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++8.27.9 Virtual postings+-----------------------++A posting with parentheses around the account name, like '(some:account)+10', is called an _unbalanced virtual posting_.  These 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,  Next: Other cost/lot notations,  Prev: Virtual postings,  Up: Other syntax++8.27.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: Other cost/lot notations,  Prev: Other Ledger directives,  Up: Other syntax++8.27.11 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 that 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".++   * '{=UNITCOST}' and '{{=TOTALCOST}}' (fixed price)+        * when buying, means "this cost is also the fixed value, 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 '@ ...', selects an existing lot+          by its cost basis.  Does not check if that lot is present.++   * '[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+   * supports '@' and '@@'+   * treats '(@)' and '(@@)' as synonyms for '@' and '@@'+   * and ignores the rest.  (This can break transaction balancing.)++   *Beancount* has simpler notation and different behaviour:++   * '@ UNITCOST' and '@@ TOTALCOST'+        * expresses a cost without creating a lot, as in hledger+        * when buying (acquiring) or selling (disposing of) a lot, and+          combined with '{...}': is not used except to document the+          cost/selling price++   * '{UNITCOST}' and '{{TOTALCOST}}'+        * when buying, expresses the cost for transaction balancing, and+          also creates a lot with this cost basis attached+        * when selling,+             * 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++   * '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, "LABEL"}',+     '{UNITCOST, YYYY-MM-DD, "LABEL"}'+        * when selling, other combinations of date/cost/label, like the+          above, are accepted for selecting the lot.++   Currently, hledger++   * supports '@' and '@@'+   * accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation, but ignores it+   * and rejects the rest.+++File: hledger.info,  Node: CSV,  Next: Timeclock,  Prev: Journal,  Up: Top++9 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 expects this rules file to be named like the CSV+file, with an extra '.rules' extension added, 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' option.++   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::+* encoding::+* 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++9.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+*'encoding'*             optionally declare which text encoding the+                         data has+*'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: encoding,  Prev: CSV rules cheatsheet,  Up: CSV++9.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: encoding,  Next: separator,  Prev: source,  Up: CSV++9.3 'encoding'+==============++encoding ENCODING++   hledger normally expects non-ascii text to be UTF8-encoded.  If you+need to read CSV files which have some other encoding, you can do it by+adding 'encoding ENCODING' to your CSV rules.  Eg: 'encoding ISO88591'.++   The following encodings are supported (these names are+case-insensitive, and can be written with inner spaces or hyphens if you+prefer): ASCII, UTF8, UTF16, UTF32, ISO88591, ISO88592, ISO88593,+ISO88594, ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910,+ISO885911, ISO885913, ISO885914, ISO885915, ISO885916, CP1250, CP1251,+CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U,+GB18030, MacOSRoman, JISX0201, JISX0208, ISO2022JP, ShiftJIS, CP437,+CP737, CP775, CP850, CP852, CP855, CP857, CP860, CP861, CP862, CP863,+CP864, CP865, CP866, CP869, CP874, CP932.+++File: hledger.info,  Node: separator,  Next: skip,  Prev: encoding,  Up: CSV++9.4 '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++9.5 '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++9.6 '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++9.7 '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++9.8 '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++9.9 '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++9.10 'decimal-mark'+===================++decimal-mark .++   or:++decimal-mark ,++   hledger automatically accepts either period or comma as a decimal+mark when parsing numbers (cf Amounts).  However if any numbers in the+CSV contain digit group marks, such as thousand-separating commas, you+should declare the decimal mark explicitly with this rule, to avoid+misparsed numbers.+++File: hledger.info,  Node: fields list,  Next: Field assignment,  Prev: decimal-mark,  Up: CSV++9.11 '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++9.12 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++9.13 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++9.13.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++9.13.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++9.13.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++9.13.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++9.13.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++9.13.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.++   Posting comments can also contain a posting date.  A secondary date,+or a year-less date, will be ignored.+++File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names++9.13.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++9.13.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++9.13.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++9.13.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 the Working with CSV tips below for more about setting amounts+and currency.+++File: hledger.info,  Node: if block,  Next: Matchers,  Prev: Field names,  Up: CSV++9.14 '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++9.15 Matchers+=============++There are two kinds of matcher:++  1. A whole record matcher is simplest: it is just a word, single-line+     text fragment, or other regular expression, which hledger will try+     to match case-insensitively anywhere within the CSV record.+     Eg: 'whole foods'.++  2. A field matcher has a percent-prefixed CSV field number or name+     before the pattern.+     Eg: '%3 whole foods' or '%description whole foods'.+     hledger will try to match the pattern just within the named CSV+     field.++   When using these, there's two things to be aware of:++  1. Whole record matchers don't see the exact original record; they see+     a reconstruction of it, in which values are comma-separated, and+     quotes enclosing values and whitespace outside those quotes are+     removed.+     Eg when reading an SSV record like: '2023-01-01 ; "Acme, Inc. " ;+     1,000'+     the whole record matcher sees instead: '2023-01-01,Acme, Inc.+     ,1,000'++  2. Field matchers expect either a CSV field number, or a CSV field+     name declared with 'fields'.  (Don't use a hledger field name here,+     unless it is also a CSV field name.)  A non-CSV field name will+     cause the matcher to match against '""' (the empty string), and+     does not raise an error, allowing easier reuse of common rules with+     different CSV files.++   You can also prefix a matcher with '!' (and optional space) to negate+it.  Eg '! whole foods', '! %3 whole foods', '!%description whole foods'+will match if "whole foods" is NOT present.  _Added in 1.32._++   The pattern 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 with it, see "Regular+expressions" in the hledger manual+(https://hledger.org/hledger.html#regular-expressions).++* Menu:++* Multiple matchers::+* Match groups::+++File: hledger.info,  Node: Multiple matchers,  Next: Match groups,  Up: Matchers++9.15.1 Multiple matchers+------------------------++When an if block has multiple matchers, each on its own line,++   * By default they are OR'd (any of them can match).+   * Matcher lines beginning with '&' (or '&&', _since 1.42_) are AND'ed+     with the matcher above (all in the AND'ed group must match).+   * Matcher lines beginning with '& !' (_since 1.41_, or '&& !', _since+     1.42_) are first negated and then AND'ed with the matcher above.++   You can also combine multiple matchers one the same line separated by+'&&' (AND) or '&& !' (AND NOT). Eg '%description amazon && %date+2025-01-01' will match only when the description field contains "amazon"+and the date field contains "2025-01-01".  _Added in 1.42._+++File: hledger.info,  Node: Match groups,  Prev: Multiple matchers,  Up: Matchers++9.15.2 Match groups+-------------------++_Added in 1.32_++   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++9.16 '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 && MATCHERC,VALUE1,VALUE2,...  (*since 1.42*)+; Comment line that explains MATCHERD+MATCHERD,VALUE1,VALUE2,...+<empty line>++   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).  You can use the+comment lines in the table body.  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+lines with matchers; whenever a line with matchers succeeds, assign all+of the values on that line to the corresponding hledger fields; If+multiple lines match, later lines will override fields assigned by the+earlier ones - just like the sequence of 'if' blocks would behave.++   If table presented above is equivalent to this sequence of if blocks:++if MATCHERA+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++if MATCHERB && MATCHERC+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++; Comment line which explains MATCHERD+if MATCHERD+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++   Example:++if,account2,comment+atm transaction fee,expenses:business:banking,deductible? check it+%description groceries,expenses:groceries,+;; Comment line that desribes why this particular date is special+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++9.17 '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++9.18 '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++9.19 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++9.19.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++9.19.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++9.19.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++9.19.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++9.19.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 specify a rules file with '--rules', 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++9.19.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++9.19.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++9.19.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++9.19.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++9.19.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++9.19.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++9.19.12 Amount decimal places+-----------------------------++When you are reading CSV data, eg with a command like 'hledger -f+foo.csv print', hledger will infer each commodity's decimal precision+(and other commodity display styles) from the amounts - much as when+reading a journal file without 'commodity' directives (see the link).++   Note, the commodity styles are not inferred from the numbers in the+original CSV data; rather, they are inferred from the amounts generated+by the CSV rules.++   When you are importing CSV data with the 'import' command, eg+'hledger import foo.csv', there's another step: 'import' tries to make+the new entries conform to the journal's existing styles.  So for each+commodity - let's say it's EUR - 'import' will choose:++  1. the style declared for EUR by a 'commodity' directive in the+     journal+  2. otherwise, the style inferred from EUR amounts in the journal+  3. otherwise, the style inferred from EUR amounts generated by the CSV+     rules.++   TLDR: if 'import' is not generating the precisions or styles you+want, add a 'commodity' directive to specify them.+++File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Working with CSV++9.19.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++9.19.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++9.19.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++9.20 CSV rules examples+=======================++* Menu:++* Bank of Ireland::+* Coinbase::+* Amazon::+* Paypal::+++File: hledger.info,  Node: Bank of Ireland,  Next: Coinbase,  Up: CSV rules examples++9.20.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++9.20.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++9.20.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++9.20.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++10 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 these shell aliases at the command line:++     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 Emacs's built-in timeclock.el, or the extended timeclock-x.el,+     and perhaps the extras in ledgerutils.el++   * 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++11 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.++        * _Added in 1.32_ 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.++   Timedot files don't support directives like journal files.  So a+common pattern is to have a main journal file (eg 'time.journal') that+contains any needed directives, and then includes the timedot file+('include time.timedot').++* Menu:++* Timedot examples::+++File: hledger.info,  Node: Timedot examples,  Up: Timedot++11.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: Time periods,  Prev: Timedot,  Up: Top++12 PART 3: REPORTING CONCEPTS+*****************************+++File: hledger.info,  Node: Time periods,  Next: Depth,  Prev: PART 3 REPORTING CONCEPTS,  Up: Top++13 Time periods+***************++* Menu:++* Report start & end date::+* Smart dates::+* Report intervals::+* Date adjustments::+* Period headings::+* Period expressions::+++File: hledger.info,  Node: Report start & end date,  Next: Smart dates,  Up: Time periods++13.1 Report start & end date+============================++Most hledger reports will by default show the full time period+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 period, such as the current+month.  You can specify a start and/or end date with the '-b/--begin',+'-e/--end', or '-p/--period' options, or a 'date:' query argument,+described below.  All of these accept the smart date syntax, also+described below.++   End dates are exclusive; specify the day after the last day you want+to see in the report.++   When dates are specified by multiple options, the last (right-most)+option wins.  And when 'date:' queries and date options are combined,+the report period will be their intersection.++   Examples:++'-b 2016/3/17'++     beginning on St.  Patrick's day 2016+'-e 12/1'++     ending at the start of December 1st in the current year+'-p 'this month''++     during the current month+'-p thismonth'++     same as above, spaces are optional+'-b 2023'++     beginning on the first day of 2023+'date:2023..' or 'date:2023-'++     same as above++   '-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020' :+during January 2020 (the smallest common period, with the -p overriding+-b and -e)+++File: hledger.info,  Node: Smart dates,  Next: Report intervals,  Prev: Report start & end date,  Up: Time periods++13.2 Smart dates+================++In hledger's user interfaces (though not in the journal file), you can+optionally use "smart date" syntax.  Smart dates can be written with+english words, can be relative, and can have parts omitted.  Missing+parts are inferred as 1, when needed.  Smart dates can be interpreted as+dates or periods depending on context.++   Examples:++   '2004-01-01', '2004/10/1', '2004.9.1', '20240504' :+Exact dates.  The year must have at least four digits, the month must be+1-12, the day must be 1-31, the separator can be '-' or '/' or '.' or+nothing.++'2004-10'++     start of month+'2004'++     start of year+'10/1' or 'oct' or 'october'++     October 1st in current year+'21'++     21st day in current month+'yesterday, today, tomorrow'++     -1, 0, 1 days from today+'last/this/next day/week/month/quarter/year'++     -1, 0, 1 periods from the current period+'in n days/weeks/months/quarters/years'++     n periods from the current period+'n days/weeks/months/quarters/years ahead'++     n periods from the current period+'n days/weeks/months/quarters/years ago'++     -n periods from the current period+'20181201'++     8 digit YYYYMMDD with valid year month and day+'201812'++     6 digit YYYYMM with valid year and month++   Dates with no separators are allowed but might give surprising+results if mistyped:++   * '20181301' (YYYYMMDD with an invalid month) is parsed as an+     eight-digit year+   * '20181232' (YYYYMMDD with an invalid day) gives a parse error+   * '201801012' (a valid YYYYMMDD followed by additional digits) gives+     a parse error++   The meaning of relative dates depends on today's date.  If you need+to test or reproduce old reports, you can use the '--today' option to+override that.  (Except for periodic transaction rules, which are not+affected by '--today'.)+++File: hledger.info,  Node: Report intervals,  Next: Date adjustments,  Prev: Smart dates,  Up: Time periods++13.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 adjustments,  Next: Period headings,  Prev: Report intervals,  Up: Time periods++13.4 Date adjustments+=====================++* Menu:++* Start date adjustment::+* End date adjustment::+++File: hledger.info,  Node: Start date adjustment,  Next: End date adjustment,  Up: Date adjustments++13.4.1 Start date adjustment+----------------------------++If you let hledger infer a report's start date, it will adjust the date+to the previous natural boundary of the report interval, for convenient+periodic reports.  (If you don't want that, specify a start date.)++   For example, if the journal's first transaction is on january 10th,++   * 'hledger register' (no report interval) will start the report on+     january 10th.+   * 'hledger register --monthly' will start the report on the previous+     month boundary, january 1st.+   * 'hledger register --monthly --begin 1/5' will start the report on+     january 5th [1].++   Also if you are generating transactions or budget goals with periodic+transaction rules, their start date may be adjusted in a similar way (in+certain situations).+++File: hledger.info,  Node: End date adjustment,  Prev: Start date adjustment,  Up: Date adjustments++13.4.2 End date adjustment+--------------------------++A report's end date is always adjusted to include a whole number of+intervals, so that the last subperiod has the same length as the others.++   For example, if the journal's last transaction is on february 20th,++   * 'hledger register' will end the report on february 20th.+   * 'hledger register --monthly' will end the report at the end of+     february.+   * 'hledger register --monthly --end 2/14' also will end the report at+     the end of february.+   * 'hledger register --monthly --begin 1/5 --end 2/14' will end the+     report on march 4th [1].++   [1] Since hledger 1.29.+++File: hledger.info,  Node: Period headings,  Next: Period expressions,  Prev: Date adjustments,  Up: Time periods++13.5 Period headings+====================++With non-standard subperiods, hledger will show "STARTDATE..ENDDATE"+headings.  With standard subperiods (ie, starting on a natural interval+boundary), you'll see more compact headings, which are usually+preferable.  (Though month names will be in english, currently.)++   So if you are specifying a start date and you want compact headings:+choose a start of year for yearly reports, a start of quarter for+quarterly reports, a start of month for monthly reports, etc.+(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start+of year, or '2024-04' or '202404' or 'Apr' for a start of month or+quarter.)++   For weekly reports, choose a date that's a Monday.  (You can try+different dates until you see the short headings, or write eg '-b '3+weeks ago''.)+++File: hledger.info,  Node: Period expressions,  Prev: Period headings,  Up: Time periods++13.6 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++13.6.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++13.6.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]' ('31st day' will be adjusted to each+     month's last day)+   * 'every Nth WEEKDAYNAME [of month]'++   Yearly on a custom month and 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++13.6.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++14 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.++   In place of a single number which limits the depth for all accounts,+you can also provide separate depth limits for different accounts using+regular expressions _(since 1.41)_.++   For example, '--depth assets=2' (or, equivalently: 'depth:assets=2')+will collapse accounts matching the regular expression 'assets' to depth+2.  So 'assets:bank:savings' would be collapsed to 'assets:bank', while+'liabilities:bank:credit card' would not be affected.  This can be+combined with a flat depth to collapse other accounts not matching the+regular expression, so '--depth assets=2 --depth 1' would collapse+'assets:bank:savings' to 'assets:bank' and 'liabilities:bank:credit+card' to 'liabilities'.++   You can supply multiple depth arguments and they will all be applied,+so '--depth assets=2 --depth liabilities=3 --depth 1' would collapse:++   * accounts matching 'assets' to depth 2,+   * accounts matching 'liabilities' to depth 3,+   * all other accounts to depth 1.++   If an account is matched by more than one regular expression depth+argument then the more specific one will used.  For example, if '--depth+assets=1 --depth assets:bank:savings=2' is provided, then+'assets:bank:savings' will be collapsed to depth 2 rather than depth 1.+This is because 'assets:bank:savings' matches at level 3 in the account+name, while 'assets' matches at level 1.  The same would be true with+the argument '--depth assets=1 --depth savings=2'.+++File: hledger.info,  Node: Queries,  Next: Pivoting,  Prev: Depth,  Up: Top++15 Queries+**********++One of hledger's strengths is being able to quickly report on a precise+subset of your data.  Most hledger commands accept query arguments, to+restrict their scope.  Multiple query terms can be provided to build up+a more complex query.++   * By default, a query term is interpreted as a case-insensitive+     substring pattern for matching account names:++     'car:fuel'+     'dining groceries'++   * Patterns containing spaces or other special characters must be+     enclosed in single or double quotes:++     ''personal care''++   * These patterns are actually regular expressions, so you can add+     regexp metacharacters for more precision (see "Regular expressions"+     above for details):++     ''^expenses\b''+     ''food$''+     ''fuel|repair''+     ''accounts (payable|receivable)''++   * To match something other than account name, add one of the query+     type prefixes described in "Query types" below:++     'date:202312-'+     'status:'+     'desc:amazon'+     'cur:USD'+     'cur:\\$'+     'amt:'>0''++   * Add a 'not:' prefix to negate a term:++     'not:status:'*''+     'not:desc:'opening|closing''+     'not:cur:USD'++   * Terms with different types are AND-ed, terms with the same type are+     OR-ed (mostly; see "Combining query terms" below).  The following+     query:++     'date:2022 desc:amazon desc:amzn'++     is interpreted as:++     _date is in 2022 AND ( transaction description contains "amazon" OR+     "amzn" )_++* Menu:++* Query types::+* Combining query terms::+* Queries and command options::+* Queries and account aliases::+* Queries and valuation::+++File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: Queries++15.1 Query types+================++Here are the types of query term available.++* Menu:++* acct query::+* amt query::+* code query::+* cur query::+* desc query::+* date query::+* date2 query::+* depth query::+* expr query::+* not query::+* note query::+* payee query::+* real query::+* status query::+* type query::+* tag query::+++File: hledger.info,  Node: acct query,  Next: amt query,  Up: Query types++15.1.1 acct: query+------------------++*'acct:REGEX'*, or just *'REGEX'*+Match account names containing this case insensitive regular expression.+This is the default query type, so we usually don't bother writing the+"acct:" prefix.+++File: hledger.info,  Node: amt query,  Next: code query,  Prev: acct query,  Up: Query types++15.1.2 amt: query+-----------------++*'amt:N, amt:'<N', 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.  'amt:'+needs quotes to hide the less than/greater than sign from the command+line shell.+++File: hledger.info,  Node: code query,  Next: cur query,  Prev: amt query,  Up: Query types++15.1.3 code: query+------------------++*'code:REGEX'*+Match by transaction code (eg check number).+++File: hledger.info,  Node: cur query,  Next: desc query,  Prev: code query,  Up: Query types++15.1.4 cur: query+-----------------++*'cur:REGEX'*+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX. (Contrary to+hledger's usual infix matching.  To do infix matching, write+'.*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 will usually need one more level+of escaping.  Eg to match the dollar sign: 'cur:\\$' or 'cur:'\$''+++File: hledger.info,  Node: desc query,  Next: date query,  Prev: cur query,  Up: Query types++15.1.5 desc: query+------------------++*'desc:REGEX'*+Match transaction descriptions.+++File: hledger.info,  Node: date query,  Next: date2 query,  Prev: desc query,  Up: Query types++15.1.6 date: query+------------------++*'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'.+++File: hledger.info,  Node: date2 query,  Next: depth query,  Prev: date query,  Up: Query types++15.1.7 date2: query+-------------------++*'date2:PERIODEXPR'*+If you use secondary dates: this matches secondary dates within the+specified period.  It is not affected by the '--date2' flag.+++File: hledger.info,  Node: depth query,  Next: expr query,  Prev: date2 query,  Up: Query types++15.1.8 depth: query+-------------------++*'depth:[REGEXP=]N'*+Match (or display, depending on command) accounts at or above this+depth, optionally only for accounts matching a provided regular+expression.  See Depth for detailed rules.+++File: hledger.info,  Node: expr query,  Next: not query,  Prev: depth query,  Up: Query types++15.1.9 expr: query+------------------++*'expr:'QUERYEXPR''*+'expr' lets you write more complicated query expressions with AND, OR,+NOT, and parentheses.+Eg: 'expr:'date:lastmonth and not (food or rent)''+The expression should be enclosed in quotes.  See Combining query terms+below.+++File: hledger.info,  Node: not query,  Next: note query,  Prev: expr query,  Up: Query types++15.1.10 not: query+------------------++*'not:QUERYTERM'*+You can prepend *'not:'* to any other query term to negate the match.+Eg: 'not:equity', 'not:desc:apple'+(Also, a trick: 'not:not:...' can sometimes solve query problems+conveniently..)+++File: hledger.info,  Node: note query,  Next: payee query,  Prev: not query,  Up: Query types++15.1.11 note: query+-------------------++*'note:REGEX'*+Match transaction notes (the part of the description right of '|', or+the whole description if there's no '|').+++File: hledger.info,  Node: payee query,  Next: real query,  Prev: note query,  Up: Query types++15.1.12 payee: query+--------------------++*'payee:REGEX'*+Match transaction payee/payer names (the part of the description left of+'|', or the whole description if there's no '|').+++File: hledger.info,  Node: real query,  Next: status query,  Prev: payee query,  Up: Query types++15.1.13 real: query+-------------------++*'real:, real:0'*+Match real or virtual postings respectively.+++File: hledger.info,  Node: status query,  Next: type query,  Prev: real query,  Up: Query types++15.1.14 status: query+---------------------++*'status:, status:!, status:*'*+Match unmarked, pending, or cleared transactions respectively.+++File: hledger.info,  Node: type query,  Next: tag query,  Prev: status query,  Up: Query types++15.1.15 type: query+-------------------++*'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.+++File: hledger.info,  Node: tag query,  Prev: type query,  Up: Query types++15.1.16 tag: query+------------------++*'tag:NAMEREGEX[=VALREGEX]'*+Match by tag name, and optionally also by tag value.  Note:++   * Both regular expressions do infix matching.  If you need a complete+     match, use '^' and '$'.+     Eg: 'tag:'^fullname$'', 'tag:'^fullname$=^fullvalue$'+   * To match values, ignoring names, do 'tag:.=VALREGEX'+   * 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.+++File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries++15.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 query terms using 'and', 'or', 'not' keywords+(case insensitive), and to group them by enclosing in parentheses.++   Some examples:++   * Exclude account names containing 'food':++     'expr:"not food"' ('not:food' is equivalent)++   * Match things which have 'cool' in the description and the 'A' tag:++     'expr:"desc:cool and tag:A"' ('expr:"desc:cool tag:A"' is+     equivalent)++   * Match things which either do not reference the 'expenses:food'+     account, or do have the 'A' tag:++     'expr:"not expenses:food or tag:A"'++   * Match things which either do not reference the 'expenses:food'+     account, or which reference the 'expenses:drink' account and also+     have the 'A' tag:++     'expr:"expenses:food or (expenses:drink and tag:A)"'++   'expr:' has a restriction: 'date:' queries may not be used inside+'or' expressions.  That would allow disjoint report periods or disjoint+result sets, with unclear semantics for our reports.+++File: hledger.info,  Node: Queries and command options,  Next: Queries and account aliases,  Prev: Combining query terms,  Up: Queries++15.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 account aliases,  Next: Queries and valuation,  Prev: Queries and command options,  Up: Queries++15.4 Queries and account aliases+================================++When account names are rewritten with '--alias' or 'alias', 'acct:' will+match either the old or the new account name.+++File: hledger.info,  Node: Queries and valuation,  Prev: Queries and account aliases,  Up: Queries++15.5 Queries and valuation+==========================++When amounts are converted to other commodities in cost or value+reports, 'cur:' and 'amt:' match the old commodity symbol and the old+amount quantity, not the new ones.  (Except in hledger 1.22, #1625.)+++File: hledger.info,  Node: Pivoting,  Next: Generating data,  Prev: Queries,  Up: Top++16 Pivoting+***********++Normally, hledger groups amounts and displays their totals by account+(name).  With '--pivot PIVOTEXPR', some other field's (or multiple+fields') value is used as a synthetic account name, causing different+grouping and display.  PIVOTEXPR can be++   * any of these standard transaction or posting fields (their value is+     substituted): 'status', 'code', 'desc', 'payee', 'note', 'acct',+     'comm'/'cur', 'amt', 'cost'+   * or a tag name+   * or any combination of these, colon-separated.++   Some special cases:++   * Colons appearing in PIVOTEXPR or in a pivoted tag value will+     generate account hierarchy.+   * When pivoting a posting has multiple values for a tag, the pivoted+     value of that tag will be the first value.+   * When a posting has multiple commodities, the pivoted value of+     "comm"/"cur" will be "".  Also when an unrecognised tag name or+     field is provided, its pivoted value will be "".  (If this causes+     confusing output, consider excluding those postings from the+     report.)++   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 pivot values:++$ 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++17 Generating data+******************++hledger can enrich the data provided to it, or generate new data, in a+number of ways.  Mostly, this is done only if you request it:++   * Missing amounts or missing costs in transactions are inferred+     automatically when possible.+   * The '--infer-equity' flag infers missing conversion equity postings+     from @/@@ costs.+   * The '--infer-costs' flag infers missing costs from conversion+     equity postings.+   * The '--infer-market-prices' flag infers 'P' price directives from+     costs.+   * The '--auto' flag adds extra postings to transactions matched by+     auto posting rules.+   * The '--forecast' option generates transactions from periodic+     transaction rules.+   * The 'balance --budget' report infers budget goals from periodic+     transaction rules.+   * Commands like 'close', 'rewrite', and 'hledger-interest' generate+     transactions or postings.+   * CSV data is converted to transactions by applying CSV conversion+     rules..  etc.++   Such generated data is temporary, existing only at report time.  You+can convert it to permanent recorded data by, eg, capturing the output+of 'hledger print' and saving it in your journal file.  This can+sometimes be useful as a data entry aid.++   If you are curious what data is being generated and why, run 'hledger+print -x --verbose-tags'.  '-x/--explicit' shows inferred amounts and+'--verbose-tags' adds tags like 'generated-transaction' (from periodic+rules) and 'generated-posting', 'modified' (from auto posting rules).+Similar hidden tags (with an underscore prefix) are always present,+also, so you can always match such data with queries like+'tag:generated' or 'tag:modified'.+++File: hledger.info,  Node: Forecasting,  Next: Budgeting,  Prev: Generating data,  Up: Top++18 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++18.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.++   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++18.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 occurrence 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++18.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++18.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++18.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++18.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: Amount formatting,  Prev: Forecasting,  Up: Top++19 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: Amount formatting,  Next: Cost reporting,  Prev: Budgeting,  Up: Top++20 Amount formatting+********************++* Menu:++* Commodity display style::+* Rounding::+* Trailing decimal marks::+* Amount parseability::+++File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Up: Amount formatting++20.1 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.  Here's an example:++# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive)+# 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++   But for convenience, 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,  Next: Trailing decimal marks,  Prev: Commodity display style,  Up: Amount formatting++20.2 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: Trailing decimal marks,  Next: Amount parseability,  Prev: Rounding,  Up: Amount formatting++20.3 Trailing decimal marks+===========================++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 Decimal 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+++File: hledger.info,  Node: Amount parseability,  Prev: Trailing decimal marks,  Up: Amount formatting++20.4 Amount parseability+========================++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: Cost reporting,  Next: Value reporting,  Prev: Amount formatting,  Up: Top++21 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" generically for convenience.)  With the '-B/--cost' flag, hledger+can show amounts "at cost", converted to the cost's commodity.++* 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++21.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++21.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++21.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++21.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.++   Note you will need to add account declarations for these to your+journal, if you use 'check accounts' or 'check --strict'.+++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++21.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:++   * 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++21.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++21.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++22 Value reporting+******************++hledger can also show amounts "at market value", converted to some other+commodity using the market price or conversion rate on a certain date.++   This is controlled by the '--value=TYPE[,COMMODITY]' option.  We also+provide simpler '-V' and '-X COMMODITY' aliases for this, which are+often sufficient.  The market prices are declared with a special 'P'+directive, and/or they can be inferred from the costs recorded in+transactions, by using the '--infer-market-prices' flag.++* Menu:++* -V Value::+* -X Value in specified commodity::+* Valuation date::+* Finding market price::+* --infer-market-prices market prices from transactions::+* Valuation commodity::+* --value Flexible valuation::+* 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++22.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++22.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++22.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++22.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++22.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: --value Flexible valuation,  Prev: --infer-market-prices market prices from transactions,  Up: Value reporting++22.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: --value Flexible valuation,  Next: Valuation examples,  Prev: Valuation commodity,  Up: Value reporting++22.7 -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: Valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: Value reporting++22.8 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++   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: Valuation examples,  Up: Value reporting++22.9 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.++   Related: #1625+++File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: Value reporting++22.10 Effect of valuation on reports+====================================++Here is a reference for how valuation is supposed to affect each part of+hledger's reports.  (It's wide, you may need to scroll sideways.)  It+may be useful when troubleshooting.  If you find problems, please report+them, ideally with a reproducible example.  Related: #329, #1083.++   First, a quick 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).++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.+++File: hledger.info,  Node: PART 4 COMMANDS,  Next: Help commands,  Prev: Value reporting,  Up: Top++23 PART 4: COMMANDS+*******************++Here are the standard commands, which you can list by running 'hledger'.+If you have installed more add-on commands, they also will be listed.++   *Help commands*++   * help - show the hledger manual with info/man/pager+   * demo - show small hledger demos in the terminal++   *User interface commands*++   * ui - (if installed) run hledger's terminal UI+   * web - (if installed) run hledger's web UI++   *Data entry commands*++   * add - add transactions using terminal prompts+   * import - add new transactions from other files, eg CSV files++   *Basic report commands*++   * accounts - show account names+   * 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++   *Standard report commands*++   * print - show transactions or export journal data+   * aregister (areg) - show transactions in a particular account+   * register (reg) - show postings in one or more accounts & running+     total+   * 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++   *Advanced report commands*++   * balance (bal) - show balance changes, end balances, budgets,+     gains..+   * roi - show return on investments++   *Chart commands*++   * activity - show bar charts of posting counts per period++   *Data generation commands*++   * close - generate balance-zeroing/restoring transactions+   * rewrite - generate auto postings, like print -auto++   *Maintenance commands*++   * check - check for various kinds of error in the data+   * diff - compare account transactions in two journal files+   * test - run self tests++   Next, these commands are described in detail.+++File: hledger.info,  Node: Help commands,  Next: User interface commands,  Prev: PART 4 COMMANDS,  Up: Top++24 Help commands+****************++* Menu:++* commands::+* demo::+* help::+++File: hledger.info,  Node: commands,  Next: demo,  Up: Help commands++24.1 commands+=============++Show the hledger commands list.++Flags:+     --builtin             show only builtin commands, not addons+++File: hledger.info,  Node: demo,  Next: help,  Prev: commands,  Up: Help commands++24.2 demo+=========++Play demos of hledger usage in the terminal, if asciinema is installed.++Flags:+  -s --speed=SPEED         playback speed (1 is original speed, .5 is half, 2+                           is double, etc (default: 2))++   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++   This command is experimental: there aren't many useful demos yet.+++File: hledger.info,  Node: help,  Prev: demo,  Up: Help commands++24.3 help+=========++Show the hledger user manual with 'info', 'man', or a pager.  With a+(case insensitive) TOPIC argument, try to open it at that section+heading.++Flags:+  -i                       show the manual with info+  -m                       show the manual with man+  -p                       show the manual with $PAGER or less+                           (less is always used if TOPIC is specified)++   This command shows the hledger manual built in to your hledger+executable.  It can be useful when offline, or when you prefer the+terminal to a web browser, or when the appropriate hledger manual or+viewers are not installed properly on your system.++   By default it chooses the best viewer found in $PATH, trying in this+order: 'info', 'man', '$PAGER', 'less', 'more', stdout.  (If a TOPIC is+specified, '$PAGER' and 'more' are not tried.)  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 if running non-interactively, it just prints the manual+to stdout.++   When using 'info', TOPIC can match either the full heading or a+prefix.  If your 'info --version' is < 6, you'll need to upgrade it, eg+with ''brew install texinfo'' on mac.++   When using 'man' or 'less', TOPIC must match the full heading.  For a+prefix match, you can write ''TOPIC.*''.++   Examples++$ hledger help -h                 # show the help command's usage+$ hledger help                    # show the manual with info, man or $PAGER+$ hledger help 'time periods'     # show the manual's "Time periods" topic+$ hledger help 'time periods' -m  # use man, even if info is installed+++File: hledger.info,  Node: User interface commands,  Next: Data entry commands,  Prev: Help commands,  Up: Top++25 User interface commands+**************************++* Menu:++* repl::+* run::+* ui::+* web::+++File: hledger.info,  Node: repl,  Next: run,  Up: User interface commands++25.1 repl+=========++Start an interactive prompt, where you can run any of hledger's+commands.  Data files are parsed just once, so the commands run faster.++Flags:+no command-specific flags++   This command is experimental and could change in the future.++   'hledger repl' starts a read-eval-print loop (REPL) where you can+enter commands interactively.  As with the 'run' command, each input+file (or each input file/input options combination) is parsed just once,+so commands will run more quickly than if you ran them individually at+the command line.++   Also like 'run', the input file(s) specified for the 'repl' command+will be the default input for all interactive commands, you can override+this temporarily by specifying an '-f' option in particular commands,+and commands will not see any changes made to input files (eg by 'add')+until you exit and restart the REPL.++   The command syntax is the same as with 'run':++   * enter one hledger command at a time, without the usual 'hledger'+     first word+   * empty lines and comment text from '#' to end of line are ignored+   * use single or double quotes to quote arguments when needed+   * type 'exit' or 'quit' or control-D to exit the REPL.++   While it is running, the REPL remembers your command history, and you+can navigate in the usual ways:++   * Keypad or Emacs navigation keys to edit the current command line+   * UP/DOWN or control-P/control-N to step back/forward through history+   * control-R to search for a past command+   * TAB completes file paths.++   The 'commands' and 'help' commands, and the command help flags ('CMD+--tldr', 'CMD -h/--help', 'CMD --info', 'CMD --man'), work in the usual+way, and can be useful.++   You can type control-C to cancel a long-running command (but only+once; typing it a second time will exit the REPL).++   And in most shells you can type control-Z to exit temporarily to the+shell (and 'fg' to return to the REPL).++   You may find some differences in behaviour between 'run' command+lines and normal hledger command lines.  For example, in the REPL,++   * the command name must be written first, options afterward+   * full command names or official abbreviations (as in the command+     list) must be used+   * options parsing with addon commands might be less flexible than the+     CLI+   * the 'stats' command gives false timings, currently++* Menu:++* Examples::+++File: hledger.info,  Node: Examples,  Up: repl++25.1.1 Examples+---------------++Start the REPL and enter some commands:++$ hledger repl +Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF.+% stats+Main file           : .../2025.journal+...+% stats -f 2024/2024.journal +Main file           : .../2024.journal+...+% stats+Main file           : .../2025.journal+...++   or:++$ hledger repl -f some.journal+Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF.+% bs+...+% print -b 'last week'+...+% bs -f other.journal+...+++File: hledger.info,  Node: run,  Next: ui,  Prev: repl,  Up: User interface commands++25.2 run+========++Run a sequence of hledger commands, provided as files or command line+arguments.  Data files are parsed just once, so the commands run faster.++Flags:+no command-specific flags++   This command is experimental and could change in the future.++   You can use 'run' in three ways:++   * 'hledger run -- CMD1 -- CMD2 -- CMD3' - read commands from the+     command line, separated by '--'+   * 'hledger run SCRIPTFILE1 SCRIPTFILE2' - read commands from one or+     more files+   * 'cat SCRIPTFILE1 | hledger run' - read commands from standard+     input.++   'run' first loads the input file(s) specified by 'LEDGER_FILE' or by+'-f' options, in the usual way.  Then it runs each command in turn, each+using the same input data.  But if you want a particular command to use+different input, you can specify an '-f' option within that command.+This will override (not add to) the default input, just for that+command.++   Each input file (more precisely, each combination of input file and+input options) is parsed only once.  This means that commands will not+see any changes made to these files, until the next run.  But the+commands will run more quickly than if run individually (typically about+twice as fast).++   Command scripts, whether in a file or written on the command line,+have a simple syntax:++   * each line may contain a single hledger command and its arguments,+     without the usual 'hledger' first word+   * empty lines are ignored+   * text from '#' to end of line is a comment, and ignored+   * you can use single or double quotes to quote arguments when needed,+     as on the command line+   * these extra commands are available: 'echo TEXT' prints some text,+     and 'exit' or 'quit' ends the run.++   On unix systems you can use '#!/usr/bin/env hledger run' in the first+line of a command file to make it a runnable script.  If that gives an+error, use '#!/usr/bin/env -S hledger run'.++   It's ok to use the 'run' command recursively within a command script.++   You may find some differences in behaviour between 'run' command+lines and normal hledger command lines.  For example, with 'run',++   * the command name must be written first, options afterward+   * full command names or official abbreviations (as in the command+     list) must be used++* Menu:++* Examples: Examples 2.+++File: hledger.info,  Node: Examples 2,  Up: run++25.2.1 Examples+---------------++Run commands from the command line:++hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats++   This would load 'some.journal', run 'balance assets --depth 2' on it,+then run 'balance liabilities --depth 3 --transpose' on+'/some/other.journal', and finally run 'stats' on 'some.journal'++   Run commands from standard input:++(echo "files"; echo "stats") | hledger -f some.journal run++   Run commands as a script:++$ cat report+#!/usr/bin/env -S hledger run -f some.journal++echo "List of accounts in some.journal"+accounts++echo "Assets of some.journal"+balance assets --depth 2++echo "Liabilities from /some/other.journal"+balance liabilities -f /some/other.journal --depth 3 --transpose++echo "Commands from another.script, applied to another.journal"+run -f another.journal another.script++$ chmod +x report+$ ./report+List of accounts in some.journal+...+++File: hledger.info,  Node: ui,  Next: web,  Prev: run,  Up: User interface commands++25.3 ui+=======++Runs hledger-ui (if installed).+++File: hledger.info,  Node: web,  Prev: ui,  Up: User interface commands++25.4 web+========++Runs hledger-web (if installed).+++File: hledger.info,  Node: Data entry commands,  Next: Basic report commands,  Prev: User interface commands,  Up: Top++26 Data entry commands+**********************++* Menu:++* add::+* import::+++File: hledger.info,  Node: add,  Next: import,  Up: Data entry commands++26.1 add+========++Record new transactions with interactive prompting in the console.++Flags:+     --no-new-accounts      don't allow creating new accounts++   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.+   * 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.++   Notes:++   * If you enter a number with no commodity symbol, and you have+     declared a default commodity with a 'D' directive, you might expect+     'add' to add this symbol for you.  It does not do this; we assume+     that if you are using a 'D' directive you prefer not to see the+     commodity symbol repeated on amounts in the journal.++   Examples:++   * Record new transactions, saving to the default journal file:++     'hledger add'++   * Add transactions to 2024.journal, but also load 2023.journal for+     completions:++     'hledger add --file 2024.journal --file 2023.journal'++   * Provide answers for the first four prompts:++     'hledger add today 'best buy' expenses:supplies '$20''++   There is a detailed tutorial at https://hledger.org/add.html.+++File: hledger.info,  Node: import,  Prev: add,  Up: Data entry commands++26.2 import+===========++Import new transactions from one or more data files to the main journal.++Flags:+     --catchup              just mark all transactions as already imported+     --dry-run              just show the transactions to be imported++   This command detects new transactions in one or more data files+specified as arguments, and appends them to the main journal.++   You can import from any input file format hledger supports, but+CSV/SSV/TSV files, downloaded from financial institutions, are the most+common import source.++   The import destination is the default journal file, or another+specified in the usual way with '$LEDGER_FILE' or '-f/--file'.  It+should be in journal format.++   Examples:++$ hledger import bank1-checking.csv bank1-savings.csv++$ hledger import *.csv++* Menu:++* Import preview::+* Overlap detection::+* First import::+* Importing balance assignments::+* Import and commodity styles::+* Import special cases::+++File: hledger.info,  Node: Import preview,  Next: Overlap detection,  Up: import++26.2.1 Import preview+---------------------++It's useful to preview the import by running first with '--dry-run', to+sanity check the range of dates being imported, and to check the effect+of your conversion rules if converting from CSV. Eg:++$ hledger import bank.csv --dry-run++   The dry run output is valid journal format, so hledger can re-parse+it.  If the output is large, you could show just the uncategorised+transactions like so:++$ hledger import --dry-run bank.csv | hledger -f- -I print unknown++   You could also run this repeatedly to see the effect of edits to your+conversion rules:++$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'++   Once the conversion and dates look good enough to import to your+journal, perhaps with some manual fixups to follow, you would do the+actual import:++$ hledger import bank.csv+++File: hledger.info,  Node: Overlap detection,  Next: First import,  Prev: Import preview,  Up: import++26.2.2 Overlap detection+------------------------++Reading CSV files is built in to hledger, and not specific to 'import';+so you could also import by doing 'hledger -f bank.csv print+>>$LEDGER_FILE'.++   But 'import' is easier and provides some advantages.  The main one is+that it avoids re-importing transactions it has seen on previous runs.+This means you don't have to worry about overlapping data in successive+downloads of your bank CSV; just download and 'import' as often as you+like, and only the new transactions will be imported each time.++   We don't call this "deduplication", as it's generally not possible to+reliably detect duplicates in bank CSV. Instead, 'import' remembers the+latest date processed previously in each CSV file (saving it in a hidden+file), and skips any records prior to that date.  This works well for+most real-world CSV, where:++  1. the data file name is stable (does not change) across imports+  2. the item dates are stable across imports+  3. the order of same-date items is stable across imports+  4. the newest items have the newest dates++   (Occasional violations of 2-4 are often harmless; you can reduce the+chance of disruption by downloading and importing more often.)++   Overlap detection is automatic, and shouldn't require much attention+from you, except perhaps at first import (see below).  But here's how it+works:++   * For each 'FILE' being imported from:++       1. hledger reads a file named '.latest.FILE' file in the same+          directory, if any.  This file contains the latest record date+          previously imported from FILE, in YYYY-MM-DD format.  If+          multiple records with that date were imported, the date is+          repeated on N lines.++       2. hledger reads records from FILE. If a latest date was found in+          step 1, any records before that date, and the first N records+          on that date, are skipped.++   * After a successful import from all FILEs, without error and without+     '--dry-run', hledger updates each FILE's '.latest.FILE' for next+     time.++   If this goes wrong, it's relatively easy to repair:++   * You'll notice it before import when you preview with 'import+     --dry-run'.+   * Or after import when you try to reconcile your hledger account+     balances with your bank.+   * 'hledger print -f FILE.csv' will show all recently downloaded+     transactions.  Compare these with your journal.  Copy/paste if+     needed.+   * Update your conversion rules and print again, if needed.+   * You can manually update or remove the .latest file, or use 'import+     --catchup FILE'.+   * Download and import more often, eg twice a week, at least while you+     are learning.  It's easier to review and troubleshoot when there+     are fewer transactions.+++File: hledger.info,  Node: First import,  Next: Importing balance assignments,  Prev: Overlap detection,  Up: import++26.2.3 First import+-------------------++The first time you import from a file, when no corresponding .latest+file has been created yet, all of the records will be imported.++   But perhaps you have been entering the data manually, so you know+that all of these transactions are already recorded in the journal.  In+this case you can run 'hledger import --catchup' once.  This will create+a .latest file containing the latest CSV record date, so that none of+those records will be re-imported.++   Or, if you know that some but not all of the transactions are in the+journal, you can create the .latest file yourself.  Eg, let's say you+previously recorded foobank transactions up to 2024-10-31 in the+journal.  Then in the directory where you'll be saving 'foobank.csv',+you would create a '.latest.foobank.csv' file containing++2024-10-31++   Or if you had three foobank transactions recorded with that date, you+would repeat the date that many times:++2024-10-31+2024-10-31+2024-10-31++   Then 'hledger import foobank.csv [--dry-run]' will import only the+newer records.+++File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: First import,  Up: import++26.2.4 Importing balance assignments+------------------------------------++Journal entries added by import will have all posting amounts made+explicit (like 'print -x').++   This means that any balance assignments in the imported entries would+need to be evaluated.  But this generally isn't possible, as the main+file's account balances are not visible during import.  So try to avoid+generating balance assignments with your CSV rules, or importing from a+journal that contains balance assignments.  (Balance assignments are+best avoided anyway.)++   But if you must use them, eg because your CSV includes only balances:+you can import with 'print', which leaves implicit amounts implicit.+('print' can also do overlap detection like import, with the '--new'+flag):++$ hledger print --new -f bank.csv >> $LEDGER_FILE++   (If you think 'import' should preserve implicit balances, please test+that and send a pull request.)+++File: hledger.info,  Node: Import and commodity styles,  Next: Import special cases,  Prev: Importing balance assignments,  Up: import++26.2.5 Import and commodity styles+----------------------------------++Amounts in entries added by import will be formatted according to the+journal's canonical commodity styles, as declared by 'commodity'+directives or inferred from the journal's amounts.++   Related: CSV > Amount decimal places.+++File: hledger.info,  Node: Import special cases,  Prev: Import and commodity styles,  Up: import++26.2.6 Import special cases+---------------------------++If you have a download whose file name varies, you could rename it to a+fixed name after each download.  Or you could use a CSV 'source' rule+with a suitable glob pattern, and import from the .rules file instead of+the data file.++   Here's a situation where you would need to run 'import' with care:+say you download 'bank.csv', but forget to import it or delete it.  And+next month you download it again.  This time your web browser may save+it as 'bank (2).csv'.  So now each of these may have data not included+in the other.  And a 'source' rule with a glob pattern would match only+the most recent file.  So in this case you should import from each one+in turn, in the correct order, taking care to use the same filename each+time:++$ hledger import bank.csv+$ mv 'bank (2).csv' bank.csv+$ hledger import bank.csv++   Here are two kinds of "deduplication" which 'import' does not handle+(and generally should not, since these can happen legitimately in+financial data):++   * Two or more of the new CSV records are identical, and generate+     identical new journal entries.+   * A new CSV record generates a journal entry identical to one(s)+     already in the journal.+++File: hledger.info,  Node: Basic report commands,  Next: Standard report commands,  Prev: Data entry commands,  Up: Top++27 Basic report commands+************************++* Menu:++* accounts::+* codes::+* commodities::+* descriptions::+* files::+* notes::+* payees::+* prices::+* stats::+* tags::+++File: hledger.info,  Node: accounts,  Next: codes,  Up: Basic report commands++27.1 accounts+=============++List account names.++Flags:+  -u --used                 show only accounts used by transactions+  -d --declared             show only accounts declared by account directive+     --unused               show only accounts declared but not used+     --undeclared           show only accounts used but not declared+     --types                also show account types when known+     --positions            also show where accounts were declared+     --directives           show as account directives, for use in journals+     --find                 find the first account matched by the first+                            argument (a case-insensitive infix regexp or+                            account name)+  -l --flat                 show accounts as a flat list (default)+  -t --tree                 show accounts as a tree+     --drop=N               flat mode: omit N leading account name parts++   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: codes,  Next: commodities,  Prev: accounts,  Up: Basic report commands++27.2 codes+==========++List the codes seen in transactions, in the order parsed.++Flags:+no command-specific flags++   This command prints the value of each transaction's code field, in+the order transactions were parsed.  The transaction code is an optional+value written in parentheses between the date and description, often+used to store a cheque number, order number or similar.++   Transactions aren't required to have a code, and missing or empty+codes will not be shown by default.  With the '-E'/'--empty' flag, they+will be printed as blank lines.++   You can add a query to select a subset of transactions.++   Examples:++2022/1/1 (123) Supermarket   + Food       $5.00+ Checking    ++2022/1/2 (124) Post Office+ Postage    $8.32+ Checking++2022/1/3 Supermarket+ Food      $11.23+ Checking ++2022/1/4 (126) Post Office+ Postage    $3.21+ Checking++$ hledger codes+123+124+126++$ hledger codes -E+123+124++126+++File: hledger.info,  Node: commodities,  Next: descriptions,  Prev: codes,  Up: Basic report commands++27.3 commodities+================++List all commodity/currency symbols used or declared in the journal.++Flags:+no command-specific flags+++File: hledger.info,  Node: descriptions,  Next: files,  Prev: commodities,  Up: Basic report commands++27.4 descriptions+=================++List the unique descriptions that appear in transactions.++Flags:+no command-specific flags++   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: files,  Next: notes,  Prev: descriptions,  Up: Basic report commands++27.5 files+==========++List all files included in the journal.  With a REGEX argument, only+file names matching the regular expression (case sensitive) are shown.++Flags:+no command-specific flags+++File: hledger.info,  Node: notes,  Next: payees,  Prev: files,  Up: Basic report commands++27.6 notes+==========++List the unique notes that appear in transactions.++Flags:+no command-specific flags++   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: Basic report commands++27.7 payees+===========++List the unique payee/payer names that appear in transactions.++Flags:+     --declared             show payees declared with payee directives+     --used                 show payees referenced by 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: stats,  Prev: payees,  Up: Basic report commands++27.8 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.++Flags:+     --show-reverse         also show the 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: stats,  Next: tags,  Prev: prices,  Up: Basic report commands++27.9 stats+==========++Show journal and performance statistics.++Flags:+  -v --verbose              show more detailed output+  -o --output-file=FILE     write output to FILE.++   The stats command shows summary information for the whole journal, or+a matched part of it.  With a reporting interval, it shows a report for+each report period.++   The default output is fairly impersonal, though it reveals the main+file name.  With '-v/--verbose', more details are shown, like file+paths, included files, and commodity names.++   It also shows some run time statistics:++   * elapsed time+   * throughput: the number of transactions processed per second+   * live: the peak memory in use by the program to do its work+   * alloc: the peak memory allocation from the OS as seen by GHC.+     Measuring this externally, eg with GNU time, is more accurate;+     usually that will be a larger number; sometimes (with swapping?)+     smaller.++   The 'stats' command's run time is similar to that of a balance+report.++   Example:++$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file           : .../1ktxns-1kaccts.journal+Included files      : 0+Txns span           : 2000-01-01 to 2002-09-27 (1000 days)+Last txn            : 2002-09-26 (7827 days ago)+Txns                : 1000 (1.0 per day)+Txns last 30 days   : 0 (0.0 per day)+Txns last 7 days    : 0 (0.0 per day)+Payees/descriptions : 1000+Accounts            : 1000 (depth 10)+Commodities         : 26+Market prices       : 1000+Runtime stats       : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc++   This command supports the -o/-output-file option (but not+-O/-output-format).+++File: hledger.info,  Node: tags,  Prev: stats,  Up: Basic report commands++27.10 tags+==========++List the tags used in the journal, or their values.++Flags:+     --values               list tag values instead of tag names+     --parsed               show tags/values in the order they were parsed,+                            including duplicates++   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: Standard report commands,  Next: Advanced report commands,  Prev: Basic report commands,  Up: Top++28 Standard report commands+***************************++* Menu:++* print::+* aregister::+* register::+* balancesheet::+* balancesheetequity::+* cashflow::+* incomestatement::+++File: hledger.info,  Node: print,  Next: aregister,  Up: Standard report commands++28.1 print+==========++Show full journal entries, representing transactions.++Flags:+  -x --explicit             show all amounts explicitly+     --show-costs           show transaction prices even with conversion+                            postings+     --round=TYPE           how much rounding or padding should be done when+                            displaying amounts ?+                            none - show original decimal digits,+                                   as in journal (default)+                            soft - just add or remove decimal zeros+                                   to match precision+                            hard - round posting amounts to precision+                                   (can unbalance transactions)+                            all  - also round cost amounts to precision+                                   (can unbalance transactions)+     --invert               display all amounts with reversed sign+     --new                  show only newer-dated transactions added in each+                            file since last run+  -m --match=DESC           fuzzy search for one recent transaction with+                            description closest to DESC+     --base-url=URLPREFIX   in html output, generate links to hledger-web,+                            with this prefix. (Usually the base url shown by+                            hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, beancount, csv, tsv, html, fods, json, sql.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   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++28.1.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++28.1.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' (_Added in 1.32_) 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++28.1.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++28.1.4 print, other features+----------------------------++With '-B'/'--cost', amounts with costs are shown converted to cost.++   With '--invert', posting amounts are shown with their sign flipped.+It could be useful if you have accidentally recorded some transactions+with the wrong signs.++   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++28.1.5 print output format+--------------------------++This command also supports the output destination and output format+options The output formats supported are 'txt', 'beancount' (_Added in+1.32_), 'csv', 'tsv' (_Added in 1.32_), 'json' and 'sql'.++   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: aregister,  Next: register,  Prev: print,  Up: Standard report commands++28.2 aregister+==============++(areg)++   Show the transactions and running balances in one account, with each+transaction on one line.++Flags:+     --txn-dates            filter strictly by transaction date, not posting+                            date. Warning: this can show a wrong running+                            balance.+     --no-elide             don't show only 2 commodities per amount+     --cumulative           show running total from report start date+  -H --historical           show historical running total/balance (includes+                            postings before report start date) (default)+     --invert               display all amounts with reversed sign+     --heading=YN           show heading row above table: yes (default) or no+  -w --width=N              set output width (default: terminal width). -wN,M+                            sets description width as well.+     --align-all            guarantee alignment across all lines (slower)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, html, csv, tsv, json.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   '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 included in the running balance ('--historical' mode is the+default).  You can suppress this behaviour using the '--cumulative'+option.++   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.++   By default, 'aregister' shows a heading above the data.  However,+when reporting in a language different from English, it is easier to+omit this heading and prepend your own one.  For this purpose, use the+'--heading=no' option.++   This command also supports the output destination and output format+options.  The output formats supported are 'txt', 'csv', 'tsv' (_Added+in 1.32_), 'html', 'fods' (_Added in 1.41_) and 'json'.++* Menu:++* aregister and posting dates::+++File: hledger.info,  Node: aregister and posting dates,  Up: aregister++28.2.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: register,  Next: balancesheet,  Prev: aregister,  Up: Standard report commands++28.3 register+=============++(reg)++   Show postings and their running total.++Flags:+     --cumulative           show running total from report start date+                            (default)+  -H --historical           show historical running total/balance (includes+                            postings before report start date)+  -A --average              show running average of posting amounts instead+                            of total (implies --empty)+  -m --match=DESC           fuzzy search for one recent posting with+                            description closest to DESC+  -r --related              show postings' siblings instead+     --invert               display all amounts with reversed sign+     --sort=FIELDS          sort by: date, desc, account, amount, absamount,+                            or a comma-separated combination of these. For a+                            descending sort, prefix with -. (Default: date)+  -w --width=N              set output width (default: terminal width). -wN,M+                            sets description width as well.+     --align-all            guarantee alignment across all lines (slower)+     --base-url=URLPREFIX   in html output, generate links to hledger-web,+                            with this prefix. (Usually the base url shown by+                            hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, csv, tsv, html, fods, json.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   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:++   The '--sort=FIELDS' flag sorts by the fields given, which can be any+of 'account', 'amount', 'absamount', 'date', or 'desc'/'description',+optionally separated by commas.  For example, '--sort account,amount'+will group all transactions in each account, sorted by transaction+amount.  Each field can be negated by a preceding '-', so '--sort+-amount' will show transactions ordered from smallest amount to largest+amount.++$ 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++28.3.1 Custom register output+-----------------------------++register normally uses the full terminal width (or 80 columns if it+can't detect that).  You can override this with 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+$ hledger reg -w 100,40           # set overall width 100, description width 40++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv' (_Added in+1.32_), and 'json'.+++File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: register,  Up: Standard report commands++28.4 balancesheet+=================++(bs)++   Show the end balances in asset and liability accounts.  Amounts are+shown with normal positive sign, as in conventional financial+statements.++Flags:+     --sum                  show sum of posting amounts (default)+     --valuechange          show total change of period-end historical+                            balance value (caused by deposits, withdrawals,+                            market price fluctuations)+     --gain                 show unrealised capital gain/loss (historical+                            balance value minus cost basis)+     --count                show the count of postings+     --change               accumulate amounts from column start to column+                            end (in multicolumn reports)+     --cumulative           accumulate amounts from report start (specified+                            by e.g. -b/--begin) to column end+  -H --historical           accumulate amounts from journal start to column+                            end (includes postings before report start date)+                            (default)+  -l --flat                 show accounts as a flat list (default). Amounts+                            exclude subaccount amounts, except where the+                            account is depth-clipped.+  -t --tree                 show accounts as a tree. Amounts include+                            subaccount amounts.+     --drop=N               flat mode: omit N leading account name parts+     --declared             include non-parent declared accounts (best used+                            with -E)+  -A --average              show a row average column (in multicolumn+                            reports)+  -T --row-total            show a row total column (in multicolumn reports)+     --summary-only         display only row summaries (e.g. row total,+                            average) (in multicolumn reports)+  -N --no-total             omit the final total row+     --no-elide             don't squash boring parent accounts (in tree+                            mode)+     --format=FORMATSTR     use this custom line format (in simple reports)+  -S --sort-amount          sort by amount instead of account code/name+  -% --percent              express values in percentage of each column's+                            total+     --layout=ARG           how to show multi-commodity amounts:+                            'wide[,WIDTH]': all commodities on one line+                            'tall'        : each commodity on a new line+                            'bare'        : bare numbers, symbols in a column+     --base-url=URLPREFIX   in html output, generate hyperlinks to+                            hledger-web, with this prefix. (Usually the base+                            url shown by hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, html, csv, tsv, json.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   This command displays a balance sheet, showing historical ending+balances of asset and liability accounts.  (To see equity as well, use+the balancesheetequity command.)++   Accounts declared with the 'Asset', 'Cash' or 'Liability' type are+shown (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 2008-12-31++                    || 2008-12-31 +====================++============+ Assets             ||            +--------------------++------------+ assets:bank:saving ||         $1 + assets:cash        ||        $-2 +--------------------++------------+                    ||        $-1 +====================++============+ Liabilities        ||            +--------------------++------------+ liabilities:debts  ||        $-1 +--------------------++------------+                    ||        $-1 +====================++============+ Net:               ||          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' (_Added in+1.32_), 'html', and 'json'.+++File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: Standard report commands++28.5 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.++Flags:+     --sum                  show sum of posting amounts (default)+     --valuechange          show total change of period-end historical+                            balance value (caused by deposits, withdrawals,+                            market price fluctuations)+     --gain                 show unrealised capital gain/loss (historical+                            balance value minus cost basis)+     --count                show the count of postings+     --change               accumulate amounts from column start to column+                            end (in multicolumn reports)+     --cumulative           accumulate amounts from report start (specified+                            by e.g. -b/--begin) to column end+  -H --historical           accumulate amounts from journal start to column+                            end (includes postings before report start date)+                            (default)+  -l --flat                 show accounts as a flat list (default). Amounts+                            exclude subaccount amounts, except where the+                            account is depth-clipped.+  -t --tree                 show accounts as a tree. Amounts include+                            subaccount amounts.+     --drop=N               flat mode: omit N leading account name parts+     --declared             include non-parent declared accounts (best used+                            with -E)+  -A --average              show a row average column (in multicolumn+                            reports)+  -T --row-total            show a row total column (in multicolumn reports)+     --summary-only         display only row summaries (e.g. row total,+                            average) (in multicolumn reports)+  -N --no-total             omit the final total row+     --no-elide             don't squash boring parent accounts (in tree+                            mode)+     --format=FORMATSTR     use this custom line format (in simple reports)+  -S --sort-amount          sort by amount instead of account code/name+  -% --percent              express values in percentage of each column's+                            total+     --layout=ARG           how to show multi-commodity amounts:+                            'wide[,WIDTH]': all commodities on one line+                            'tall'        : each commodity on a new line+                            'bare'        : bare numbers, symbols in a column+     --base-url=URLPREFIX   in html output, generate hyperlinks to+                            hledger-web, with this prefix. (Usually the base+                            url shown by hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, html, csv, tsv, json.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   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 2008-12-31++                    || 2008-12-31 +====================++============+ Assets             ||            +--------------------++------------+ assets:bank:saving ||         $1 + assets:cash        ||        $-2 +--------------------++------------+                    ||        $-1 +====================++============+ Liabilities        ||            +--------------------++------------+ liabilities:debts  ||        $-1 +--------------------++------------+                    ||        $-1 +====================++============+ Equity             ||            +--------------------++------------+--------------------++------------+                    ||          0 +====================++============+ Net:               ||          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 report is the easiest way to see if the accounting equation+(A+L+E = 0) is satisfied (after you have done a 'close --retain' to+merge revenues and expenses with equity, and perhaps added+'--infer-equity' to balance your commodity conversions).++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv', 'html',+and 'json'.+++File: hledger.info,  Node: cashflow,  Next: incomestatement,  Prev: balancesheetequity,  Up: Standard report commands++28.6 cashflow+=============++(cf)++   This command displays a (simple) 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.++Flags:+     --sum                  show sum of posting amounts (default)+     --valuechange          show total change of period-end historical+                            balance value (caused by deposits, withdrawals,+                            market price fluctuations)+     --gain                 show unrealised capital gain/loss (historical+                            balance value minus cost basis)+     --count                show the count of postings+     --change               accumulate amounts from column start to column+                            end (in multicolumn reports) (default)+     --cumulative           accumulate amounts from report start (specified+                            by e.g. -b/--begin) to column end+  -H --historical           accumulate amounts from journal start to column+                            end (includes postings before report start date)+  -l --flat                 show accounts as a flat list (default). Amounts+                            exclude subaccount amounts, except where the+                            account is depth-clipped.+  -t --tree                 show accounts as a tree. Amounts include+                            subaccount amounts.+     --drop=N               flat mode: omit N leading account name parts+     --declared             include non-parent declared accounts (best used+                            with -E)+  -A --average              show a row average column (in multicolumn+                            reports)+  -T --row-total            show a row total column (in multicolumn reports)+     --summary-only         display only row summaries (e.g. row total,+                            average) (in multicolumn reports)+  -N --no-total             omit the final total row+     --no-elide             don't squash boring parent accounts (in tree+                            mode)+     --format=FORMATSTR     use this custom line format (in simple reports)+  -S --sort-amount          sort by amount instead of account code/name+  -% --percent              express values in percentage of each column's+                            total+     --layout=ARG           how to show multi-commodity amounts:+                            'wide[,WIDTH]': all commodities on one line+                            'tall'        : each commodity on a new line+                            'bare'        : bare numbers, symbols in a column+     --base-url=URLPREFIX   in html output, generate hyperlinks to+                            hledger-web, with this prefix. (Usually the base+                            url shown by hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, html, csv, tsv, json.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   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 2008++                    || 2008 +====================++======+ Cash flows         ||      +--------------------++------+ assets:bank:saving ||   $1 + assets:cash        ||  $-2 +--------------------++------+                    ||  $-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' (_Added in+1.32_), 'html', and 'json'.+++File: hledger.info,  Node: incomestatement,  Prev: cashflow,  Up: Standard report commands++28.7 incomestatement+====================++(is)++   Show revenue inflows and expense outflows during the report period.+Amounts are shown with normal positive sign, as in conventional+financial statements.++Flags:+     --sum                  show sum of posting amounts (default)+     --valuechange          show total change of period-end historical+                            balance value (caused by deposits, withdrawals,+                            market price fluctuations)+     --gain                 show unrealised capital gain/loss (historical+                            balance value minus cost basis)+     --count                show the count of postings+     --change               accumulate amounts from column start to column+                            end (in multicolumn reports) (default)+     --cumulative           accumulate amounts from report start (specified+                            by e.g. -b/--begin) to column end+  -H --historical           accumulate amounts from journal start to column+                            end (includes postings before report start date)+  -l --flat                 show accounts as a flat list (default). Amounts+                            exclude subaccount amounts, except where the+                            account is depth-clipped.+  -t --tree                 show accounts as a tree. Amounts include+                            subaccount amounts.+     --drop=N               flat mode: omit N leading account name parts+     --declared             include non-parent declared accounts (best used+                            with -E)+  -A --average              show a row average column (in multicolumn+                            reports)+  -T --row-total            show a row total column (in multicolumn reports)+     --summary-only         display only row summaries (e.g. row total,+                            average) (in multicolumn reports)+  -N --no-total             omit the final total row+     --no-elide             don't squash boring parent accounts (in tree+                            mode)+     --format=FORMATSTR     use this custom line format (in simple reports)+  -S --sort-amount          sort by amount instead of account code/name+  -% --percent              express values in percentage of each column's+                            total+     --layout=ARG           how to show multi-commodity amounts:+                            'wide[,WIDTH]': all commodities on one line+                            'tall'        : each commodity on a new line+                            'bare'        : bare numbers, symbols in a column+     --base-url=URLPREFIX   in html output, generate hyperlinks to+                            hledger-web, with this prefix. (Usually the base+                            url shown by hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, html, csv, tsv, json.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   This command displays an income statement, showing revenues and+expenses during one or more periods.++   It 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 2008++                   || 2008 +===================++======+ Revenues          ||      +-------------------++------+ income:gifts      ||   $1 + income:salary     ||   $1 +-------------------++------+                   ||   $2 +===================++======+ Expenses          ||      +-------------------++------+ expenses:food     ||   $1 + expenses:supplies ||   $1 +-------------------++------+                   ||   $2 +===================++======+ Net:              ||    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' (_Added in+1.32_), 'html', and 'json'.+++File: hledger.info,  Node: Advanced report commands,  Next: Chart commands,  Prev: Standard report commands,  Up: Top++29 Advanced report commands+***************************++* Menu:++* balance::+* roi::+++File: hledger.info,  Node: balance,  Next: roi,  Up: Advanced report commands++29.1 balance+============++(bal)++   A flexible, general purpose "summing" report that shows accounts with+some kind of numeric data.  This can be balance changes per period, end+balances, budget performance, unrealised capital gains, etc.++Flags:+     --sum                  show sum of posting amounts (default)+     --valuechange          show total change of value of period-end+                            historical balances (caused by deposits,+                            withdrawals, market price fluctuations)+     --gain                 show unrealised capital gain/loss (historical+                            balance value minus cost basis)+     --budget[=DESCPAT]     show sum of posting amounts together with budget+                            goals defined by periodic+                            transactions. With a DESCPAT argument (must be+                            separated by = not space),+                            use only periodic transactions with matching+                            description+                            (case insensitive substring match).+     --count                show the count of postings+     --change               accumulate amounts from column start to column+                            end (in multicolumn reports, default)+     --cumulative           accumulate amounts from report start (specified+                            by e.g. -b/--begin) to column end+  -H --historical           accumulate amounts from journal start to column+                            end (includes postings before report start date)+  -l --flat                 show accounts as a flat list (default). Amounts+                            exclude subaccount amounts, except where the+                            account is depth-clipped.+  -t --tree                 show accounts as a tree. Amounts include+                            subaccount amounts.+     --drop=N               omit N leading account name parts (in flat mode)+     --declared             include non-parent declared accounts (best used+                            with -E)+  -A --average              show a row average column (in multicolumn+                            reports)+  -T --row-total            show a row total column (in multicolumn reports)+     --summary-only         display only row summaries (e.g. row total,+                            average) (in multicolumn reports)+  -N --no-total             omit the final total row+     --no-elide             don't squash boring parent accounts (in tree+                            mode)+     --format=FORMATSTR     use this custom line format (in simple reports)+  -S --sort-amount          sort by amount instead of account code/name (in+                            flat mode). With multiple columns, sorts by the row+                            total, or by row average if that is displayed.+  -% --percent              express values in percentage of each column's+                            total+  -r --related              show the other accounts transacted with, instead+     --invert               display all amounts with reversed sign+     --transpose            switch rows and columns (use vertical time axis)+     --layout=ARG           how to lay out multi-commodity amounts and the+                            overall table:+                            'wide[,W]': commodities on same line, up to W wide+                            'tall'    : commodities on separate lines+                            'bare'    : commodity symbols in a separate column+                            'tidy'    : each data field in its own column+     --base-url=URLPREFIX   in html output, generate links to hledger-web,+                            with this prefix. (Usually the base url shown by+                            hledger-web; can also be relative.)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, html, csv, tsv, json, fods.+  -o --output-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.++   '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::+* Balance report output::+* Some useful balance reports::+++File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance++29.1.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 balance changes from sibling postings ('--related'/'-r')+   * 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' (_Added in 1.32_),+'json', and (multi-period reports only:) 'html', 'fods' (_Added in+1.40_).  In 'txt' output in a colour-supporting terminal, negative+amounts are shown in red.+++File: hledger.info,  Node: Simple balance report,  Next: Balance report line format,  Prev: balance features,  Up: balance++29.1.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++29.1.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++29.1.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++29.1.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++29.1.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++29.1.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++29.1.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++29.1.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++29.1.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++29.1.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.+   * 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.+   * The '--summary-only' flag ('--summary' also works) hides all but+     the Total and Average columns (those should be enabled with+     '--row-total' and '-A/--average').++   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'+   * Filter to a single currency with 'cur:'+   * Convert to a single currency with '-V [--infer-market-price]'+   * Use a more compact layout like '--layout=bare'+   * 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++29.1.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++29.1.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++29.1.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++29.1.13.2 Accumulation type+...........................++How amounts should accumulate across a report's subperiods/columns.+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, cashflow,+     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*)+++File: hledger.info,  Node: Valuation type,  Next: Combining balance report types,  Prev: Accumulation type,  Up: Balance report types++29.1.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++29.1.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++29.1.14 Budget report+---------------------++The '--budget' report type is like a regular balance report, but with+two main differences:++   * Budget goals and performance percentages are also shown, in+     brackets+   * Accounts which don't have budget goals are hidden by default.++   This is useful for comparing planned and actual income, expenses,+time usage, etc.++   Periodic transaction rules are used to define budget goals.  For+example, here's a periodic rule defining monthly goals for bus travel+and food expenses:++;; Budget+~ monthly+  (expenses:bus)              $30+  (expenses:food)            $400++   After recording some actual expenses,++;; Two months worth of expenses+2017-11-01+  income                   $-1950+  expenses:bus                $35+  expenses:food:groceries    $310+  expenses:food:dining        $42+  expenses:movies             $38+  assets:bank:checking++2017-12-01+  income                   $-2100+  expenses:bus                $53+  expenses:food:groceries    $380+  expenses:food:dining        $32+  expenses:gifts             $100+  assets:bank:checking++   we can see a budget report like this:++$ hledger bal -M --budget+Budget performance in 2017-11-01..2017-12-31:++               ||                  Nov                   Dec +===============++============================================+ <unbudgeted>  || $-425                 $-565                + expenses      ||  $425 [ 99% of $430]   $565 [131% of $430] + expenses:bus  ||   $35 [117% of  $30]    $53 [177% of  $30] + expenses:food ||  $352 [ 88% of $400]   $412 [103% of $400] +---------------++--------------------------------------------+               ||     0 [  0% of $430]      0 [  0% of $430] ++   This is "goal-based budgeting"; you define goals for accounts and+periods, often recurring, and hledger shows performance relative to the+goals.  This contrasts with "envelope budgeting", which is more detailed+and strict - useful when cash is tight, but also quite a bit more work.+https://plaintextaccounting.org/Budgeting has more on this topic.++* Menu:++* Using the budget report::+* Budget date surprises::+* Selecting budget goals::+* Budgeting vs forecasting::+++File: hledger.info,  Node: Using the budget report,  Next: Budget date surprises,  Up: Budget report++29.1.14.1 Using the budget report+.................................++Historically this report has been confusing and fragile.  hledger's+version should be relatively robust and intuitive, but you may still+find surprises.  Here are more notes to help with learning and+troubleshooting.++   * In the above example, 'expenses:bus' and 'expenses:food' are shown+     because they have budget goals during the report period.++   * Their parent 'expenses' is also shown, with budget goals aggregated+     from the children.++   * The subaccounts 'expenses:food:groceries' and+     'expenses:food:dining' are not shown since they have no budget goal+     of their own, but they contribute to 'expenses:food''s actual+     amount.++   * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also+     not shown, but they contribute to 'expenses''s actual amount.++   * The other unbudgeted accounts 'income' and 'assets:bank:checking'+     are grouped as '<unbudgeted>'.++   * '--depth' or 'depth:' can be used to limit report depth in the+     usual way (but will not reveal unbudgeted subaccounts).++   * Amounts are always inclusive of subaccounts (even in '-l/--list'+     mode).++   * Numbers displayed in a -budget report will not always agree with+     the totals, because of hidden unbudgeted accounts; this is normal.+     '-E/--empty' can be used to reveal the hidden accounts.++   * In the periodic rules used for setting budget goals, unbalanced+     postings are convenient.++   * You can filter budget reports with the usual queries, eg to focus+     on particular accounts.  It's common to restrict them to just+     expenses.  (The '<unbudgeted>' account is occasionally hard to+     exclude; this is because of date surprises, discussed below.)++   * When you have multiple currencies, you may want to convert them to+     one ('-X COMM --infer-market-prices') and/or show just one at a+     time ('cur:COMM').  If you do need to show multiple currencies at+     once, '--layout bare' can be helpful.++   * You can "roll over" amounts (actual and budgeted) to the next+     period with '--cumulative'.++   See also: https://hledger.org/budgeting.html.+++File: hledger.info,  Node: Budget date surprises,  Next: Selecting budget goals,  Prev: Using the budget report,  Up: Budget report++29.1.14.2 Budget date surprises+...............................++With small data, or when starting out, some of the generated budget goal+transaction dates might fall outside the report periods.  Eg with the+following journal and report, the first period appears to have no+'expenses:food' budget.  (Also the '<unbudgeted>' account should be+excluded by the 'expenses' query, but isn't.):++~ monthly in 2020+  (expenses:food)  $500++2020-01-15+  expenses:food    $400+  assets:checking++$ hledger bal --budget expenses+Budget performance in 2020-01-15:++               ||         2020-01-15 +===============++====================+ <unbudgeted>  || $400               + expenses:food ||    0 [ 0% of $500] +---------------++--------------------+               || $400 [80% of $500] ++   In this case, the budget goal transactions are generated on first+days of of month (this can be seen with 'hledger print --forecast+tag:generated expenses').  Whereas the report period defaults to just+the 15th day of january (this can be seen from the report table's column+headings).++   To fix this kind of thing, be more explicit about the report period+(and/or the periodic rules' dates).  In this case, adding '-b 2020' does+the trick.+++File: hledger.info,  Node: Selecting budget goals,  Next: Budgeting vs forecasting,  Prev: Budget date surprises,  Up: Budget report++29.1.14.3 Selecting budget goals+................................++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 between period+expression and description), and then select from multiple budgets+defined in your journal.+++File: hledger.info,  Node: Budgeting vs forecasting,  Prev: Selecting budget goals,  Up: Budget report++29.1.14.4 Budgeting vs forecasting+..................................++'--forecast' and '--budget' both use the periodic transaction rules in+the journal to generate temporary transactions for reporting purposes.+However they are separate features - though you can use both at the same+time if you want.  Here are some differences between them:++-forecast                                -budget+--------------------------------------------------------------------------+is a general option; it enables          is a balance command option;+forecasting with all reports             it selects the balance+                                         report's budget mode+generates visible transactions which     generates invisible+appear in reports                        transactions which produce+                                         goal amounts+generates forecast transactions from     generates budget goal+after the last regular transaction, to   transactions throughout the+the end of the report period; or with    report period, optionally+an argument '--forecast=PERIODEXPR'      restricted by periods+generates them throughout the            specified in the periodic+specified period, both optionally        transaction rules+restricted by periods specified in the+periodic transaction rules+uses all periodic rules                  uses all periodic rules; or+                                         with an argument+                                         '--budget=DESCPAT' uses just+                                         the rules matched by DESCPAT+++File: hledger.info,  Node: Balance report layout,  Next: Balance report output,  Prev: Budget report,  Up: balance++29.1.15 Balance report layout+-----------------------------++The '--layout' option affects how 'balance' and the other balance-like+commands show multi-commodity amounts and commodity symbols.  It can+improve readability, for humans and/or machines (other software).  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.  (This one is currently supported only+     by the 'balance' command.)++   Here are the '--layout' modes supported by each output format 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:++* Menu:++* Wide layout::+* Tall layout::+* Bare layout::+* Tidy layout::+++File: hledger.info,  Node: Wide layout,  Next: Tall layout,  Up: Balance report layout++29.1.15.1 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 ++   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.. +++File: hledger.info,  Node: Tall layout,  Next: Bare layout,  Prev: Wide layout,  Up: Balance report layout++29.1.15.2 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 +++File: hledger.info,  Node: Bare layout,  Next: Tidy layout,  Prev: Tall layout,  Up: Balance report layout++29.1.15.3 Bare layout+.....................++Commodity symbols are kept in one column, each commodity has its own+row, amounts are bare numbers, 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"++   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).+++File: hledger.info,  Node: Tidy layout,  Prev: Bare layout,  Up: Balance report layout++29.1.15.4 Tidy layout+.....................++This produces normalised "tidy data" (see+https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)+where every variable has its own column and each row represents a single+data point.  This is the easiest kind of data for other software to+consume:++$ 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: Balance report output,  Next: Some useful balance reports,  Prev: Balance report layout,  Up: balance++29.1.16 Balance report output+-----------------------------++As noted in Output format, if you choose HTML output (by using '-O html'+or '-o somefile.html'), it will use the UTF-8 text encoding, And you can+create a 'hledger.css' file in the same directory to customise the+report's appearance.++   The HTML and FODS output formats can generate hyperlinks to a+'hledger-web' register view for each account and period.  E.g.  if your+'hledger-web' server is reachable at 'http://localhost:5000' then you+might run the 'balance' command with the extra option+'--base-url=http://localhost:5000'.  You can also produce relative+links, like '--base-url="some/path"' or '--base-url=""'.)+++File: hledger.info,  Node: Some useful balance reports,  Prev: Balance report output,  Up: balance++29.1.17 Some 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: roi,  Prev: balance,  Up: Advanced report commands++29.2 roi+========++Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on+your investments.++Flags:+     --cashflow                 show all amounts that were used to compute+                                returns+     --investment=QUERY         query to select your investment transactions+     --profit-loss=QUERY --pnl  query to select profit-and-loss or+                                appreciation/valuation transactions++   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++29.2.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++29.2.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++29.2.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: Chart commands,  Next: Data generation commands,  Prev: Advanced report commands,  Up: Top++30 Chart commands+*****************++* Menu:++* activity::+++File: hledger.info,  Node: activity,  Up: Chart commands++30.1 activity+=============++Show an ascii barchart of posting counts per interval.++Flags:+no command-specific flags++   The activity command displays an ascii histogram showing transaction+counts by day, week, month or other reporting interval (by day is the+default).  With query arguments, it counts only matched transactions.++   Examples:++$ hledger activity --quarterly+2008-01-01 **+2008-04-01 *******+2008-07-01 +2008-10-01 **+++File: hledger.info,  Node: Data generation commands,  Next: Maintenance commands,  Prev: Chart commands,  Up: Top++31 Data generation commands+***************************++* Menu:++* close::+* rewrite::+++File: hledger.info,  Node: close,  Next: rewrite,  Up: Data generation commands++31.1 close+==========++(equity)++   'close' prints several kinds of "closing" and/or "opening"+transactions, useful in various situations: migrating balances to a new+journal file, retaining earnings into equity, consolidating balances,+viewing lot costs..  Like 'print', it prints valid journal entries.  You+can copy these into your journal file(s) when you are happy with how+they look.++Flags:+     --clopen[=TAGVAL]      show closing and opening balances transactions,+                            for AL accounts by default+     --close[=TAGVAL]       show just a closing balances transaction+     --open[=TAGVAL]        show just an opening balances transaction+     --assert[=TAGVAL]      show a balance assertions transaction+     --assign[=TAGVAL]      show a balance assignments transaction+     --retain[=TAGVAL]      show a retain earnings transaction, for RX+                            accounts by default+  -x --explicit             show all amounts explicitly+     --show-costs           show amounts with different costs separately+     --interleaved          show source and destination postings together+     --assertion-type=TYPE  =, ==, =* or ==*+     --close-desc=DESC      set closing transaction's description+     --close-acct=ACCT      set closing transaction's destination account+     --open-desc=DESC       set opening transaction's description+     --open-acct=ACCT       set opening transaction's source account+     --round=TYPE           how much rounding or padding should be done when+                            displaying amounts ?+                            none - show original decimal digits,+                                   as in journal (default)+                            soft - just add or remove decimal zeros+                                   to match precision+                            hard - round posting amounts to precision+                                   (can unbalance transactions)+                            all  - also round cost amounts to precision+                                   (can unbalance transactions)++   'close' has six modes, selected by choosing one of the mode flags+('--close' is the default).  They all do much the same operation, but+with different defaults, useful in different situations.++* Menu:++* close --clopen::+* close --close::+* close --open::+* close --assert::+* close --assign::+* close --retain::+* close customisation::+* close and balance assertions::+* close examples::+++File: hledger.info,  Node: close --clopen,  Next: close --close,  Up: close++31.1.1 close -clopen+--------------------++This is useful if migrating balances to a new journal file at the start+of a new year.  It prints a "closing balances" transaction that zeroes+out account balances (Asset and Liability accounts, by default), and an+opposite "opening balances" transaction that restores them again.+Typically, you would run++hledger close --clopen -e NEWYEAR >> $LEDGER_FILE++   and then move the opening transaction from the old file to the new+file (and probably also update your LEDGER_FILE environment variable).++   Why might you do this ?  If your reports are fast, you may not need+it.  But at some point you will probably want to partition your data by+time, for performance or data integrity or regulatory reasons.  A new+file or set of files per year is common.  Then, having each file/fileset+"bookended" with opening and closing balance transactions will allow you+to freely pick and choose which files to read - just the current year,+any past year, any sequence of years, or all of them - while showing+correct account balances in each case.  The earliest opening balances+transaction sets correct starting balances, and any later+closing/opening pairs will harmlessly cancel each other out.++   The balances will be transferred to and from 'equity:opening/closing+balances' by default.  You can override this by using '--close-acct'+and/or '--open-acct'.++   You can select a different set of accounts to close/open by providing+an account query.  Eg to add Equity accounts, provide arguments like+'assets liabilities equity' or 'type:ALE'.  When migrating to a new+file, you'll usually want to bring along the AL or ALE accounts, but not+the RX accounts (Revenue, Expense).++   Assertions will be added indicating and checking the new balances of+the closed/opened accounts.++   The generated transactions will have a 'clopen:' tag.  If the main+journal's base file name contains a number (eg a year number), the tag's+value will be that base file name with the number incremented.  Or you+can choose the tag value yourself, by using '--clopen=TAGVAL'.+++File: hledger.info,  Node: close --close,  Next: close --open,  Prev: close --clopen,  Up: close++31.1.2 close -close+-------------------++This prints just the closing balances transaction of '--clopen'.  It is+the default if you don't specify a mode.++   More customisation options are described below.  Among other things,+you can use 'close --close' to generate a transaction moving the+balances from any set of accounts, to a different account.  (If you need+to move just a portion of the balance, see hledger-move.)+++File: hledger.info,  Node: close --open,  Next: close --assert,  Prev: close --close,  Up: close++31.1.3 close -open+------------------++This prints just the opening balances transaction of '--clopen'.  (It is+similar to Ledger's equity command.)+++File: hledger.info,  Node: close --assert,  Next: close --assign,  Prev: close --open,  Up: close++31.1.4 close -assert+--------------------++This prints a transaction that asserts the account balances as they are+on the end date (and adds an 'assert:' tag).  It could be useful as+documention and to guard against changes.+++File: hledger.info,  Node: close --assign,  Next: close --retain,  Prev: close --assert,  Up: close++31.1.5 close -assign+--------------------++This prints a transaction that assigns the account balances as they are+on the end date (and adds an "assign:" tag).  Unlike balance assertions,+assignments will post changes to balances as needed to reach the+specified amounts.++   This is another way to set starting balances when migrating to a new+file, and it will set them correctly even in the presence of earlier+files which do not have a closing balances transaction.  However, it can+hide errors, and disturb the accounting equation, so '--clopen' is+usually recommended.+++File: hledger.info,  Node: close --retain,  Next: close customisation,  Prev: close --assign,  Up: close++31.1.6 close -retain+--------------------++This is like '--close', but it closes Revenue and Expense account+balances by default.  They will be transferred to 'equity:retained+earnings', or another account specified with '--close-acct'.++   Revenues and expenses correspond to changes in equity.  They are+categorised separately for reporting purposes, but traditionally at the+end of each accounting period, businesses consolidate them into equity,+This is called "retaining earnings", or "closing the books".++   In personal accounting, there's not much reason to do this, and most+people don't.  (One reason to do it is to help the 'balancesheetequity'+report show a zero total, demonstrating that the accounting equation+(A-L=E) is satisfied.)+++File: hledger.info,  Node: close customisation,  Next: close and balance assertions,  Prev: close --retain,  Up: close++31.1.7 close customisation+--------------------------++In all modes, the following things can be overridden:++   * the accounts to be closed/opened, with account query arguments+   * the balancing account, with '--close-acct=ACCT' and/or+     '--open-acct=ACCT'+   * the transaction descriptions, with '--close-desc=DESC' and+     '--open-desc=DESC'+   * the transaction's tag value, with a '--MODE=NEW' option argument+   * the closing/opening dates, with '-e OPENDATE'++   By default, the closing date is yesterday, or the journal's end date,+whichever is later; and the opening date is always one day after the+closing date.  You can change these by specifying a report end date; the+closing date will be the last day of the report period.  Eg '-e 2024'+means "close on 2023-12-31, open on 2024-01-01".++   With '--x/--explicit', the balancing 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 '--interleaved', each individual transfer is shown with source+and destination postings next to each other (perhaps useful for+troubleshooting).++   With '--show-costs', balances' costs are also shown, with different+costs kept separate.  This may generate very large journal entries, if+you have many currency conversions or investment transactions.  'close+--show-costs' is currently the best way to view investment lots with+hledger.  (To move or dispose of lots, see the more capable+'hledger-move' script.)+++File: hledger.info,  Node: close and balance assertions,  Next: close examples,  Prev: close customisation,  Up: close++31.1.8 close and balance assertions+-----------------------------------++'close' adds balance assertions verifying that the accounts have been+reset to zero in a closing transaction or restored to their previous+balances in an opening transaction.  These provide useful error+checking, but you can ignore them temporarily with '-I', or remove them+if you prefer.++   Single-commodity, subaccount-exclusive balance assertions ('=') are+generated by default.  This can be changed with '--assertion-type='==*''+(eg).++   When running 'close' you should probably avoid using '-C', '-R',+'status:' (filtering by status or realness) or '--auto' (generating+postings), since the generated balance assertions would then require+these.++   Transactions with multiple dates (eg posting dates) spanning the file+boundary also can 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 this you can transfer the money to and from a temporary+account, 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: close examples,  Prev: close and balance assertions,  Up: close++31.1.9 close examples+---------------------++* Menu:++* Retain earnings::+* Migrate balances to a new file::+* More detailed close examples::+++File: hledger.info,  Node: Retain earnings,  Next: Migrate balances to a new file,  Up: close examples++31.1.9.1 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++   After this, to see 2022's revenues and expenses you must exclude the+retain earnings transaction:++$ hledger -f 2022.journal is not:desc:'retain earnings'+++File: hledger.info,  Node: Migrate balances to a new file,  Next: More detailed close examples,  Prev: Retain earnings,  Up: close examples++31.1.9.2 Migrate balances to a new file+.......................................++Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:++$ hledger close --clopen -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++   After this, to see 2022's end-of-year balances you must exclude the+closing balances transaction:++$ hledger -f 2022.journal bs not:desc:'closing balances'++   For more flexibility, it helps to tag closing and opening+transactions with eg 'clopen:NEWYEAR', then you can ensure correct+balances by excluding all opening/closing transactions except the first,+like so:++$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'+$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:clopen=2021 or not tag:clopen'+$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:clopen=2022 or not tag:clopen'+$ hledger bs -Y -f 2021.j                     expr:'tag:clopen=2021 or not tag:clopen'+$ hledger bs -Y -f 2022.j                     expr:'tag:clopen=2022 or not tag:clopen'+$ hledger bs -Y -f 2023.j                     # unclosed file, no query needed+++File: hledger.info,  Node: More detailed close examples,  Prev: Migrate balances to a new file,  Up: close examples++31.1.9.3 More detailed close examples+.....................................++See examples/multi-year.+++File: hledger.info,  Node: rewrite,  Prev: close,  Up: Data generation commands++31.2 rewrite+============++Print all transactions, rewriting the postings of matched transactions.+For now the only rewrite available is adding new postings, like print+-auto.++Flags:+     --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be+                                    parenthesised. AMTEXPR is either a literal+                                    amount, or *N which means the transaction's+                                    first matched amount multiplied by N (a+                                    decimal number). Two spaces separate ACCT+                                    and AMTEXPR.+     --diff                         generate diff suitable as an input for+                                    patch tool++   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++31.2.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++31.2.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++31.2.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: Maintenance commands,  Next: PART 5 COMMON TASKS,  Prev: Data generation commands,  Up: Top++32 Maintenance commands+***********************++* Menu:++* check::+* diff::+* test::+++File: hledger.info,  Node: check,  Next: diff,  Up: Maintenance commands++32.1 check+==========++Check for various kinds of errors in your data.++Flags:+no command-specific flags++   hledger provides a number of built-in correctness checks to help+validate your data and prevent errors.  Some are run automatically, some+when you enable '--strict' mode; or you can run any of them on demand by+providing them as arguments to the 'check' command.  'check' produces no+output and a zero exit code if all is well.  Eg:++hledger check                      # run basic checks+hledger check -s                   # run basic and strict checks+hledger check ordereddates payees  # run basic checks and two others++   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.  Generally, they are+performed in the order they are shown here (and only the first failure+is reported).++* Menu:++* Basic checks::+* Strict checks::+* Other checks::+* Custom checks::+++File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check++32.1.1 Basic checks+-------------------++These important checks are performed by default, by almost all hledger+commands:++   * *parseable* - data files are in a supported format, with no syntax+     errors and no invalid include directives.  This ensures that all+     files exist and are readable.++   * *autobalanced* - all transactions are balanced, after inferring+     missing amounts and conversion costs where possible, and then+     converting to cost.  This ensures that each individual transaction+     is well formed.++   * *assertions* - all balance assertions in the journal are passing.+     Balance assertions are like canaries in your journal, they catch+     many problems.  They can get in the way sometimes; you can disable+     them temporarily with '-I'/'--ignore-assertions' (unless overridden+     with '-s'/'--strict' or 'hledger check assertions').+++File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check++32.1.2 Strict checks+--------------------++These additional checks are performed by any command when the+'-s'/'--strict' flag is used (strict mode).  Strict mode always enables+the balance assertions check, also.  These provide extra error-catching+power when you are serious about keeping your data clean and free of+typos:++   * *balanced* - like 'autobalanced', but in conversion transactions,+     costs must be written explicitly.  This ensures some redundancy in+     the entry, which helps prevent typos.++   * *commodities* - all commodity symbols used must be declared.  This+     guards against mistyping or omitting commodity symbols.++   * *accounts* - all account names used must be declared.  This+     prevents the use of mis-spelled or outdated account names.+++File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check++32.1.3 Other checks+-------------------++These other checks are not wanted by everyone, but can be run using the+'check' command:++   * *ordereddates* - within each file, transactions are ordered by+     date.  This is a simple and effective error catcher, and you should+     use it.  Alas!  not everyone wants it.  If you do, use 'hledger+     check -s ordereddates'.  When enabled, this check is performed+     early, before balance assertions (because copy-pasted dates are+     often the root cause of balance assertion failures).++   * *payees* - all payees used by transactions must be declared.  This+     will force you to always use known/declared payee names.  For most+     people this is a bit too restrictive.++   * *tags* - all tags used by transactions must be declared.  This+     prevents mistyped tag names.++   * *recentassertions* - all accounts with balance assertions must have+     a balance assertion within the last 7 days before their latest+     posting.  This encourages you to add balance assertions fairly+     regularly for your active asset/liability accounts, which in turn+     should encourage you to check and reconcile with their real world+     balances fairly regularly.  'close --assert' can be helpful.  (The+     older balance assertions become redundant; you can remove them+     periodically, or leave them in place, perhaps commented, as+     documentation.)++   * *uniqueleafnames* - no two accounts may have the same leaf name.+     The leaf name is the last colon-separated part of an account name,+     eg 'checking' in 'assets:bank:checking'.  This encourages you to+     keep those unique, effectively giving each account a short name+     which is easier to remember and to type in reporting commands.+++File: hledger.info,  Node: Custom checks,  Prev: Other checks,  Up: check++32.1.4 Custom checks+--------------------++You can build your own custom checks with add-on command scripts.  See+also Cookbook > Scripting.  Here are some examples from hledger/bin/:++   * *hledger-check-tagfiles* - all tag values containing / (a forward+     slash) exist as file paths++   * *hledger-check-fancyassertions* - more complex balance assertions+     are passing+++File: hledger.info,  Node: diff,  Next: test,  Prev: check,  Up: Maintenance commands++32.2 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.++Flags:+no command-specific flags++   More precisely: for each posting affecting this account in either+file, this command looks for a corresponding posting in the other file+which posts the same amount to the same account (ignoring date,+description, etc).++   Since it compares postings, not transactions, this also works when+multiple bank transactions have been combined into a single journal+entry.++   This command 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: test,  Prev: diff,  Up: Maintenance commands++32.3 test+=========++Run built-in unit tests.++Flags:+no command-specific flags++   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: Getting help,  Prev: Maintenance commands,  Up: Top++33 PART 5: COMMON TASKS+***********************++Here are some quick examples of how to do some basic tasks with hledger.+++File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Prev: PART 5 COMMON TASKS,  Up: Top++34 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: Top++35 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: Top++36 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: Top++37 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"++   When correctly configured, in a new terminal window+'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'.+++File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Setting LEDGER_FILE,  Up: Top++38 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: Top++39 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: Top++40 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: Top++41 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,  Next: BUGS,  Prev: Reporting,  Up: Top++42 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: Migrating to a new file,  Up: Top++43 BUGS+*******++We welcome bug reports in the hledger issue tracker (shortcut:+https://bugs.hledger.org), or on the hledger chat or 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++43.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).  On Windows,+     '$env:LEDGER_FILE' should show it.+   * 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: Top208+Node: PART 1 USER INTERFACE4360+Node: Input4499+Node: Text encoding5591+Node: Data formats6448+Node: Standard input8172+Node: Multiple files8561+Node: Strict mode9298+Node: Commands10132+Node: Add-on commands11318+Node: Options12536+Node: Special characters19110+Node: Escaping shell special characters20060+Node: Escaping on Windows21304+Node: Escaping regular expression special characters22037+Node: Escaping add-on arguments23024+Node: Escaping in other situations24053+Node: Using a wild card25012+Node: Unicode characters25391+Node: Regular expressions27055+Node: hledger's regular expressions30314+Node: Argument files31955+Node: Config files32658+Node: Shell completions35811+Node: Output36300+Node: Output destination36491+Node: Output format37049+Node: Text output38835+Node: Box-drawing characters39814+Node: Colour40314+Node: Paging40900+Node: HTML output42426+Node: CSV / TSV output42880+Node: FODS output43134+Node: Beancount output43938+Node: Beancount account names45393+Node: Beancount commodity names45934+Node: Beancount virtual postings46581+Node: Beancount metadata46897+Node: Beancount costs47677+Node: Beancount operating currency48093+Node: SQL output48543+Node: JSON output49334+Node: Commodity styles50151+Node: Debug output51038+Node: Environment51870+Node: PART 2 DATA FORMATS52527+Node: Journal52670+Node: Journal cheatsheet55148+Node: Comments61362+Node: Transactions62306+Node: Dates63443+Node: Simple dates63595+Node: Posting dates64211+Node: Status65298+Node: Code67064+Node: Description67399+Node: Payee and note68086+Node: Transaction comments69177+Node: Postings69693+Node: Debits and credits70856+Node: The two space delimiter71466+Node: Account names72031+Node: Amounts73835+Node: Decimal marks74864+Node: Digit group marks75968+Node: Commodity76603+Node: Costs77720+Node: Balance assertions79972+Node: Assertions and ordering81235+Node: Assertions and multiple included files81963+Node: Assertions and multiple -f files82723+Node: Assertions and costs83365+Node: Assertions and commodities84015+Node: Assertions and subaccounts85674+Node: Assertions and status86334+Node: Assertions and virtual postings86754+Node: Assertions and auto postings87119+Node: Assertions and precision87994+Node: Posting comments88445+Node: Transaction balancing88985+Node: Tags90987+Node: Querying with tags92281+Node: Displaying tags93080+Node: When to use tags ?93476+Node: Tag names94140+Node: Special tags94693+Node: Directives96258+Node: Directives and multiple files97715+Node: Directive effects98660+Node: account directive101816+Node: Account comments103266+Node: Account error checking103925+Node: Account display order105462+Node: Account types106660+Node: alias directive110434+Node: Basic aliases111645+Node: Regex aliases112520+Node: Combining aliases113567+Node: Aliases and multiple files115021+Node: end aliases directive115804+Node: Aliases can generate bad account names116172+Node: Aliases and account types117005+Node: commodity directive117897+Node: Commodity directive syntax119484+Node: Commodity error checking121133+Node: decimal-mark directive121608+Node: include directive122187+Node: P directive123263+Node: payee directive124297+Node: tag directive124919+Node: Periodic transactions125531+Node: Periodic rule syntax127685+Node: Periodic rules and relative dates128508+Node: Two spaces between period expression and description!129285+Node: Auto postings130246+Node: Auto postings and multiple files133406+Node: Auto postings and dates133811+Node: Auto postings and transaction balancing / inferred amounts / balance assertions134252+Node: Auto posting tags135098+Node: Auto postings on forecast transactions only135993+Node: Other syntax136463+Node: Balance assignments137235+Node: Balance assignments and costs138763+Node: Balance assignments and multiple files139185+Node: Bracketed posting dates139608+Node: D directive140306+Node: apply account directive142079+Node: Y directive142946+Node: Secondary dates143934+Node: Star comments145419+Node: Valuation expressions146111+Node: Virtual postings146410+Node: Other Ledger directives148034+Node: Other cost/lot notations148796+Node: CSV151637+Node: CSV rules cheatsheet153733+Node: source155760+Node: encoding156760+Node: separator157699+Node: skip158352+Node: date-format159002+Node: timezone159845+Node: newest-first160971+Node: intra-day-reversed161684+Node: decimal-mark162284+Node: fields list162764+Node: Field assignment164572+Node: Field names165791+Node: date field167123+Node: date2 field167287+Node: status field167482+Node: code field167672+Node: description field167860+Node: comment field168077+Node: account field168634+Node: amount field169352+Node: currency field172191+Node: balance field172599+Node: if block173122+Node: Matchers174649+Node: Multiple matchers176639+Node: Match groups177447+Node: if table178340+Node: balance-type180403+Node: include181230+Node: Working with CSV181799+Node: Rapid feedback182351+Node: Valid CSV182934+Node: File Extension183810+Node: Reading CSV from standard input184545+Node: Reading multiple CSV files184931+Node: Reading files specified by rule185407+Node: Valid transactions186804+Node: Deduplicating importing187629+Node: Setting amounts188858+Node: Amount signs191385+Node: Setting currency/commodity192450+Node: Amount decimal places193826+Node: Referencing other fields195083+Node: How CSV rules are evaluated196191+Node: Well factored rules197859+Node: CSV rules examples198349+Node: Bank of Ireland198547+Node: Coinbase200144+Node: Amazon201327+Node: Paypal203169+Node: Timeclock210919+Node: Timedot213188+Node: Timedot examples216665+Node: PART 3 REPORTING CONCEPTS218942+Node: Time periods219106+Node: Report start & end date219379+Node: Smart dates220855+Node: Report intervals222798+Node: Date adjustments223372+Node: Start date adjustment223592+Node: End date adjustment224495+Node: Period headings225240+Node: Period expressions226173+Node: Period expressions with a report interval228078+Node: More complex report intervals228526+Node: Multiple weekday intervals230642+Node: Depth231653+Node: Queries233488+Node: Query types235186+Node: acct query235603+Node: amt query235914+Node: code query236531+Node: cur query236726+Node: desc query237332+Node: date query237515+Node: date2 query237911+Node: depth query238202+Node: expr query238538+Node: not query238919+Node: note query239259+Node: payee query239525+Node: real query239806+Node: status query240011+Node: type query240251+Node: tag query240784+Node: Combining query terms241413+Node: Queries and command options243153+Node: Queries and account aliases243607+Node: Queries and valuation243932+Node: Pivoting244294+Node: Generating data246570+Node: Forecasting248370+Node: --forecast249026+Node: Inspecting forecast transactions250127+Node: Forecast reports251460+Node: Forecast tags252569+Node: Forecast period in detail253189+Node: Forecast troubleshooting254277+Node: Budgeting255348+Node: Amount formatting255908+Node: Commodity display style256152+Node: Rounding257993+Node: Trailing decimal marks258598+Node: Amount parseability259531+Node: Cost reporting261112+Node: Recording costs261943+Node: Reporting at cost263670+Node: Equity conversion postings264435+Node: Inferring equity conversion postings267080+Node: Combining costs and equity conversion postings268222+Node: Requirements for detecting equity conversion postings269447+Node: Infer cost and equity by default ?270969+Node: Value reporting271406+Node: -V Value272342+Node: -X Value in specified commodity272669+Node: Valuation date273019+Node: Finding market price273979+Node: --infer-market-prices market prices from transactions275359+Node: Valuation commodity278403+Node: --value Flexible valuation279836+Node: Valuation examples281679+Node: Interaction of valuation and queries283811+Node: Effect of valuation on reports284528+Node: PART 4 COMMANDS292426+Node: Help commands294642+Node: commands294828+Node: demo295036+Node: help296270+Node: User interface commands297975+Node: repl298186+Node: Examples300656+Node: run301214+Node: Examples 2303631+Node: ui304655+Node: web304792+Node: Data entry commands304920+Node: add305118+Node: import307573+Node: Import preview308607+Node: Overlap detection309555+Node: First import312441+Node: Importing balance assignments313636+Node: Import and commodity styles314691+Node: Import special cases315129+Node: Basic report commands316464+Node: accounts316765+Node: codes319638+Node: commodities320660+Node: descriptions320904+Node: files321371+Node: notes321668+Node: payees322180+Node: prices322964+Node: stats323856+Node: tags325597+Node: Standard report commands326904+Node: print327209+Node: print explicitness329950+Node: print amount style330870+Node: print parseability332108+Node: print other features333027+Node: print output format333890+Node: aregister337175+Node: aregister and posting dates341634+Node: register342535+Node: Custom register output349710+Node: balancesheet350895+Node: balancesheetequity355665+Node: cashflow360805+Node: incomestatement365367+Node: Advanced report commands369965+Node: balance370173+Node: balance features375349+Node: Simple balance report377425+Node: Balance report line format379235+Node: Filtered balance report381595+Node: List or tree mode382114+Node: Depth limiting383627+Node: Dropping top-level accounts384394+Node: Showing declared accounts384904+Node: Sorting by amount385634+Node: Percentages386471+Node: Multi-period balance report387178+Node: Balance change end balance389930+Node: Balance report types391567+Node: Calculation type392246+Node: Accumulation type392950+Node: Valuation type394051+Node: Combining balance report types395240+Node: Budget report397272+Node: Using the budget report399577+Node: Budget date surprises401853+Node: Selecting budget goals403217+Node: Budgeting vs forecasting404165+Node: Balance report layout405842+Node: Wide layout407047+Node: Tall layout409452+Node: Bare layout410758+Node: Tidy layout412822+Node: Balance report output414366+Node: Some useful balance reports415181+Node: roi416441+Node: Spaces and special characters in --inv and --pnl418688+Node: Semantics of --inv and --pnl419414+Node: IRR and TWR explained421501+Node: Chart commands424912+Node: activity425093+Node: Data generation commands425590+Node: close425796+Node: close --clopen428359+Node: close --close430533+Node: close --open431057+Node: close --assert431307+Node: close --assign431634+Node: close --retain432313+Node: close customisation433170+Node: close and balance assertions434814+Node: close examples436336+Node: Retain earnings436573+Node: Migrate balances to a new file437076+Node: More detailed close examples438438+Node: rewrite438660+Node: Re-write rules in a file441232+Node: Diff output format442542+Node: rewrite vs print --auto443815+Node: Maintenance commands444529+Node: check444738+Node: Basic checks445820+Node: Strict checks446773+Node: Other checks447648+Node: Custom checks449503+Node: diff449958+Node: test451165+Node: PART 5 COMMON TASKS452037+Node: Getting help452270+Node: Constructing command lines453179+Node: Starting a journal file454017+Node: Setting LEDGER_FILE455401+Node: Setting opening balances456659+Node: Recording transactions459981+Node: Reconciling460706+Node: Reporting463095+Node: Migrating to a new file467209+Node: BUGS467658+Node: Troubleshooting468623  End Tag Table