hledger 1.34 → 1.40

raw patch · 52 files changed

+24946/−21749 lines, 52 filesdep ~hledger-libdep ~megaparsecPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: hledger-lib, megaparsec

API changes (from Hackage documentation)

Files

• CHANGES.md +113/−2
• Hledger/Cli.hs +441/−163
• Hledger/Cli/CliOptions.hs +91/−70
• Hledger/Cli/Commands/Accounts.txt +14/−1
• Hledger/Cli/Commands/Activity.txt +2/−1
• Hledger/Cli/Commands/Add.txt +2/−3
• Hledger/Cli/Commands/Aregister.hs +1/−1
• Hledger/Cli/Commands/Aregister.txt +12/−1
• Hledger/Cli/Commands/Balance.hs +591/−139
• Hledger/Cli/Commands/Balance.txt +63/−8
• Hledger/Cli/Commands/Balancesheet.txt +44/−1
• Hledger/Cli/Commands/Balancesheetequity.txt +44/−1
• Hledger/Cli/Commands/Cashflow.txt +43/−1
• Hledger/Cli/Commands/Check.txt +2/−1
• Hledger/Cli/Commands/Close.txt +29/−1
• Hledger/Cli/Commands/Codes.txt +2/−1
• Hledger/Cli/Commands/Commodities.txt +2/−1
• Hledger/Cli/Commands/Demo.txt +3/−1
• Hledger/Cli/Commands/Descriptions.txt +2/−1
• Hledger/Cli/Commands/Diff.txt +14/−10
• Hledger/Cli/Commands/Files.hs +2/−2
• Hledger/Cli/Commands/Files.txt +2/−1
• Hledger/Cli/Commands/Help.txt +5/−1
• Hledger/Cli/Commands/Import.txt +3/−1
• Hledger/Cli/Commands/Incomestatement.txt +43/−1
• Hledger/Cli/Commands/Notes.txt +2/−1
• Hledger/Cli/Commands/Payees.txt +3/−1
• Hledger/Cli/Commands/Prices.txt +4/−2
• Hledger/Cli/Commands/Print.hs +1/−1
• Hledger/Cli/Commands/Print.txt +22/−1
• Hledger/Cli/Commands/Register.hs +5/−2
• Hledger/Cli/Commands/Register.txt +28/−1
• Hledger/Cli/Commands/Rewrite.txt +9/−1
• Hledger/Cli/Commands/Roi.hs +2/−2
• Hledger/Cli/Commands/Roi.txt +6/−1
• Hledger/Cli/Commands/Stats.txt +3/−1
• Hledger/Cli/Commands/Tags.txt +4/−1
• Hledger/Cli/Commands/Test.txt +2/−1
• Hledger/Cli/CompoundBalanceCommand.hs +100/−48
• Hledger/Cli/Conf.hs +220/−0
• Hledger/Cli/DocFiles.hs +8/−3
• embeddedfiles/hledger-import.md +1/−1
• embeddedfiles/hledger-ui.1 +37/−32
• embeddedfiles/hledger-ui.info +60/−55
• embeddedfiles/hledger-ui.txt +121/−117
• embeddedfiles/hledger-web.1 +9/−8
• embeddedfiles/hledger-web.info +24/−23
• embeddedfiles/hledger-web.txt +9/−8
• embeddedfiles/hledger.1 +678/−76
• embeddedfiles/hledger.info +12360/−11809
• embeddedfiles/hledger.txt +9647/−9129
• hledger.cabal +11/−10

@@ -7,12 +7,12 @@  Breaking changes +Fixes+ Features  Improvements -Fixes- Docs  Scripts/addons@@ -23,6 +23,116 @@ User-visible changes in the hledger command line tool and library.  +# 1.40 2024-09-09++Fixes++- Account tags (and type declarations) declared in multiple files are now combined correctly. [#2202]++- Several kinds of report interval now choose a better start date:+  - `every Nth day of month from DATE` with periodic transactions [#2218]+  - `every M/D from DATE`+  - `every Nth WEEKDAY from DATE`++- The balance commands' html output no longer repeats the "Total" and+  "Net" headings when the totals row has multiple lines.+  And the layout has been improved and made more consistent with the+  text output.++- The `--tldr` flag now also works with the `tealdeer` tldr client.++Features++- You can now save command line options in a [config file](https://hledger.org/hledger.html#config-files),+  to be added to your hledger commands either on demand or automatically.+  (This supersedes the older arguments files feature.)++  This much-requested new feature has pros and cons, and is experimental;+  your testing and feedback is welcome.+  It changes the nature of hledger somewhat, which I have marked by+  giving this release a more memorable version number (1.40).++- The balance commands can now output in FODS format, an XML spreadsheet+  file format readable by LibreOffice. (Henning Thielemann)++- The `register` report can now be sorted by date, account, amount,+  absolute amount, description, or a combination of these. (Michael Rees, [#2211])++Improvements++- Command line processing has been overhauled and should be more robust+  in certain cases, with tweaked error messages and debug output.+  Command-specific flags can now optionally appear before the command name.+  (Though writing them afterward is usually more readable.+   Addon-specific flags must still come last, after `--`.)++- The `--rules-file` option has been renamed to `--rules`.+  The old spelling is still supported as a hidden option.++- Weekly reports' week headings are now more compact, especially in+  single-year balance reports. ([#2204], Victor Mihalache)++- The `balance` command with no report interval, and also `balance --budget`,+  now support html output. (Henning Thielemann)++- In balance commands' html and csv output, "Total:" and "Net:" headings+  are now capitalised consistently.++- `bs`/`cf`/`is` reports now show the report interval in their title.++- The balance commands' text output with the `--pretty` flag now shows+  an outer table border and inter-column borders.++- The `check recentassertions` error message is now more readable.++- Timedot format now allows comment lines to be indented.++- When running the `tldr-node-client` client, auto-update of the tldr+  database is now suppressed.++- When running a tldr client fails, the warning now mentions the required+  `--render` flag. [#2201]++- The error message for unsupported regular expressions like `(?:foo)` has+  been improved.++- `--debug` has moved to "General help flags", making it available in+  more situations.++- Some verbose debug output from command line processing has been demoted to level 2.++- Parsing timedot files now gives debug output at level 9.++- Allow doclayout 0.5.++Docs++- The hledger/hledger-ui/hledger-web manuals now list all command options as shown by `--help`.+- Added an example config file, `hledger.conf.sample`.+- The `diff` and `prices` commands' help layout has been improved.+- `add`'s doc described the effect of `D` wrongly, now fixed.+- Date adjustments: rewrites and corrections+- Period headings: added+- Input: clarify that multiple -f options are allowed+- Scripts and add-ons: edits, list add-ons again+- Timeclock: edits, fix `ti`/`to` scripts+- Fixed "hledger and Ledger" links [hledger_site#112]+- examples/csv: Monzo CSV rules added+- examples/csv: Tiller CSV rules added+- examples/csv: Nordea CSV rules added (Arto Jonsson)++Scripts/addons++- `bin/bashrc` updates; add years, eachyear scripts+- `bin/hledger-simplebal`: ignore config files+- `bin/hledger-script-example`: explain shebang commands better+- `bin/hledger-register-max`: update/fix++++API++ # 1.34 2024-06-01  Breaking changes@@ -114,6 +224,7 @@  [#2005]: https://github.com/simonmichael/hledger/issues/2005 [#2198]: https://github.com/simonmichael/hledger/issues/2198+  # 1.33.1 2024-05-02 

@@ -19,7 +19,7 @@ == About  hledger - a fast, reliable, user-friendly plain text accounting tool.-Copyright (c) 2007-2023 Simon Michael <simon@joyful.com> and contributors+Copyright (c) 2007-2024 Simon Michael <simon@joyful.com> and contributors Released under GPL version 3 or later.  hledger is a Haskell rewrite of John Wiegley's "ledger".  @@ -64,10 +64,12 @@  -} -{-# LANGUAGE LambdaCase #-}- {-# OPTIONS_GHC -Wno-unrecognised-pragmas #-} {-# HLINT ignore "Unused LANGUAGE pragma" #-}+{-# LANGUAGE LambdaCase #-}+{-# LANGUAGE MultiWayIf #-}+{-# LANGUAGE RecordWildCards #-}+{-# LANGUAGE TupleSections #-}  module Hledger.Cli (   main,@@ -75,38 +77,52 @@   argsToCliOpts,   -- * Re-exports   module Hledger.Cli.CliOptions,+  module Hledger.Cli.Conf,   module Hledger.Cli.Commands,   module Hledger.Cli.DocFiles,   module Hledger.Cli.Utils,   module Hledger.Cli.Version,   module Hledger,   -- ** System.Console.CmdArgs.Explicit-  module System.Console.CmdArgs.Explicit,+  module CmdArgsWithoutName ) where -import Control.Monad (when)+import Control.Monad (when, unless)+import Data.Bifunctor (second)+import Data.Char (isDigit)+import Data.Either (isRight)+import Data.Function ((&))+import Data.Functor ((<&>)) import Data.List import qualified Data.List.NonEmpty as NE+import Data.Maybe (isJust)+import Data.Text (pack, Text) import Data.Time.Clock.POSIX (getPOSIXTime) import Safe-import System.Console.CmdArgs.Explicit hiding (Name) -- don't clash with hledger-ui-import qualified System.Console.CmdArgs.Explicit as C+import System.Console.CmdArgs.Explicit+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) import Text.Printf  import Hledger import Hledger.Cli.CliOptions+import Hledger.Cli.Conf import Hledger.Cli.Commands import Hledger.Cli.DocFiles import Hledger.Cli.Utils import Hledger.Cli.Version  +verboseDebugLevel = 8+ -- | The overall cmdargs mode describing hledger's command-line options and subcommands.+-- The names of known addons are provided so they too can be recognised as commands. mainmode addons = defMode {   modeNames = [progname ++ " [COMMAND]"]  ,modeArgs = ([], Just $ argsFlag "[ARGS]")@@ -124,12 +140,10 @@  ,modeGroupFlags = Group {      -- flags in named groups: (keep synced with Hledger.Cli.CliOptions.highlightHelp)      groupNamed = cligeneralflagsgroups1-     -- flags in the unnamed group, shown last:-    ,groupUnnamed = []-     -- flags handled but not shown in the help:-    ,groupHidden =-        [detailedversionflag]-        -- ++ inputflags -- included here so they'll not raise a confusing error if present with no COMMAND+     -- flags in the unnamed group, shown last: (keep synced with dropUnsupportedOpts)+    ,groupUnnamed = confflags+     -- other flags handled but not shown in help:+    ,groupHidden = hiddenflagsformainmode     }  ,modeHelpSuffix = []     -- "Examples:" :@@ -142,194 +156,458 @@     -- ," help [MANUAL]           show any of the hledger manuals in various formats"     -- ]  }+-- A dummy mode just for parsing --conf/--no-conf flags.+confflagsmode = defMode{+   modeGroupFlags=Group [] confflags []+  ,modeArgs = ([], Just $ argsFlag "")+  } --- | Let's go!+------------------------------------------------------------------------------+-- | hledger CLI's main procedure.+--+-- Here we will parse the command line, read any config file,+-- and search for hledger-* addon executables in the user's PATH,+-- then choose the appropriate builtin operation or addon operation to run,+-- then run it in the right way, usually reading input data (eg a journal) first.+--+-- When making a CLI usable and robust with main command, builtin subcommands,+-- various kinds of addon commands, and config files that add general and+-- command-specific options, while balancing circular dependencies, environment,+-- idioms, legacy, and libraries with their own requirements and limitations:+-- things get crazy, and there is a tradeoff against complexity and bug risk.+-- We try to provide the most intuitive, expressive and robust CLI that's feasible+-- while keeping the CLI processing below sufficiently comprehensible, troubleshootable,+-- and tested. It's an ongoing quest.+-- See also: Hledger.Cli.CliOptions, cli.test, addons.test, --debug and --debug=8.+--+-- Probably the biggest source of complexity here is that cmdargs can't parse+-- a command line containing undeclared flags, but this arises often with our+-- addon commands and builtin/custom commands which haven't implemented all options,+-- so we have to work hard to work around this.+-- https://github.com/ndmitchell/cmdargs/issues/36 is the wishlist issue;+-- implementing that would simplify hledger's CLI processing a lot.+-- main :: IO () main = withGhcDebug' $ do-  when (ghcDebugMode == GDPauseAtStart) $ ghcDebugPause' +  -- let's go!+  let+    -- Trace helpers. These always trace to stderr, even when running `hledger ui`;+    -- that's ok as conf is a hledger cli feature for now.+    dbgIO, dbgIO1, dbgIO2 :: Show a => String -> a -> IO ()  -- this signature is needed+    dbgIO  = ptraceAtIO verboseDebugLevel+    dbgIO1 = ptraceAtIO 1+    dbgIO2 = ptraceAtIO 2++  dbgIO "running" prognameandversion+   starttime <- getPOSIXTime -  -- try to encourage user's $PAGER to properly display ANSI+  -- give ghc-debug a chance to take control+  when (ghcDebugMode == GDPauseAtStart) $ ghcDebugPause'++  -- try to encourage user's $PAGER to display ANSI when supported   when useColorOnStdout setupPager -  -- Choose and run the appropriate internal or external command based-  -- on the raw command-line arguments, cmdarg's interpretation of-  -- same, and hledger-* executables in the user's PATH. A somewhat-  -- complex mishmash of cmdargs and custom processing, hence all the-  -- debugging support and tests. See also Hledger.Cli.CliOptions and-  -- command-line.test.+  -- Search PATH for addon commands. Exclude any that match builtin command names.+  addons <- hledgerAddons <&> filter (not . (`elem` builtinCommandNames) . dropExtension) -  -- some preliminary (imperfect) argument parsing to supplement cmdargs-  args <- getArgs >>= expandArgsAt+  ---------------------------------------------------------------+  -- Preliminary command line parsing.++  -- Do some argument preprocessing to help cmdargs+  cliargs <- getArgs+    >>= expandArgsAt         -- interpolate @ARGFILEs+    <&> replaceNumericFlags  -- convert -NUM to --depth=NUM   let-    args'                = moveFlagsAfterCommand $ replaceNumericFlags args-    isFlag               = ("-" `isPrefixOf`)-    isNonEmptyNonFlag s  = not (isFlag s) && not (null s)-    rawcmd               = headDef "" $ takeWhile isNonEmptyNonFlag args'-    isNullCommand        = null rawcmd-    (argsbeforecmd, argsaftercmd') = break (==rawcmd) args-    argsaftercmd         = drop 1 argsaftercmd'-    dbgIO :: Show a => String -> a -> IO ()-    dbgIO = ptraceAtIO 8+    (clicmdarg, cliargswithoutcmd, cliargswithcmdfirst) = moveFlagsAfterCommand cliargs+    cliargswithcmdfirstwithoutclispecific = dropCliSpecificOpts cliargswithcmdfirst+    (cliargsbeforecmd, cliargsaftercmd) = second (drop 1) $ break (==clicmdarg) cliargs+  dbgIO "cli args" cliargs+  dbg1IO "cli args with command first, if any" cliargswithcmdfirst+  dbgIO "command argument found"   clicmdarg+  dbgIO "cli args before command"  cliargsbeforecmd+  dbgIO "cli args after command"   cliargsaftercmd -  dbgIO "running" prognameandversion-  dbgIO "raw args" args-  dbgIO "raw args rearranged for cmdargs" args'-  dbgIO "raw command is probably" rawcmd-  dbgIO "raw args before command" argsbeforecmd-  dbgIO "raw args after command" argsaftercmd+  -- Now try to identify the full subcommand name, so we can look for+  -- command-specific options in config files (clicmdarg may be only an abbreviation).+  -- For this do a preliminary cmdargs parse of the arguments with cli-specific options removed.+  -- If no command was provided, or if the command line contains a bad flag+  -- or a wrongly present/missing flag argument, cmd will be "".+  let+    rawopts0 = cmdargsParse+      "to get command name"+      (mainmode addons)+      cliargswithcmdfirstwithoutclispecific+    cmd = stringopt "command" rawopts0+      -- XXX better error message when cmdargs fails (eg spaced/quoted/malformed flag values) ?+    nocmdprovided  = null clicmdarg+    badcmdprovided = null cmd && not nocmdprovided+    isaddoncmd = not (null cmd) && cmd `elem` addons+    -- isbuiltincmd = cmd `elem` builtinCommandNames+    mcmdmodeaction = findBuiltinCommand cmd+    effectivemode = maybe (mainmode []) fst mcmdmodeaction+  dbgIO "cli args with command first and no cli-specific opts" cliargswithcmdfirstwithoutclispecific+  dbgIO1 "command found" cmd+  dbgIO "no command provided" nocmdprovided+  dbgIO "bad command provided" badcmdprovided+  dbgIO "is addon command" isaddoncmd -  -- Search PATH for add-ons, excluding any that match built-in command names-  addons' <- hledgerAddons-  let addons = filter (not . (`elem` builtinCommandNames) . dropExtension) addons'+  ---------------------------------------------------------------+  -- Read extra options from a config file. -  -- parse arguments with cmdargs-  opts' <- argsToCliOpts args addons-  let opts = opts'{progstarttime_=starttime}+  -- Identify any --conf/--no-conf options.+  -- For this parse with cmdargs again, this time with just the args that look conf-related.+  let cliconfargs = dropUnsupportedOpts confflagsmode cliargswithoutcmd+  dbgIO "cli args without command" cliargswithoutcmd+  -- dbgIO "cli conf args" cliconfargs+  let rawopts1 = cmdargsParse "to get conf file" confflagsmode cliconfargs -  -- select an action and prepare to run it+  -- Read extra general and command-specific args/opts from the config file if found.+  -- Ignore any general opts or cli-specific opts not known to be supported by the command.+  (conf, mconffile) <- getConf rawopts1   let-    cmd               = command_ opts -- the full matched internal or external command name, if any-    isInternalCommand = cmd `elem` builtinCommandNames -- not (null cmd) && not (cmd `elem` addons)-    isExternalCommand = not (null cmd) && cmd `elem` addons -- probably-    isBadCommand      = not (null rawcmd) && null cmd-    printUsage        = pager $ showModeUsage (mainmode addons) ++ "\n"-    badCommandError   = error' ("command "++rawcmd++" is not recognized, run with no command to see a list") >> exitFailure  -- PARTIAL:-    helpFlag       = boolopt "help"    $ rawopts_ opts-    tldrFlag       = boolopt "tldr"    $ rawopts_ opts-    infoFlag       = boolopt "info"    $ rawopts_ opts-    manFlag        = boolopt "man"     $ rawopts_ opts-    versionFlag    = boolopt "version" $ rawopts_ opts-    f `orShowHelp` mode1-      | helpFlag = pager $ showModeUsage mode1 ++ "\n"-      | tldrFlag = runTldrForPage $ maybe "hledger" (("hledger-"<>)) $ headMay $ modeNames mode1-      | infoFlag = runInfoForTopic "hledger" (headMay $ modeNames mode1)-      | manFlag  = runManForTopic "hledger" (headMay $ modeNames mode1)-      | otherwise   = f-      -- where-      --   lastdocflag-  dbgIO "processed opts" opts-  dbgIO "command matched" cmd-  dbgIO "isNullCommand" isNullCommand-  dbgIO "isInternalCommand" isInternalCommand-  dbgIO "isExternalCommand" isExternalCommand-  dbgIO "isBadCommand" isBadCommand-  dbgIO "period from opts" (period_ . _rsReportOpts $ reportspec_ opts)-  dbgIO "interval from opts" (interval_ . _rsReportOpts $ reportspec_ opts)-  dbgIO "query from opts & args" (_rsQuery $ reportspec_ opts)+    genargsfromconf = confLookup "general" conf+    addoncmdssupportinggenopts = ["ui", "web"]  -- addons known to support hledger general options+    supportedgenargsfromconf+      | cmd `elem` addoncmdssupportinggenopts =+          [a | a <- genargsfromconf, not $ any (`isPrefixOf` a) addoncmdssupportinggenopts]+      | isaddoncmd = []+      | otherwise  = dropUnsupportedOpts effectivemode genargsfromconf+    excludedgenargsfromconf = genargsfromconf \\ supportedgenargsfromconf+    cmdargsfromconf+      | null cmd  = []+      | otherwise = confLookup cmd conf & if isaddoncmd then ("--":) else id+  when (isJust mconffile) $ do+    dbgIO1 "using extra general args from config file" genargsfromconf+    unless (null excludedgenargsfromconf) $+      dbgIO1 "excluded general args from config file, not supported by this command" excludedgenargsfromconf+    dbgIO1 "using extra command args from config file" cmdargsfromconf++  ---------------------------------------------------------------+  -- Combine cli and config file args and parse with cmdargs.+  -- A bad flag or flag argument will cause the program to exit with an error here.+   let-    runHledgerCommand-      -- high priority flags and situations. -h, then --help, then --tldr, then --info, then --man are highest priority.-      | isNullCommand && helpFlag = dbgIO "" "-h/--help with no command, showing general help" >> printUsage-      | isNullCommand && tldrFlag = dbgIO "" "--tldr with no command, showing general tldr page" >> runTldrForPage "hledger"-      | isNullCommand && infoFlag = dbgIO "" "--info with no command, showing general info manual" >> runInfoForTopic "hledger" Nothing-      | isNullCommand && manFlag  = dbgIO "" "--man with no command, showing general man page" >> runManForTopic "hledger" Nothing-      | versionFlag && not (isExternalCommand || helpFlag || tldrFlag || infoFlag || manFlag) = putStrLn prognameandversion-      | isNullCommand             = dbgIO "" "no command, showing commands list" >> printCommandsList prognameandversion addons-      | isBadCommand              = badCommandError+    finalargs =  -- (avoid breaking vs code haskell highlighting..)+      (if null clicmdarg then [] else [clicmdarg]) <> supportedgenargsfromconf <> cmdargsfromconf <> cliargswithoutcmd+      & replaceNumericFlags                -- convert any -NUM opts from the config file+  -- finalargs' <- expandArgsAt finalargs  -- expand @ARGFILEs in the config file ? don't bother+  let rawopts = cmdargsParse "to get options" (mainmode addons) finalargs -      -- builtin commands-      | Just (cmdmode, cmdaction) <- findBuiltinCommand cmd =-        (case True of-           -- these commands should not require or read the journal-          _ | cmd `elem` ["demo","help","test"] ->-              cmdaction opts $ error' $ cmd++" tried to read the journal but is not supposed to"-          -- these commands should create the journal if missing-          _ | cmd `elem` ["add","import"] -> do-              ensureJournalFileExists . NE.head =<< journalFilePathFromOpts opts-              withJournalDo opts (cmdaction opts)-          -- other commands read the journal and should fail if it's missing-          _ -> withJournalDo opts (cmdaction opts)-        )-        `orShowHelp` cmdmode+  ---------------------------------------------------------------+  -- Finally, select an action and run it. -      -- addon commands-      | isExternalCommand = do-          let externalargs = argsbeforecmd ++ filter (/="--") argsaftercmd-          let shellcmd = printf "%s-%s %s" progname cmd (unwords' externalargs) :: String-          dbgIO "external command selected" cmd-          dbgIO "external command arguments" (map quoteIfNeeded externalargs)-          dbgIO "running shell command" shellcmd-          system shellcmd >>= exitWith+  -- We check for the help/doc/version flags first, since they are a high priority.+  -- (A perfectionist might think they should be so high priority that adding -h+  -- to an invalid command line would show help. But cmdargs tends to fail first,+  -- preventing this, and trying to detect them without cmdargs, and always do the+  -- right thing with builtin commands and addon commands, gets much too complicated.)+  let+    helpFlag    = boolopt "help"    rawopts+    tldrFlag    = boolopt "tldr"    rawopts+    infoFlag    = boolopt "info"    rawopts+    manFlag     = boolopt "man"     rawopts+    versionFlag = boolopt "version" rawopts -      -- deprecated commands-      -- cmd == "convert"         = error' (modeHelp oldconvertmode) >> exitFailure+  if+    -- no command and a help/doc flag found - show general help/docs+    | nocmdprovided && helpFlag -> pager $ showModeUsage (mainmode []) ++ "\n"+    | nocmdprovided && tldrFlag -> runTldrForPage  "hledger"+    | nocmdprovided && infoFlag -> runInfoForTopic "hledger" Nothing+    | nocmdprovided && manFlag  -> runManForTopic  "hledger" Nothing -      -- shouldn't reach here-      | otherwise                = usageError ("could not understand the arguments "++show args) >> exitFailure+    -- --version flag found and none of these other conditions - show version+    | versionFlag && not (isaddoncmd || helpFlag || tldrFlag || infoFlag || manFlag) -> putStrLn prognameandversion -  -- do it-  runHledgerCommand+    -- there's a command argument, but it's bad - show error+    | badcmdprovided -> error' $ "command "++clicmdarg++" is not recognized, run with no command to see a list" +    -- no command found, nothing else to do - show the commands list+    | nocmdprovided -> dbgIO "" "no command, showing commands list" >> printCommandsList prognameandversion addons++    -- builtin command found+    | Just (cmdmode, cmdaction) <- mcmdmodeaction -> do++      -- 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+        mcmdname = headMay $ modeNames cmdmode+        tldrpagename = maybe "hledger" (("hledger-"<>)) mcmdname++      -- run the builtin command according to its type+      if+        -- help/doc flag - show command help/docs+        | helpFlag  -> pager $ showModeUsage cmdmode ++ "\n"+        | tldrFlag  -> runTldrForPage tldrpagename+        | infoFlag  -> runInfoForTopic "hledger" mcmdname+        | manFlag   -> runManForTopic "hledger"  mcmdname++        -- builtin command which should not require or read the journal - run it+        | cmd `elem` ["demo","help","test"] ->+          cmdaction opts $ error' $ cmd++" tried to read the journal but is not supposed to"++        -- builtin command which should create the journal if missing - do that and run it+        | cmd `elem` ["add","import"] -> do+          ensureJournalFileExists . NE.head =<< journalFilePathFromOpts opts+          withJournalDo opts (cmdaction opts)++        -- all other builtin commands - read the journal and if successful run the command with it+        | otherwise -> withJournalDo opts $ cmdaction opts++    -- external addon command found - run it,+    -- passing any cli arguments written after the command name+    -- and any command-specific opts from the config file.+    -- Any "--" arguments, which sometimes must be used in the command line+    -- to hide addon-specific opts from hledger's cmdargs parsing,+    -- (and are also accepted in the config file, though not required there),+    -- will be removed.+    -- (hledger does not preserve -- arguments)+    -- Arguments written before the command name, and general opts from the config file,+    -- are not passed since we can't be sure they're supported.+    | isaddoncmd -> do+        let+          addonargs0 = filter (/="--") $ supportedgenargsfromconf <> cmdargsfromconf <> cliargswithoutcmd+          addonargs = dropCliSpecificOpts addonargs0+          shellcmd = printf "%s-%s %s" progname cmd (unwords' addonargs) :: String+        dbgIO "addon command selected" cmd+        dbgIO "addon command arguments after removing cli-specific opts" (map quoteIfNeeded addonargs)+        dbgIO1 "running addon" shellcmd+        system shellcmd >>= exitWith++    -- deprecated command found+    -- cmd == "convert" = error' (modeHelp oldconvertmode) >> exitFailure++    -- something else (shouldn't happen) - show an error +    | otherwise -> usageError $+        "could not understand the arguments "++show finalargs+        <> if null genargsfromconf then "" else "\ngeneral arguments added from config file: "++show genargsfromconf+        <> if null cmdargsfromconf then "" else "\ncommand arguments added from config file: "++show cmdargsfromconf++  -- And we're done.+  -- Give ghc-debug a final chance to take control.   when (ghcDebugMode == GDPauseAtEnd) $ ghcDebugPause' --- | Parse hledger CLI options from these command line arguments and--- add-on command names, or raise any error.+------------------------------------------------------------------------------+++-- | A helper for addons/scripts: this parses hledger CliOpts from these+-- command line arguments and add-on command names, roughly how hledger main does.+-- If option parsing/validating fails, it exits the program with usageError.+-- Unlike main, this does not read extra args from a config file+-- or search for addons; to do those things, mimic the code in main for now. argsToCliOpts :: [String] -> [String] -> IO CliOpts argsToCliOpts args addons = do   let-    args'        = moveFlagsAfterCommand $ replaceNumericFlags args-    cmdargsopts  = either usageError id $ C.process (mainmode addons) args'-  rawOptsToCliOpts cmdargsopts+    (_, _, args0) = moveFlagsAfterCommand args+    args1 = replaceNumericFlags args0+    rawopts = cmdargsParse "to get options" (mainmode addons) args1+  rawOptsToCliOpts rawopts --- | A hacky workaround for cmdargs not accepting flags before the--- subcommand name: try to detect and move such flags after the--- command.  This allows the user to put them in either position.--- The order of options is not preserved, but that should be ok.+-- | Parse the given command line arguments/options with the given cmdargs mode,+-- after adding values to any valueless --debug flags,+-- with debug logging showing the given description of this parsing pass+-- (useful when cmdargsParse is called more than once).+-- If parsing fails, exit the program with an informative error message.+cmdargsParse :: String -> Mode RawOpts -> [String] -> RawOpts+cmdargsParse desc m args0 = process m (ensureDebugFlagHasVal args0)+  & either+    (\e -> error' $ e <> " while parsing these args " <> desc <> ": " <> unwords (map quoteIfNeeded args0))+    (traceOrLogAt verboseDebugLevel ("cmdargs: parsing " <> desc <> ": " <> show args0))++-- | 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. ----- Since we're not parsing flags as precisely as cmdargs here, this is--- imperfect. We make a decent effort to:--- - move all no-argument help/input/report flags--- - move all required-argument help/input/report flags along with their values, space-separated or not--- - ensure --debug has an argument (because.. "or this all goes to hell")--- - not confuse things further or cause misleading errors.-moveFlagsAfterCommand :: [String] -> [String]-moveFlagsAfterCommand args = moveArgs $ ensureDebugHasArg args+-- 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.+--+-- We make a best-effort attempt like so:+-- whether a flag argument (- or -- followed by a non-space character and zero or more others),+-- and its following argument, are movable, falls into these cases, to be checked in this order:+--+-- - it exactly matches a known short or long no-value flag; move it+-- - it exactly matches a short or long requires-value flag; move it and the following argument+-- - it exactly matches a short optional-value flag; assume these don't exist or we don't have any+-- - it exactly matches a long optional-value flag; assume there's no value, move it+-- - it begins with a short requires-value flag; the value is joined to it, move it+-- - 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.+--   But it should be fairly robust now, being aware of all builtin flags.+--+-- - 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).+--+-- - Long flags should be spelled in full; abbreviated long flags may not be moved.+--+-- - 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 moveFlagArgs (args, []) of+    ([],as)                      -> ("", as, as)+    (unmoved@(('-':_):_), moved) -> ("", as, as) where as = unmoved<>moved+    (cmdarg:unmoved, moved)      -> (cmdarg, as, cmdarg:as) where as = unmoved<>moved   where-    moveArgs args1 = insertFlagsAfterCommand $ moveArgs' (args1, [])+    moveFlagArgs :: ([String], [String]) -> ([String], [String])+    moveFlagArgs ((a:b:cs), moved)+      | isMovableFlagArg a b == 2 = moveFlagArgs (cs, moved++[a,b])+      | isMovableFlagArg a b == 1 = moveFlagArgs (b:cs, moved++[a])+      | otherwise                 = (a:b:cs, moved)       where-        -- -f FILE ..., --alias ALIAS ...-        moveArgs' ((f:v:a:as), flags) | isMovableReqArgFlag f, isValue v       = moveArgs' (a:as, flags ++ [f,v])-        -- -fFILE ..., --alias=ALIAS ...-        moveArgs' ((fv:a:as), flags)  | isMovableArgFlagAndValue fv            = moveArgs' (a:as, flags ++ [fv])-        -- -f(missing arg)-        moveArgs' ((f:a:as), flags)   | isMovableReqArgFlag f, not (isValue a) = moveArgs' (a:as, flags ++ [f])-        -- -h ..., --version ...-        moveArgs' ((f:a:as), flags)   | isMovableNoArgFlag f                   = moveArgs' (a:as, flags ++ [f])-        -- anything else-        moveArgs' (as, flags) = (as, flags)+        -- Is this a short or long flag argument that should be moved,+        -- and is its following argument a value that also should be moved ?+        -- Returns:+        -- 0 (not a flag; don't move this argument)+        -- 1 (a valueless flag, or a long flag with joined argument, or multiple joined valueless short flags; move this argument)+        -- 2 (a short or long flag with a value in the next argument; move this and next argument).+        isMovableFlagArg :: String -> String -> Int+        isMovableFlagArg a1 a2+          | a1 `elem` noValFlagArgs  = 1  -- short or long no-val flag+          | a1 == "--debug" && not (isDebugValue a2) = 1  --debug without a value+          | a1 `elem` reqValFlagArgs = 2  -- short or long req-val flag (or --debug) with a separate value+          | a1 `elem` optValFlagArgs = 1  -- long (or short ?) opt-val flag, assume no value+          | any (`isPrefixOf` a1) shortReqValFlagArgs = 1  -- short req-val flag with a joined value+               -- or possibly multiple joined valueless short flags, we won't move those correctly+          | any (`isPrefixOf` a1) longReqValFlagArgs_ = 1  -- long req-val flag (or --debug) with a joined value+          | any (`isPrefixOf` a1) longOptValFlagArgs_ = 1  -- long opt-val flag with a joined value+          -- | isLongFlagArg a1 && any (takeWhile (/='=') `isPrefixOf`) longReqValFlagArgs_ ... -- try to move abbreviated long flags ?+          | isFlagArg a1 = 1    -- an addon flag (or mistyped flag) we don't know, assume no value or value is joined+          | otherwise = 0    -- not a flag+    moveFlagArgs (as, moved)       = (as, moved) -        insertFlagsAfterCommand ([],           flags) = flags-        insertFlagsAfterCommand (command1:args2, flags) = [command1] ++ flags ++ args2+-- Is this string a valid --debug value ?+isDebugValue s = isRight $ parsewith isdebugvalp $ pack s+  where isdebugvalp = optional (char '-') >> takeWhile1P Nothing isDigit <* eof :: TextParser m Text -isMovableNoArgFlag a  = "-" `isPrefixOf` a && dropWhile (=='-') a `elem` optargflagstomove ++ noargflagstomove+-- Flag arguments are command line arguments beginning with - or --+-- (followed by a short of long flag name, and possibly joined short flags or a joined value).+isFlagArg, isShortFlagArg, isLongFlagArg :: String -> Bool+isFlagArg a = isShortFlagArg a || isLongFlagArg a -isMovableReqArgFlag a = "-" `isPrefixOf` a && dropWhile (=='-') a `elem` reqargflagstomove+isShortFlagArg ('-':c:_) = c /= '-'+isShortFlagArg _         = False -isMovableArgFlagAndValue ('-':'-':a:as) = case break (== '=') (a:as) of-    (f:fs,_:_) -> (f:fs) `elem` optargflagstomove ++ reqargflagstomove-    _          -> False-isMovableArgFlagAndValue ('-':shortflag:_:_) = [shortflag] `elem` reqargflagstomove-isMovableArgFlagAndValue _ = False+isLongFlagArg ('-':'-':_:_) = True+isLongFlagArg _             = False -isValue "-"     = True-isValue ('-':_) = False-isValue _       = True+-- | Add the leading hyphen(s) to a short or long flag name.+toFlagArg :: Name -> String+toFlagArg f = if length f == 1 then "-"++f else "--"++f -flagstomove = inputflags ++ reportflags ++ helpflags-noargflagstomove  = concatMap flagNames (filter ((==FlagNone).flagInfo) flagstomove)-  -- silly special case: if someone is abbreviating --tldr, make sure it works right when written before COMMAND-  -- (not needed for --info, --man, --version since their abbreviations are ambiguous)-  ++ ["tl", "tld"]-reqargflagstomove = -- filter (/= "debug") $-                    concatMap flagNames $ filter ((==FlagReq ).flagInfo) flagstomove-optargflagstomove = concatMap flagNames $ filter (isFlagOpt   .flagInfo) flagstomove+-- | Flatten a possibly multi-named Flag to (name, FlagInfo) pairs.+toFlagInfos :: Flag RawOpts -> [(Name, FlagInfo)]+toFlagInfos f = [(n,i) | let i = flagInfo f, n <- flagNames f]++-- | Is this flag's value optional ?+isOptVal :: FlagInfo -> Bool+isOptVal = \case+  FlagOpt _     -> True+  FlagOptRare _ -> True+  _             -> False++-- | All the general flags defined in hledger's main mode.+generalFlags :: [Flag RawOpts]+generalFlags = concatMap snd groupNamed <> groupHidden <> groupUnnamed+  where Group{..} = modeGroupFlags $ mainmode []  ++-- | All the general flag names.+generalFlagNames :: [Name]+generalFlagNames = concatMap flagNames generalFlags++-- | All hledger's builtin subcommand-specific flags.+commandFlags :: [Flag RawOpts]+commandFlags = concatMap (groupUnnamed.modeGroupFlags) commandModes   where-    isFlagOpt = \case-      FlagOpt     _ -> True-      FlagOptRare _ -> True-      _             -> False+    commandModes = concatMap snd groupNamed <> groupUnnamed <> groupHidden+      where Group{..} = modeGroupModes $ mainmode [] +-- | The names of general options flags, grouped by whether they expect a value.+-- There may be some overlaps with command flag names.+noValGeneralFlagNames, reqValGeneralFlagNames, optValGeneralFlagNames :: [Name]+noValGeneralFlagNames  = [f | (f,i) <- concatMap toFlagInfos generalFlags, i == FlagNone]+reqValGeneralFlagNames = [f | (f,i) <- concatMap toFlagInfos generalFlags, i == FlagReq]+optValGeneralFlagNames = [f | (f,i) <- concatMap toFlagInfos generalFlags, isOptVal i]++-- | The names of builtin subcommand flags, grouped by whether they expect a value.+-- There may be some overlaps with general flag names.+noValCommandFlagNames, reqValCommandFlagNames, optValCommandFlagNames :: [Name]+noValCommandFlagNames  = [f | (f,i) <- concatMap toFlagInfos commandFlags, i == FlagNone]+reqValCommandFlagNames = [f | (f,i) <- concatMap toFlagInfos commandFlags, i == FlagReq]+optValCommandFlagNames = [f | (f,i) <- concatMap toFlagInfos commandFlags, isOptVal i]++-- All flag arguments understood by hledger cli and builtin commands, grouped by whether they expect a value.+-- Any command flags which have the same name as a general flag are excluded.+noValFlagArgs  = map toFlagArg $ noValGeneralFlagNames  `union` (noValCommandFlagNames  \\ generalFlagNames)+reqValFlagArgs = map toFlagArg $ reqValGeneralFlagNames `union` (reqValCommandFlagNames \\ generalFlagNames)+optValFlagArgs = map toFlagArg $ optValGeneralFlagNames `union` (optValCommandFlagNames \\ generalFlagNames)++-- Short flag args that expect a required value.+shortReqValFlagArgs = filter isShortFlagArg reqValFlagArgs++-- Long flag args that expect a required value, with = appended.+longReqValFlagArgs_ = map (++"=") $ filter isLongFlagArg reqValFlagArgs++-- Long flag args that expect an optional value, with = appended.+longOptValFlagArgs_ = map (++"=") $ filter isLongFlagArg optValFlagArgs ++ ["--debug"]++-- Drop any arguments which look like cli-specific options (--no-conf, --conf CONFFILE, etc.)+-- Keep synced with mainmode's groupUnnamed.+dropCliSpecificOpts :: [String] -> [String]+dropCliSpecificOpts = \case+  "--conf":_:as                   -> dropCliSpecificOpts as+  a:as | "--conf=" `isPrefixOf` a -> dropCliSpecificOpts as+  "--no-conf":as                  -> dropCliSpecificOpts as+  "-n":as                         -> dropCliSpecificOpts as+  a:as                            -> a:dropCliSpecificOpts as+  []                              -> []++-- | Given a hledger cmdargs mode and a list of command line arguments, try to drop any of the+-- arguments which seem to be flags not supported by this mode. Also drop their values if any.+--+-- >>> dropUnsupportedOpts confflagsmode ["--debug","1","-f","file"]+-- []+-- >>> dropUnsupportedOpts confflagsmode ["--debug","-f","file"]+-- []+dropUnsupportedOpts :: Mode RawOpts -> [String] -> [String]+dropUnsupportedOpts m = \case+  []   -> []+  "--debug":a:as | not (m `supportsFlag` "debug") ->+    go $ if isDebugValue a then as else a:as+  a:as -> if+    | isLongFlagArg a,+      let f = takeWhile (/='=') a,+      let as' = if isReqValFlagArg f && '=' `notElem` a then drop 1 as else as+      -> if m `supportsFlag` f then a : go as else go as'+    | isShortFlagArg a,+      let f = take 2 a,+      let as' = if isReqValFlagArg f && length a == 2 then drop 1 as else as+      -> if m `supportsFlag` f then a : go as else go as'+    | otherwise -> a : dropUnsupportedOpts m as+  where+    go = dropUnsupportedOpts m+    isReqValFlagArg = (`elem` reqValFlagArgs)+    supportsFlag m1 flagarg = elem flagarg $ map toFlagArg $ concatMap flagNames $ modeAndSubmodeFlags m1++-- | Get all the flags defined in a mode or its immediate subcommands,+-- whether in named, unnamed or hidden groups.+-- Does not recurse into subsubcommands,+-- and does not deduplicate (general flags are repeated on all hledger subcommands).+modeAndSubmodeFlags :: Mode a -> [Flag a]+modeAndSubmodeFlags m@Mode{modeGroupModes=Group{..}} =+  modeFlags m <> concatMap modeFlags (concatMap snd groupNamed <> groupUnnamed <> groupHidden)  -- unit tests (tests_Hledger_Cli) are defined in Hledger.Cli.Commands

@@ -13,6 +13,7 @@ {-# LANGUAGE TemplateHaskell     #-} {-# LANGUAGE TypeFamilies        #-} {-# LANGUAGE TypeOperators       #-}+{-# LANGUAGE NamedFieldPuns #-}  module Hledger.Cli.CliOptions (   progname,@@ -23,9 +24,10 @@   reportflags,   helpflags,   helpflagstitle,-  detailedversionflag,   flattreeflags,+  confflags,   hiddenflags,+  hiddenflagsformainmode,   -- outputflags,   outputFormatFlag,   outputFileFlag,@@ -47,7 +49,6 @@   withAliases,   likelyExecutablesInPath,   hledgerExecutablesInPath,-  ensureDebugHasArg,    -- * CLI options   CliOpts(..),@@ -58,7 +59,8 @@   rawOptsToCliOpts,   outputFormats,   defaultOutputFormat,-  CommandDoc,+  CommandHelpStr,+  parseCommandHelp,    -- possibly these should move into argsToCliOpts   -- * CLI option accessors@@ -70,6 +72,7 @@   defaultWidth,   -- widthFromOpts,   replaceNumericFlags,+  ensureDebugFlagHasVal,   -- | For register:   registerWidthsFromOpts, @@ -87,7 +90,7 @@ import Control.Monad (when) import Data.Char import Data.Default-import Data.Either (fromRight, isRight)+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.Split (splitOn)@@ -141,11 +144,11 @@ -- common cmdargs flags -- keep synced with flag docs in doc/common.m4 --- | Common input-related flags: --file, --rules-file, --alias...+-- | Common input-related flags: --file, --rules, --conf, --alias... inputflags :: [Flag RawOpts] inputflags = [-   flagReq  ["file","f"]      (\s opts -> Right $ setopt "file" s opts) "FILE" "Read data from FILE, or from stdin if -. Can be specified more than once. If not specified, reads from $LEDGER_FILE or $HOME/.hledger.journal."-  ,flagReq  ["rules-file"]    (\s opts -> Right $ setopt "rules-file" s opts) "RULEFILE" "Use conversion rules from this file for converting subsequent CSV/SSV/TSV files. If not specified, uses FILE.rules for each such FILE."+   flagReq  ["file","f"]      (\s opts -> Right $ setopt "file" s opts) "[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."+  ,flagReq  ["rules"]         (\s opts -> Right $ setopt "rules" s opts) "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."  -- see also hiddenflags    ,flagReq  ["alias"]         (\s opts -> Right $ setopt "alias" s opts)  "A=B|/RGX/=RPL" "transform account names from A to B, or by replacing regular expression matches"   ,flagNone ["auto"]          (setboolopt "auto") "generate extra postings by applying auto posting rules (\"=\") to all transactions"@@ -191,7 +194,7 @@  ,flagReq  ["period","p"]    (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set begin date, end date, and/or report interval, with more flexibility"  ,flagReq  ["today"]         (\s opts -> Right $ setopt "today" s opts) "DATE" "override today's date (affects relative dates)"  ,flagNone ["date2"]         (setboolopt "date2") "match/use secondary dates instead (deprecated)"  -- see also hiddenflags- +   -- status/realness/depth/zero filters  ,flagNone ["unmarked","U"]  (setboolopt "unmarked") "include only unmarked postings/transactions"  ,flagNone ["pending","P"]   (setboolopt "pending")  "include only pending postings/transactions"@@ -223,7 +226,7 @@    -- general output-related  ,flagReq ["commodity-style", "c"] (\s opts -> Right $ setopt "commodity-style" s opts) "S"-    "Override a commodity's display style.\nEg: -c '$1000.' or -c '1.000,00 EUR'"  +    "Override a commodity's display style.\nEg: -c '$1000.' or -c '1.000,00 EUR'"   -- This has special support in hledger-lib:colorOption, keep synced  ,flagReq  ["color","colour"] (\s opts -> Right $ setopt "color" s opts) "YN"    (unlines@@ -232,11 +235,6 @@      ])  ,flagOpt "yes" ["pretty"] (\s opts -> Right $ setopt "pretty" s opts) "YN"     "Use box-drawing characters in text output? Can be\n'y'/'yes' or 'n'/'no'.\nIf YN is specified, the equals is required."-- -- flagOpt would be more correct for --debug, showing --debug[=LVL] rather than --debug=[LVL].- -- But because we handle --debug specially, flagReq also works, and it does not need =, removing a source of confusion.- -- ,flagOpt "1" ["debug"] (\s opts -> Right $ setopt "debug" s opts) "LVL" "show debug output (levels 1-9, default: 1)"- ,flagReq  ["debug"]    (\s opts -> Right $ setopt "debug" s opts) "[1-9]" "show this level of debug output (default: 1)"  ]  helpflags :: [Flag RawOpts]@@ -246,13 +244,12 @@  ,flagNone ["info"]     (setboolopt "info")    "show the manual with info"  ,flagNone ["man"]      (setboolopt "man")     "show the manual with man"  ,flagNone ["version"]  (setboolopt "version") "show version information"+  -- flagOpt would be more correct for --debug, showing --debug[=LVL] rather than --debug=[LVL] in help.+  -- But flagReq plus special handling in Cli.hs makes the = optional, removing a source of confusion.+ ,flagReq  ["debug"]    (\s opts -> Right $ setopt "debug" s opts) "[1-9]" "show this much debug output (default: 1)"  ] -- XXX why are these duplicated in defCommandMode below ? --- | A hidden flag just for the hledger executable.-detailedversionflag :: Flag RawOpts-detailedversionflag = flagNone ["version+"] (setboolopt "version+") "show version information with extra detail"- -- | Flags for selecting flat/tree mode, used for reports organised by account. -- With a True argument, shows some extra help about inclusive/exclusive amounts. flattreeflags :: Bool -> [Flag RawOpts]@@ -264,17 +261,28 @@     ("show accounts as a tree" ++ if showamounthelp then ". Amounts include subaccount amounts." else "")   ] --- | Common flags that are accepted but not shown in --help,--- such as --effective, --aux-date.-hiddenflags :: [Flag RawOpts]-hiddenflags = [+-- | hledger CLI's --conf/--no-conf flags.+confflags = [+   flagReq ["conf"] (\s opts -> Right $ setopt "conf" s opts) "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)."+  ,flagNone ["no-conf","n"] (setboolopt "no-conf") "ignore any config file"+  ]++-- | Common legacy flags that are accepted but not shown in --help.+hiddenflagsformainmode :: [Flag RawOpts]+hiddenflagsformainmode = [    flagNone ["effective","aux-date"] (setboolopt "date2") "Ledger-compatible aliases for --date2"   ,flagNone ["infer-value"]          (setboolopt "infer-market-prices") "legacy flag that was renamed"   ,flagNone ["pretty-tables"]        (setopt "pretty" "always") "legacy flag that was renamed"   ,flagNone ["anon"]                 (setboolopt "anon") "deprecated, renamed to --obfuscate"  -- #2133, handled by anonymiseByOpts   ,flagNone ["obfuscate"]            (setboolopt "obfuscate") "slightly obfuscate hledger's output. Warning, does not give privacy. Formerly --anon."  -- #2133, handled by maybeObfuscate+  ,flagReq  ["rules-file"]           (\s opts -> Right $ setopt "rules" s opts) "RULESFILE" "was renamed to --rules"   ] +-- Subcommands/addons add the conf flags, so they won't error if those are present.+hiddenflags :: [Flag RawOpts]+hiddenflags = hiddenflagsformainmode ++ confflags+ -- | Common output-related flags: --output-file, --output-format...  -- outputflags = [outputFormatFlag, outputFileFlag]@@ -396,23 +404,33 @@      }   } +-- | A command's name, optional official abbreviation, and help preamble & postamble,+-- as a specially formatted single string. Used to generate the CLI help, and also+-- the command's doc in the hledger manual. See parseCommandHelp for the format.+type CommandHelpStr = String+ -- | A command's documentation. Used both as part of CLI help, and as--- part of the hledger manual. See parseCommandDoc.-type CommandDoc = String+-- part of the hledger manual. See parseCommandHelpStr.+data CommandHelp = CommandHelp {+   cmdName           :: Name        -- the official command name+  ,mcmdShortName     :: Maybe Name  -- optional official name abbreviation+  ,cmdHelpPreamble   :: String      -- help preamble, shown before flags help+  ,cmdHelpPostamble ::  String      -- help postamble, shown after flags help+} deriving (Show)  -- | Build a cmdarg mode for a hledger command, -- from a help template and flag/argument specifications. -- Reduces boilerplate a little, though the complicated cmdargs -- flag and argument specs are still required.-hledgerCommandMode :: CommandDoc -> [Flag RawOpts] -> [(String, [Flag RawOpts])]+hledgerCommandMode :: CommandHelpStr -> [Flag RawOpts] -> [(String, [Flag RawOpts])]   -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts-hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =-  case parseCommandDoc doc of-    Nothing -> error' $ "Could not parse command doc:\n"++doc++"\n"  -- PARTIAL:-    Just (names, shorthelp, longhelplines) ->-      (defCommandMode names) {-         modeHelp        = shorthelp-        ,modeHelpSuffix  = longhelplines+hledgerCommandMode helpstr unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =+  case parseCommandHelp helpstr of+    Nothing -> error' $ "Could not parse command doc:\n"++helpstr++"\n"  -- PARTIAL:+    Just CommandHelp{cmdName, mcmdShortName, cmdHelpPreamble, cmdHelpPostamble} ->+      (defCommandMode $ cmdName : maybeToList mcmdShortName) {+         modeHelp        = cmdHelpPreamble+        ,modeHelpSuffix  = lines cmdHelpPostamble         ,modeGroupFlags  = Group {             groupUnnamed = unnamedflaggroup            ,groupNamed   = namedflaggroups@@ -421,36 +439,45 @@         ,modeArgs        = argsdescr         } --- | Parse a command's help text file (Somecommand.txt).--- This is generated from the command's doc source file (Somecommand.md)--- by Shake cmdhelp, and it should be formatted as follows:+-- | Parse a command's help text file (@Somecommand.txt@).+-- This is generated by @Shake cmdhelp@ from the command's doc source (@Somecommand.md@).+-- @Somecommand.md@ should be formatted as follows: ----- - First line: main command name+-- - First line: main command name, as a markdown heading. ----- - Third line: command aliases, comma-and-space separated, in parentheses (optional)+-- - Optional parenthesised third line: an official abbreviation of the command name. ----- - Fifth or third line to the line containing just _FLAGS (or end of file): short command help+-- - From third or fifth line to a @```flags@ line: the command help preamble.+--   Usually one sentence or paragraph; any blank lines will not be rendered. ----- - Any lines after _FLAGS: long command help+-- - A fenced code block beginning with @```flags@, containing a @Flags:@ line,+--   followed by a snapshot of the command-specific flags help as generated by cmdargs+--   or "none" if there are no command-specific flags.+--   This should contain no blank lines (no extra newlines in the cmdargs command mode help strings).+--   This is shown as-is in manuals, and regenerated at runtime for --help output. ----- The CLI --help displays the short help, the flags help generated by cmdargs,--- then the long help (which some day we might make optional again).--- The manual displays the short help, then the long help (but not the flags list).+-- - Any remaining lines: the command help postamble. ---parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String])-parseCommandDoc t =+-- (Note the difference between+-- @Somecommand.md@, which is the markdown source file, and+-- @Somecommand.txt@, which is the plain text file generated by @Shake cmdhelp@,+-- which this function parses.)+--+parseCommandHelp :: CommandHelpStr -> Maybe CommandHelp+parseCommandHelp t =   case lines t of     [] -> Nothing-    (l1:_:l3:ls) -> Just (cmdname:cmdaliases, shorthelp, longhelplines)+    (l1:_:l3:ls) -> Just $ CommandHelp cmdname (Just cmdalias) preamble postamble       where-        cmdname = strip l1-        (cmdaliases, rest) =+        cmdname = l1+        (cmdalias, rest) =           if "(" `isPrefixOf` l3 && ")" `isSuffixOf` l3-          then (words $ filter (/=',') $ drop 1 $ init l3, ls)+          then (drop 1 $ init l3, ls)           else ([], l3:ls)-        (shorthelpls, longhelpls) = break (== "_FLAGS") $ dropWhile (=="") rest-        shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls-        longhelplines = dropWhile null $ drop 1 longhelpls+        (preamblels, rest2) = break (== "Flags:") $ dropWhile null rest+        postamblels = dropWhile null $ dropWhile (not.null) rest2+        preamble = unlines $ reverse $ dropWhile null $ reverse preamblels+        postamble = unlines postamblels     _ -> Nothing  -- error' "misformatted command help text file"  -- | Get a mode's usage message as a nicely wrapped string.@@ -497,15 +524,6 @@ -- s `withAliases` as     = s ++ " (aliases: " ++ intercalate ", " as ++ ")"  --- help_postscript = [---   -- "DATES can be Y/M/D or smart dates like \"last month\"."---   -- ,"PATTERNS are regular"---   -- ,"expressions which filter by account name.  Prefix a pattern with desc: to"---   -- ,"filter by transaction description instead, prefix with not: to negate it."---   -- ,"When using both, not: comes last."---  ]-- -- CliOpts  -- | Command line options, used in the @hledger@ package and above.@@ -560,6 +578,15 @@     replace ('-':ds) | not (null ds) && all isDigit ds = "--depth="++ds     replace s = s +-- Convert a valueless --debug flag to one with a value.+-- See also the --debug flag definition in CliOptions.hs.+-- This makes an equals sign unnecessary with this optional-value flag.+ensureDebugFlagHasVal :: [String] -> [String]+ensureDebugFlagHasVal as = case break (=="--debug") as of+  (bs,"--debug":c:cs) | null c || not (all isDigit c) -> bs++"--debug=1" : ensureDebugFlagHasVal (c:cs)+  (bs,["--debug"])                                    -> bs++["--debug=1"]+  _                                                   -> as+ -- | Parse raw option string values to the desired final data types. -- Any relative smart dates will be converted to fixed dates based on -- today's date. Parsing failures will raise an error.@@ -569,8 +596,8 @@   currentDay <- getCurrentDay   let day = case maybestringopt "today" rawopts of               Nothing -> currentDay-              Just d  -> fromRight (error' $ "Unable to parse date \"" ++ d ++ "\"") $ -- PARTIAL:-                         fromEFDay <$> fixSmartDateStrEither' currentDay (T.pack d)+              Just d  -> either (const err) fromEFDay $ fixSmartDateStrEither' currentDay (T.pack d)+                where err = error' $ "Unable to parse date \"" ++ d ++ "\""   let iopts = rawOptsToInputOpts day rawopts   rspec <- either error' pure $ rawOptsToReportSpec day rawopts  -- PARTIAL:   mcolumns <- readMay <$> getEnvSafe "COLUMNS"@@ -650,7 +677,7 @@ getHledgerCliOpts :: Mode RawOpts -> IO CliOpts getHledgerCliOpts mode' = do   args' <- getArgs >>= expandArgsAt-  getHledgerCliOpts' mode' args' +  getHledgerCliOpts' mode' args'  -- CliOpts accessors @@ -691,7 +718,7 @@ -- | All the output formats known by any command, for outputFormatFromOpts. -- To automatically infer it from -o/--output-file, it needs to be listed here. outputFormats :: [String]-outputFormats = [defaultOutputFormat, "beancount", "csv", "json", "html", "sql", "tsv"]+outputFormats = [defaultOutputFormat, "beancount", "csv", "json", "html", "sql", "tsv", "fods"]  -- | Get the output format from the --output-format option, -- otherwise from a recognised file extension in the --output-file option,@@ -889,9 +916,3 @@ instance HasReportOpts CliOpts where     reportOpts = reportSpec.reportOpts --- | Convert an argument-less --debug flag to --debug=1 in the given arguments list.--- Used by hledger/ui/web to make their command line parsing easier somehow.-ensureDebugHasArg as = case break (=="--debug") as of-  (bs,"--debug":c:cs) | null c || not (all isDigit c) -> bs++"--debug=1":c:cs-  (bs,["--debug"])                                    -> bs++["--debug=1"]-  _                                                   -> as

@@ -2,7 +2,20 @@  List account names. -_FLAGS+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

@@ -2,7 +2,8 @@  Show an ascii barchart of posting counts per interval. -_FLAGS+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

@@ -2,7 +2,8 @@  Record new transactions with interactive prompting in the console. -_FLAGS+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@@ -26,8 +27,6 @@ -   The tab key will auto-complete whenever possible - accounts,     payees/descriptions, dates (yesterday, today, tomorrow). If the     input area is empty, it will insert the default value.--   If the journal defines a default commodity, it will be added to any-    bare numbers entered. -   A parenthesised transaction code may be entered following a date. -   Comments and tags may be entered following a description or amount. -   If you make a mistake, enter < at any prompt to go one step

@@ -29,7 +29,7 @@ import System.Console.CmdArgs.Explicit (flagNone, flagReq)  import Hledger-import Hledger.Read.CsvUtils (CSV, CsvRecord, printCSV, printTSV)+import Hledger.Write.Csv (CSV, CsvRecord, printCSV, printTSV) import Hledger.Cli.CliOptions import Hledger.Cli.Utils import Text.Tabular.AsciiWide hiding (render)

@@ -5,7 +5,18 @@ Show the transactions and running balances in one account, with each transaction on one line. -_FLAGS+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+  -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

@@ -233,51 +233,81 @@  -} -{-# LANGUAGE ExtendedDefaultRules #-}-{-# LANGUAGE NamedFieldPuns       #-} {-# LANGUAGE OverloadedStrings    #-}+{-# LANGUAGE ExtendedDefaultRules #-}  -- for lucid_+{-# LANGUAGE FlexibleContexts #-}      -- for stylesheet_+{-# LANGUAGE NamedFieldPuns       #-} {-# LANGUAGE RecordWildCards      #-} {-# LANGUAGE ScopedTypeVariables  #-} {-# LANGUAGE TemplateHaskell      #-}  module Hledger.Cli.Commands.Balance (+  -- ** balance command   balancemode  ,balance+  -- ** balance output rendering  ,balanceReportAsText  ,balanceReportAsCsv+ ,balanceReportAsSpreadsheet  ,balanceReportItemAsText  ,multiBalanceRowAsCsvText- ,multiBalanceRowAsTableText+ ,multiBalanceRowAsText  ,multiBalanceReportAsText  ,multiBalanceReportAsCsv  ,multiBalanceReportAsHtml  ,multiBalanceReportHtmlRows  ,multiBalanceReportHtmlFootRow- ,balanceReportAsTable- ,balanceReportTableAsText+ ,multiBalanceReportAsTable+ ,multiBalanceReportTableAsText+ ,multiBalanceReportAsSpreadsheet+  -- ** HTML output helpers+ ,stylesheet_+ ,styles_+ ,bold+ ,doubleborder+ ,topdoubleborder+ ,bottomdoubleborder+ ,alignright+ ,alignleft+ ,aligncenter+ ,collapse+ ,lpad+ ,rpad+ ,hpad+ ,vpad+  -- ** Tests  ,tests_Balance ) where +import Control.Arrow ((***))+import Data.Decimal (roundTo) import Data.Default (def)-import Data.List (transpose, transpose)+import Data.Function (on)+import Data.List (find, transpose, foldl')+import qualified Data.Map as Map import qualified Data.Set as S-import Data.Maybe (fromMaybe)+import Data.Maybe (catMaybes, fromMaybe)+import Data.Text (Text) import qualified Data.Text as T import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as TB import Data.Time (addDays, fromGregorian)-import System.Console.CmdArgs.Explicit as C+import System.Console.CmdArgs.Explicit as C (flagNone, flagReq, flagOpt) import Lucid as L hiding (value_) import Safe (headMay, maximumMay) import Text.Tabular.AsciiWide-    (Align(..), Cell(..), Table(..), TableOpts(..), cellWidth, concatTables,-    renderColumns, renderRowB, textCell)-import qualified Text.Tabular.AsciiWide as Tab+    (Header(..), Align(..), Properties(..), Cell(..), Table(..), TableOpts(..),+    cellWidth, concatTables, renderColumns, renderRowB, renderTableByRowsB, textCell) +import qualified System.IO as IO+ import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Utils-import Hledger.Read.CsvUtils (CSV, printCSV, printTSV)+import Hledger.Write.Csv (CSV, printCSV, printTSV)+import Hledger.Write.Ods (printFods)+import Hledger.Write.Html (printHtml)+import qualified Hledger.Write.Spreadsheet as Ods   -- | Command line options for this command.@@ -306,7 +336,7 @@     ,flagNone ["cumulative"] (setboolopt "cumulative")       "accumulate amounts from report start (specified by e.g. -b/--begin) to column end"     ,flagNone ["historical","H"] (setboolopt "historical")-      "accumulate amounts from journal start to column end (includes postings before report start date)\n "+      "accumulate amounts from journal start to column end (includes postings before report start date)"     ]     -- other options specific to this command:     ++ flattreeflags True ++@@ -332,7 +362,7 @@         ,"'tidy'        : every attribute in its own column"         ])     -- output:-    ,outputFormatFlag ["txt","html","csv","tsv","json"]+    ,outputFormatFlag ["txt","html","csv","tsv","json","fods"]     ,outputFileFlag     ]   )@@ -354,6 +384,10 @@             "json" -> (<>"\n") . toJsonText             "csv"  -> printCSV . budgetReportAsCsv ropts             "tsv"  -> printTSV . budgetReportAsCsv ropts+            "html" -> (<>"\n") . L.renderText .+                      printHtml . map (map (fmap L.toHtml)) . budgetReportAsSpreadsheet ropts+            "fods" -> printFods IO.localeEncoding .+                      Map.singleton "Hledger" . (,) (Just 1, Nothing) . budgetReportAsSpreadsheet ropts             _      -> error' $ unsupportedOutputFormatError fmt       writeOutputLazyText opts $ render budgetreport @@ -365,6 +399,8 @@               "tsv"  -> printTSV . multiBalanceReportAsCsv ropts               "html" -> (<>"\n") . L.renderText . multiBalanceReportAsHtml ropts               "json" -> (<>"\n") . toJsonText+              "fods" -> printFods IO.localeEncoding .+                        Map.singleton "Hledger" . multiBalanceReportAsSpreadsheet ropts               _      -> const $ error' $ unsupportedOutputFormatError fmt  -- PARTIAL:         writeOutputLazyText opts $ render report @@ -374,8 +410,10 @@               "txt"  -> \ropts1 -> TB.toLazyText . balanceReportAsText ropts1               "csv"  -> \ropts1 -> printCSV . balanceReportAsCsv ropts1               "tsv"  -> \ropts1 -> printTSV . balanceReportAsCsv ropts1-              -- "html" -> \ropts -> (<>"\n") . L.renderText . multiBalanceReportAsHtml ropts . balanceReportAsMultiBalanceReport ropts+              "html" -> \ropts1 -> (<>"\n") . L.renderText .+                                   printHtml . map (map (fmap L.toHtml)) . balanceReportAsSpreadsheet ropts1               "json" -> const $ (<>"\n") . toJsonText+              "fods" -> \ropts1 -> printFods IO.localeEncoding . Map.singleton "Hledger" . (,) (Just 1, Nothing) . balanceReportAsSpreadsheet ropts1               _      -> error' $ unsupportedOutputFormatError fmt  -- PARTIAL:         writeOutputLazyText opts $ render ropts report   where@@ -386,65 +424,28 @@     delimited   = fmt == "csv" || fmt == "tsv"     fmt         = outputFormatFromOpts opts --- XXX this allows rough HTML rendering of a flat BalanceReport, but it can't handle tree mode etc.--- -- | Convert a BalanceReport to a MultiBalanceReport.--- balanceReportAsMultiBalanceReport :: ReportOpts -> BalanceReport -> MultiBalanceReport --- balanceReportAsMultiBalanceReport _ropts (britems, brtotal) = ---   let---     mbrrows = ---       [PeriodicReportRow{---           prrName    = flatDisplayName brfullname---         , prrAmounts = [bramt]---         , prrTotal   = bramt---         , prrAverage = bramt---         }---       | (brfullname, _, _, bramt) <- britems---       ]---   in---     PeriodicReport{---         prDates  = [nulldatespan]---       , prRows   = mbrrows---       , prTotals = PeriodicReportRow{---            prrName=()---           ,prrAmounts=[brtotal]---           ,prrTotal=brtotal---           ,prrAverage=brtotal---           }---       }+-- Rendering --- XXX should all the per-report, per-format rendering code live in the command module,--- like the below, or in the report module, like budgetReportAsText/budgetReportAsCsv ?+-- What to show as heading for the totals row in balance reports ?+-- Currently nothing in terminal, Total: in html and xSV output.+totalRowHeadingText       = ""+totalRowHeadingBudgetText = ""+totalRowHeadingHtml       = "Total:"+totalRowHeadingCsv        = "Total:"+totalRowHeadingBudgetCsv  = "Total:" --- rendering single-column balance reports+-- Single-column balance reports  -- | Render a single-column balance report as CSV. balanceReportAsCsv :: ReportOpts -> BalanceReport -> CSV-balanceReportAsCsv opts (items, total) =-    headers : concatMap (\(a, _, _, b) -> rows a b) items ++ if no_total_ opts then [] else rows "total" total-  where-    headers = "account" : case layout_ opts of-      LayoutBare -> ["commodity", "balance"]-      _          -> ["balance"]-    rows :: AccountName -> MixedAmount -> [[T.Text]]-    rows name ma = case layout_ opts of-      LayoutBare ->-          map (\a -> [showName name, acommodity a, renderAmount $ mixedAmount a])-          . amounts $ mixedAmountStripCosts ma-      _ -> [[showName name, renderAmount ma]]--    showName = accountNameDrop (drop_ opts)-    renderAmount amt = wbToText $ showMixedAmountB bopts amt-      where-        bopts = machineFmt{displayCommodity=showcomm, displayCommodityOrder = commorder}-        (showcomm, commorder)-          | layout_ opts == LayoutBare = (False, Just $ S.toList $ maCommodities amt)-          | otherwise                  = (True, Nothing)+balanceReportAsCsv opts =+    map (map Ods.cellContent) . balanceReportAsSpreadsheet opts  -- | Render a single-column balance report as plain text. balanceReportAsText :: ReportOpts -> BalanceReport -> TB.Builder balanceReportAsText opts ((items, total)) = case layout_ opts of     LayoutBare | iscustom -> error' "Custom format not supported with commodity columns"  -- PARTIAL:-    LayoutBare -> balanceReportAsText' opts ((items, total))+    LayoutBare -> bareLayoutBalanceReportAsText opts ((items, total))     _ -> unlinesB ls <> unlinesB (if no_total_ opts then [] else [overline, totalLines])   where     (ls, sizes) = unzip $ map (balanceReportItemAsText opts) items@@ -460,11 +461,14 @@     overlinewidth = if iscustom then sum (map maximum' $ transpose sizes) else 20     overline   = TB.fromText $ T.replicate overlinewidth "-" --- | Render a single-column balance report as plain text in commodity-column mode-balanceReportAsText' :: ReportOpts -> BalanceReport -> TB.Builder-balanceReportAsText' opts ((items, total)) =-  unlinesB . fmap (renderColumns def{tableBorders=False} sizes .  Tab.Group Tab.NoLine . fmap Tab.Header) $-    ls ++ concat [[[overline], totalline] | not (no_total_ opts)]+-- | Render a single-column balance report as plain text with a separate commodity column (--layout=bare)+bareLayoutBalanceReportAsText :: ReportOpts -> BalanceReport -> TB.Builder+bareLayoutBalanceReportAsText opts ((items, total)) =+  unlinesB .+  map +    (renderColumns def{tableBorders=singleColumnTableOuterBorder} sizes .+     Group singleColumnTableInterColumnBorder . map Header) $+  ls ++ concat [[[overline], totalline] | not (no_total_ opts)]   where     render (_, acctname, dep, amt) =         [ Cell TopRight damts@@ -479,6 +483,8 @@     sizes = fromMaybe 0 . maximumMay . map cellWidth <$>         transpose ([totalline | not (no_total_ opts)] ++ ls)     overline = Cell TopLeft . pure . wbFromText . flip T.replicate "-" . fromMaybe 0 $ headMay sizes+    singleColumnTableOuterBorder       = pretty_ opts+    singleColumnTableInterColumnBorder = if pretty_ opts then SingleLine else NoLine  {- :r@@ -499,21 +505,31 @@ balanceReportItemAsText opts (_, accountName, dep, amt) =   renderBalanceReportItem opts (accountName, dep, amt) --- | Render a balance report item using the given StringFormat, generating one or more lines of text.+-- | Render a balance report item, using the StringFormat specified by --format.+--  renderBalanceReportItem :: ReportOpts -> (AccountName, Int, MixedAmount) -> (TB.Builder, [Int]) renderBalanceReportItem opts (acctname, dep, total) =   case format_ opts of-      OneLine       comps -> renderRow' $ render True  True  comps-      TopAligned    comps -> renderRow' $ render True  False comps-      BottomAligned comps -> renderRow' $ render False False comps+      OneLine       comps -> renderRowFromComponents $ renderComponents True  True  comps+      TopAligned    comps -> renderRowFromComponents $ renderComponents True  False comps+      BottomAligned comps -> renderRowFromComponents $ renderComponents False False comps+   where-    renderRow' is = ( renderRowB def{tableBorders=False, borderSpaces=False}-                      . Tab.Group Tab.NoLine $ map Tab.Header is-                    , map cellWidth is )+    -- Combine the rendered component cells horizontally, as a possibly multi-line text (builder),+    -- aligned in borderless columns (? XXX). Also returns the rendered width of each cell.+    renderRowFromComponents :: [Cell] -> (TB.Builder, [Int])+    renderRowFromComponents cs =+      ( renderRowB def{tableBorders=False, borderSpaces=False} . Group NoLine $ map Header cs+      , map cellWidth cs+      ) -    render topaligned oneline = map (renderComponent topaligned oneline opts (acctname, dep, total))+    -- Render each of the given StringFormat components for the balance report item,+    -- returning each as a Cell.+    renderComponents :: Bool -> Bool -> [StringFormatComponent] -> [Cell]+    renderComponents topaligned oneline = map (renderComponent topaligned oneline opts (acctname, dep, total)) --- | Render one StringFormat component for a balance report item.+-- Render one StringFormat component for a balance report item.+-- Returns a Cell, containing 0 or more lines of text (as builders). renderComponent :: Bool -> Bool -> ReportOpts -> (AccountName, Int, MixedAmount) -> StringFormatComponent -> Cell renderComponent _ _ _ _ (FormatLiteral s) = textCell TopLeft s renderComponent topaligned oneline opts (acctname, dep, total) (FormatField ljust mmin mmax field) = case field of@@ -534,8 +550,66 @@                   ,displayColour    = color_ opts                   } --- rendering multi-column balance reports+-- | Render a single-column balance report as FODS.+balanceReportAsSpreadsheet :: ReportOpts -> BalanceReport -> [[Ods.Cell Text]]+balanceReportAsSpreadsheet opts (items, total) =+    headers :+    concatMap (\(a, _, _, b) -> rows a b) items +++    if no_total_ opts then []+      else map (map (\c -> c {Ods.cellStyle = Ods.Body Ods.Total})) $+            rows totalRowHeadingCsv total+  where+    cell = Ods.defaultCell+    headers =+      map (\content -> (cell content) {Ods.cellStyle = Ods.Head}) $+      "account" : case layout_ opts of+        LayoutBare -> ["commodity", "balance"]+        _          -> ["balance"]+    rows :: AccountName -> MixedAmount -> [[Ods.Cell Text]]+    rows name ma = case layout_ opts of+      LayoutBare ->+          map (\a ->+                [showName name,+                 cell $ acommodity a,+                 renderAmount $ mixedAmount a])+          . amounts $ mixedAmountStripCosts ma+      _ -> [[showName name, renderAmount ma]] +    showName = cell . accountNameDrop (drop_ opts)+    renderAmount mixedAmt = wbToText <$> cellFromMixedAmount bopts mixedAmt+      where+        bopts = machineFmt{displayCommodity=showcomm, displayCommodityOrder = commorder}+        (showcomm, commorder)+          | layout_ opts == LayoutBare = (False, Just $ S.toList $ maCommodities mixedAmt)+          | otherwise                  = (True, Nothing)++cellFromMixedAmount :: AmountFormat -> MixedAmount -> Ods.Cell WideBuilder+cellFromMixedAmount bopts mixedAmt =+    (Ods.defaultCell $ showMixedAmountB bopts mixedAmt) {+        Ods.cellType =+          case unifyMixedAmount mixedAmt of+            Just amt -> amountType bopts amt+            Nothing -> Ods.TypeMixedAmount+    }++cellsFromMixedAmount :: AmountFormat -> MixedAmount -> [Ods.Cell WideBuilder]+cellsFromMixedAmount bopts mixedAmt =+    map+        (\(str,amt) ->+            (Ods.defaultCell str) {Ods.cellType = amountType bopts amt})+        (showMixedAmountLinesPartsB bopts mixedAmt)++amountType :: AmountFormat -> Amount -> Ods.Type+amountType bopts amt =+    Ods.TypeAmount $+    if displayCommodity bopts+      then amt+      else amt {acommodity = T.empty}++++-- Multi-column balance reports+ -- | Render a multi-column balance report as CSV. -- The CSV will always include the initial headings row, -- and will include the final totals row unless --no-total is set.@@ -545,33 +619,65 @@     allRows = case layout_ of       LayoutTidy -> rows  -- tidy csv should not include totals or averages       _ -> rows ++ totals-    (rows, totals) = multiBalanceReportAsCsvOrHtml False opts report+    (rows, totals) = multiBalanceReportAsCsvHelper False opts report     maybeTranspose = if transpose_ then transpose else id --- Helper used for both CSV and HTML rendering.-multiBalanceReportAsCsvOrHtml :: Bool -> ReportOpts -> MultiBalanceReport -> (CSV, CSV)-multiBalanceReportAsCsvOrHtml ishtml opts@ReportOpts{..} (PeriodicReport colspans items tr) =-    (headers : concatMap fullRowAsTexts items, totalrows)+-- Helper for CSV (and HTML) rendering.+multiBalanceReportAsCsvHelper :: Bool -> ReportOpts -> MultiBalanceReport -> (CSV, CSV)+multiBalanceReportAsCsvHelper ishtml opts =+    (map (map Ods.cellContent) *** map (map Ods.cellContent)) .+    multiBalanceReportAsSpreadsheetHelper ishtml opts++-- Helper for CSV and ODS and HTML rendering.+multiBalanceReportAsSpreadsheetHelper ::+    Bool -> ReportOpts -> MultiBalanceReport -> ([[Ods.Cell Text]], [[Ods.Cell Text]])+multiBalanceReportAsSpreadsheetHelper ishtml opts@ReportOpts{..} (PeriodicReport colspans items tr) =+    (headers : concatMap fullRowAsTexts items,+        map (map (\c -> c{Ods.cellStyle = Ods.Body Ods.Total})) totalrows)   where-    headers = "account" : case layout_ of+    cell = Ods.defaultCell+    headers =+      map (\content -> (cell content) {Ods.cellStyle = Ods.Head}) $+      "account" :+      case layout_ of       LayoutTidy -> ["period", "start_date", "end_date", "commodity", "value"]       LayoutBare -> "commodity" : dateHeaders       _          -> dateHeaders     dateHeaders = map showDateSpan colspans ++ ["total" | row_total_] ++ ["average" | average_]--    fullRowAsTexts row = map (showName row :) $ rowAsText opts colspans row-    showName = accountNameDrop drop_ . prrFullName+    fullRowAsTexts row = map (cell (showName row) :) $ rowAsText row+      where showName = accountNameDrop drop_ . prrFullName     totalrows-      | no_total_ = mempty-      | otherwise = map ("total" :) $ rowAsText opts colspans tr-    rowAsText = if ishtml then multiBalanceRowAsHtmlText else multiBalanceRowAsCsvText+      | no_total_ = []+      | ishtml    = zipWith (:) (cell totalRowHeadingHtml : repeat Ods.emptyCell) $ rowAsText tr+      | otherwise = map (cell totalRowHeadingCsv :) $ rowAsText tr+    rowAsText =+        let fmt = if ishtml then oneLineNoCostFmt else machineFmt+        in  map (map (fmap wbToText)) . multiBalanceRowAsCellBuilders fmt opts colspans +-- Helpers and CSS styles for HTML output.++stylesheet_ elstyles = style_ $ T.unlines $ "" : [el<>" {"<>styles<>"}" | (el,styles) <- elstyles]+styles_ = style_ . T.intercalate "; "+bold = "font-weight:bold"+doubleborder = "double black"+topdoubleborder    = "border-top:"<>doubleborder+bottomdoubleborder = "border-bottom:"<>doubleborder+alignright  = "text-align:right"+alignleft   = "text-align:left"+aligncenter = "text-align:center"+collapse = "border-collapse:collapse"+lpad = "padding-left:1em"+rpad = "padding-right:1em"+hpad = "padding-left:1em; padding-right:1em"+vpad = "padding-top:1em;  padding-bottom:1em"+ -- | Render a multi-column balance report as HTML. multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html () multiBalanceReportAsHtml ropts mbr =   let     (headingsrow,bodyrows,mtotalsrows) = multiBalanceReportHtmlRows ropts mbr-  in+  in do+    stylesheet_ [("table",collapse), ("th, td",lpad), ("th.account, td.account","padding-left:0;")]     table_ $ mconcat $          [headingsrow]       ++ bodyrows@@ -585,11 +691,15 @@     -- TODO: should the commodity_column be displayed as a subaccount in this case as well?     (headingsrow:bodyrows, mtotalsrows)       | transpose_ ropts = error' "Sorry, --transpose with HTML output is not yet supported"  -- PARTIAL:-      | otherwise = multiBalanceReportAsCsvOrHtml True ropts mbr+      | otherwise = multiBalanceReportAsCsvHelper True ropts mbr   in     (multiBalanceReportHtmlHeadRow ropts headingsrow     ,map (multiBalanceReportHtmlBodyRow ropts) bodyrows-    ,multiBalanceReportHtmlFootRow ropts <$> mtotalsrows -- TODO pad totals row with zeros when there are+    ,zipWith3 ($)+      (repeat (multiBalanceReportHtmlFootRow ropts))+      (True : repeat False)  -- mark the first html table row for special styling+      mtotalsrows+      -- TODO pad totals row with zeros when there are     )  -- | Render one MultiBalanceReport heading row as a HTML table row.@@ -597,7 +707,6 @@ multiBalanceReportHtmlHeadRow _ [] = mempty  -- shouldn't happen multiBalanceReportHtmlHeadRow ropts (acct:cells) =   let-    defstyle = style_ ""     (amts,tot,avg)       | row_total_ ropts && average_ ropts = (ini2,  sndlst2, lst2)       | row_total_ ropts                   = (ini1,  lst1,    [])@@ -611,17 +720,16 @@    in     tr_ $ mconcat $-          td_ [class_ "account"]              (toHtml acct)-       : [td_ [class_ "", defstyle]           (toHtml a) | a <- amts]-      ++ [td_ [class_ "rowtotal", defstyle]   (toHtml a) | a <- tot]-      ++ [td_ [class_ "rowaverage", defstyle] (toHtml a) | a <- avg]+          th_ [styles_ [bottomdoubleborder,alignleft], class_ "account"]    (toHtml acct)+       : [th_ [styles_ [bottomdoubleborder,alignright], class_ ""]           (toHtml a) | a <- amts]+      ++ [th_ [styles_ [bottomdoubleborder,alignright], class_ "rowtotal"]   (toHtml a) | a <- tot]+      ++ [th_ [styles_ [bottomdoubleborder,alignright], class_ "rowaverage"] (toHtml a) | a <- avg]  -- | Render one MultiBalanceReport data row as a HTML table row. multiBalanceReportHtmlBodyRow :: ReportOpts -> [T.Text] -> Html () multiBalanceReportHtmlBodyRow _ [] = mempty  -- shouldn't happen multiBalanceReportHtmlBodyRow ropts (label:cells) =   let-    defstyle = style_ "text-align:right"     (amts,tot,avg)       | row_total_ ropts && average_ ropts = (ini2,  sndlst2, lst2)       | row_total_ ropts                   = (ini1,  lst1,    [])@@ -634,23 +742,22 @@         (sndlst2,lst2) = splitAt 1 rest   in     tr_ $ mconcat $-          td_ [class_ "account", style_ "text-align:left"]  (toHtml label)-       : [td_ [class_ "amount", defstyle]            (toHtml a) | a <- amts]-      ++ [td_ [class_ "amount rowtotal", defstyle]   (toHtml a) | a <- tot]-      ++ [td_ [class_ "amount rowaverage", defstyle] (toHtml a) | a <- avg]+          td_ [styles_ [],  class_ "account"]           (toHtml label)+       : [td_ [styles_ [alignright], class_ "amount"]            (toHtml a) | a <- amts]+      ++ [td_ [styles_ [alignright], class_ "amount rowtotal"]   (toHtml a) | a <- tot]+      ++ [td_ [styles_ [alignright], class_ "amount rowaverage"] (toHtml a) | a <- avg]  -- | Render one MultiBalanceReport totals row as a HTML table row.-multiBalanceReportHtmlFootRow :: ReportOpts -> [T.Text] -> Html ()-multiBalanceReportHtmlFootRow _ropts [] = mempty+multiBalanceReportHtmlFootRow :: ReportOpts -> Bool -> [T.Text] -> Html ()+multiBalanceReportHtmlFootRow _ _ [] = mempty -- TODO pad totals row with zeros when subreport is empty --  multiBalanceReportHtmlFootRow ropts $ --     "" --   : repeat nullmixedamt zeros --  ++ (if row_total_ ropts then [nullmixedamt] else []) --  ++ (if average_ ropts   then [nullmixedamt]   else [])-multiBalanceReportHtmlFootRow ropts (acct:cells) =+multiBalanceReportHtmlFootRow ropts isfirstline (hdr:cells) =   let-    defstyle = style_ "text-align:right"     (amts,tot,avg)       | row_total_ ropts && average_ ropts = (ini2,  sndlst2, lst2)       | row_total_ ropts                   = (ini1,  lst1,    [])@@ -663,20 +770,31 @@         (sndlst2,lst2) = splitAt 1 rest   in     tr_ $ mconcat $-          th_ [style_ "text-align:left"]             (toHtml acct)-       : [th_ [class_ "amount coltotal", defstyle]   (toHtml a) | a <- amts]-      ++ [th_ [class_ "amount coltotal", defstyle]   (toHtml a) | a <- tot]-      ++ [th_ [class_ "amount colaverage", defstyle] (toHtml a) | a <- avg]+          td_ [styles_ $ [topdoubleborder | isfirstline] ++ [bold], class_ "account"]                 (toHtml hdr)+       : [td_ [styles_ $ [topdoubleborder | isfirstline] ++ [alignright], class_ "amount coltotal"]   (toHtml a) | a <- amts]+      ++ [td_ [styles_ $ [topdoubleborder | isfirstline] ++ [alignright], class_ "amount coltotal"]   (toHtml a) | a <- tot]+      ++ [td_ [styles_ $ [topdoubleborder | isfirstline] ++ [alignright], class_ "amount colaverage"] (toHtml a) | a <- avg]  --thRow :: [String] -> Html () --thRow = tr_ . mconcat . map (th_ . toHtml) ++-- | Render the ODS table rows for a MultiBalanceReport.+-- Returns the heading row, 0 or more body rows, and the totals row if enabled.+multiBalanceReportAsSpreadsheet ::+  ReportOpts -> MultiBalanceReport -> ((Maybe Int, Maybe Int), [[Ods.Cell Text]])+multiBalanceReportAsSpreadsheet ropts mbr =+  let (upper,lower) = multiBalanceReportAsSpreadsheetHelper True ropts mbr+  in  ((Just 1, case layout_ ropts of LayoutWide _ -> Just 1; _ -> Nothing),+            upper ++ lower)++ -- | Render a multi-column balance report as plain text suitable for console output. multiBalanceReportAsText :: ReportOpts -> MultiBalanceReport -> TL.Text multiBalanceReportAsText ropts@ReportOpts{..} r = TB.toLazyText $     TB.fromText title     <> TB.fromText "\n\n"-    <> balanceReportTableAsText ropts (balanceReportAsTable ropts r)+    <> multiBalanceReportTableAsText ropts (multiBalanceReportAsTable ropts r)   where     title = mtitle <> " in " <> showDateSpan (periodicReportSpan r) <> valuationdesc <> ":" @@ -706,15 +824,36 @@         (CalcValueChange, Cumulative) -> True         _                                     -> False +-- | Given a table representing a multi-column balance report,+-- render it in a format suitable for console output.+-- Amounts with more than two commodities will be elided unless --no-elide is used.+multiBalanceReportTableAsText :: ReportOpts -> Table T.Text T.Text WideBuilder -> TB.Builder+multiBalanceReportTableAsText ReportOpts{..} = renderTableByRowsB tableopts renderCh renderRow+  where+    tableopts = def{tableBorders=multiColumnTableOuterBorder, prettyTable=pretty_}+    multiColumnTableOuterBorder = pretty_++    renderCh :: [Text] -> [Cell]+    renderCh+      | layout_ /= LayoutBare || transpose_ = fmap (textCell TopRight)+      | otherwise = zipWith ($) (textCell TopLeft : repeat (textCell TopRight))++    renderRow :: (Text, [WideBuilder]) -> (Cell, [Cell])+    renderRow (rh, row)+      | layout_ /= LayoutBare || transpose_ =+          (textCell TopLeft rh, fmap (Cell TopRight . pure) row)+      | otherwise =+          (textCell TopLeft rh, zipWith ($) (Cell TopLeft : repeat (Cell TopRight)) (fmap pure row))+ -- | Build a 'Table' from a multi-column balance report.-balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table T.Text T.Text WideBuilder-balanceReportAsTable opts@ReportOpts{summary_only_, average_, row_total_, balanceaccum_}+multiBalanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table T.Text T.Text WideBuilder+multiBalanceReportAsTable opts@ReportOpts{summary_only_, average_, row_total_, balanceaccum_}     (PeriodicReport spans items tr) =    maybetranspose $    addtotalrow $    Table-     (Tab.Group Tab.NoLine $ map Tab.Header (concat accts))-     (Tab.Group Tab.NoLine $ map Tab.Header colheadings)+     (Group multiColumnTableInterRowBorder    $ map Header $ concat accts)+     (Group multiColumnTableInterColumnBorder $ map Header colheadings)      (concat rows)   where     totalscolumn = row_total_ && balanceaccum_ `notElem` [Cumulative, Historical]@@ -723,7 +862,7 @@                   ++ ["  Total" | totalscolumn]                   ++ ["Average" | average_]     fullRowAsTexts row =-      let rs = multiBalanceRowAsTableText opts row+      let rs = multiBalanceRowAsText opts row        in (replicate (length rs) (renderacct row), rs)     (accts, rows) = unzip $ fmap fullRowAsTexts items     renderacct row =@@ -731,39 +870,49 @@     addtotalrow       | no_total_ opts = id       | otherwise =-        let totalrows = multiBalanceRowAsTableText opts tr-            rh = Tab.Group Tab.NoLine . replicate (length totalrows) $ Tab.Header ""-            ch = Tab.Header [] -- ignored-         in (flip (concatTables Tab.SingleLine) $ Table rh ch totalrows)+        let totalrows = multiBalanceRowAsText opts tr+            rowhdrs = Group NoLine $ map Header $ totalRowHeadingText : replicate (length totalrows - 1) ""+            colhdrs = Header [] -- unused, concatTables will discard+        in (flip (concatTables SingleLine) $ Table rowhdrs colhdrs totalrows)     maybetranspose | transpose_ opts = \(Table rh ch vals) -> Table ch rh (transpose vals)                    | otherwise       = id+    multiColumnTableInterRowBorder    = NoLine+    multiColumnTableInterColumnBorder = if pretty_ opts then SingleLine else NoLine -multiBalanceRowAsWbs :: AmountFormat -> ReportOpts -> [DateSpan] -> PeriodicReportRow a MixedAmount -> [[WideBuilder]]-multiBalanceRowAsWbs bopts ReportOpts{..} colspans (PeriodicReportRow _ as rowtot rowavg) =+multiBalanceRowAsTextBuilders :: AmountFormat -> ReportOpts -> [DateSpan] -> PeriodicReportRow a MixedAmount -> [[WideBuilder]]+multiBalanceRowAsTextBuilders bopts ropts colspans row =+    map (map Ods.cellContent) $+    multiBalanceRowAsCellBuilders bopts ropts colspans row++multiBalanceRowAsCellBuilders ::+    AmountFormat -> ReportOpts -> [DateSpan] -> PeriodicReportRow a MixedAmount -> [[Ods.Cell WideBuilder]]+multiBalanceRowAsCellBuilders bopts ReportOpts{..} colspans (PeriodicReportRow _ as rowtot rowavg) =     case layout_ of-      LayoutWide width -> [fmap (showMixedAmountB bopts{displayMaxWidth=width}) allamts]-      LayoutTall       -> paddedTranspose mempty-                           . fmap (showMixedAmountLinesB bopts{displayMaxWidth=Nothing})+      LayoutWide width -> [fmap (cellFromMixedAmount bopts{displayMaxWidth=width}) allamts]+      LayoutTall       -> paddedTranspose Ods.emptyCell+                           . fmap (cellsFromMixedAmount bopts{displayMaxWidth=Nothing})                            $ allamts-      LayoutBare       -> zipWith (:) (fmap wbFromText cs)  -- add symbols+      LayoutBare       -> zipWith (:) (map wbCell cs)  -- add symbols                            . transpose                         -- each row becomes a list of Text quantities-                           . fmap (showMixedAmountLinesB bopts{displayCommodity=False, displayCommodityOrder=Just cs, displayMinWidth=Nothing})+                           . fmap (cellsFromMixedAmount bopts{displayCommodity=False, displayCommodityOrder=Just cs, displayMinWidth=Nothing})                            $ allamts       LayoutTidy       -> concat                            . zipWith (map . addDateColumns) colspans-                           . fmap ( zipWith (\c a -> [wbFromText c, a]) cs-                                  . showMixedAmountLinesB bopts{displayCommodity=False, displayCommodityOrder=Just cs, displayMinWidth=Nothing})+                           . fmap ( zipWith (\c a -> [wbCell c, a]) cs+                                  . cellsFromMixedAmount bopts{displayCommodity=False, displayCommodityOrder=Just cs, displayMinWidth=Nothing})                            $ as  -- Do not include totals column or average for tidy output, as this                                  -- complicates the data representation and can be easily calculated   where+    wbCell = Ods.defaultCell . wbFromText+    wbDate content = (wbCell content) {Ods.cellType = Ods.TypeDate}     totalscolumn = row_total_ && balanceaccum_ `notElem` [Cumulative, Historical]     cs = if all mixedAmountLooksZero allamts then [""] else S.toList $ foldMap maCommodities allamts     allamts = (if not summary_only_ then as else []) ++                 [rowtot | totalscolumn && not (null as)] ++                 [rowavg | average_ && not (null as)]-    addDateColumns spn@(DateSpan s e) = (wbFromText (showDateSpan spn) :)-                                       . (wbFromText (maybe "" showEFDate s) :)-                                       . (wbFromText (maybe "" (showEFDate . modifyEFDay (addDays (-1))) e) :)+    addDateColumns spn@(DateSpan s e) = (wbCell (showDateSpan spn) :)+                                       . (wbDate (maybe "" showEFDate s) :)+                                       . (wbDate (maybe "" (showEFDate . modifyEFDay (addDays (-1))) e) :)      paddedTranspose :: a -> [[a]] -> [[a]]     paddedTranspose _ [] = [[]]@@ -780,14 +929,317 @@           m [] = [n]  +multiBalanceRowAsText :: ReportOpts -> PeriodicReportRow a MixedAmount -> [[WideBuilder]]+multiBalanceRowAsText opts = multiBalanceRowAsTextBuilders oneLineNoCostFmt{displayColour=color_ opts} opts []+ multiBalanceRowAsCsvText :: ReportOpts -> [DateSpan] -> PeriodicReportRow a MixedAmount -> [[T.Text]]-multiBalanceRowAsCsvText opts colspans = fmap (fmap wbToText) . multiBalanceRowAsWbs machineFmt opts colspans+multiBalanceRowAsCsvText opts colspans = fmap (fmap wbToText) . multiBalanceRowAsTextBuilders machineFmt opts colspans -multiBalanceRowAsHtmlText :: ReportOpts -> [DateSpan] -> PeriodicReportRow a MixedAmount -> [[T.Text]]-multiBalanceRowAsHtmlText opts colspans = fmap (fmap wbToText) . multiBalanceRowAsWbs oneLineNoCostFmt opts colspans+-- Budget reports -multiBalanceRowAsTableText :: ReportOpts -> PeriodicReportRow a MixedAmount -> [[WideBuilder]]-multiBalanceRowAsTableText opts = multiBalanceRowAsWbs oneLineNoCostFmt{displayColour=color_ opts} opts []+-- A BudgetCell's data values rendered for display - the actual change amount,+-- the budget goal amount if any, and the corresponding goal percentage if possible.+type BudgetDisplayCell = (WideBuilder, Maybe (WideBuilder, Maybe WideBuilder))++-- | A row of rendered budget data cells.+type BudgetDisplayRow  = [BudgetDisplayCell]++-- | An amount render helper for the budget report. Renders each commodity separately.+type BudgetShowAmountsFn   = MixedAmount -> [WideBuilder]++-- | A goal percentage calculating helper for the budget report.+type BudgetCalcPercentagesFn  = Change -> BudgetGoal -> [Maybe Percentage]++-- | Render a budget report as plain text suitable for console output.+budgetReportAsText :: ReportOpts -> BudgetReport -> TL.Text+budgetReportAsText ropts@ReportOpts{..} budgetr = TB.toLazyText $+    TB.fromText title <> TB.fromText "\n\n" <>+      multiBalanceReportTableAsText ropts (budgetReportAsTable ropts budgetr)+  where+    title = "Budget performance in " <> showDateSpan (periodicReportSpan budgetr)+           <> (case conversionop_ of+                 Just ToCost -> ", converted to cost"+                 _           -> "")+           <> (case value_ of+                 Just (AtThen _mc)   -> ", valued at posting date"+                 Just (AtEnd _mc)    -> ", valued at period ends"+                 Just (AtNow _mc)    -> ", current value"+                 Just (AtDate d _mc) -> ", valued at " <> showDate d+                 Nothing             -> "")+           <> ":"++-- | Build a 'Table' from a multi-column balance report.+budgetReportAsTable :: ReportOpts -> BudgetReport -> Table Text Text WideBuilder+budgetReportAsTable ReportOpts{..} (PeriodicReport spans items totrow) =+  maybetransposetable $+  addtotalrow $+    Table+      (Group budgetTableInterRowBorder    $ map Header accts)+      (Group budgetTableInterColumnBorder $ map Header colheadings)+      rows+  where+    budgetTableInterRowBorder    = NoLine+    budgetTableInterColumnBorder = if pretty_ then SingleLine else NoLine++    maybetransposetable+      | transpose_ = \(Table rh ch vals) -> Table ch rh (transpose vals)+      | otherwise  = id++    addtotalrow+      | no_total_ = id+      | otherwise =+        let +          rowhdrs = Group NoLine $ map Header $ totalRowHeadingBudgetText : replicate (length totalrows - 1) ""+          colhdrs = Header [] -- ignored by concatTables+        in+          (flip (concatTables SingleLine) $ Table rowhdrs colhdrs totalrows)  -- XXX ?++    colheadings = ["Commodity" | layout_ == LayoutBare]+                  ++ map (reportPeriodName balanceaccum_ spans) spans+                  ++ ["  Total" | row_total_]+                  ++ ["Average" | average_]++    (accts, rows, totalrows) =+      (accts'+      ,maybecommcol itemscs  $ showcells  texts+      ,maybecommcol totrowcs $ showtotrow totrowtexts)+      where+        -- If --layout=bare, prepend a commodities column.+        maybecommcol :: [WideBuilder] -> [[WideBuilder]] -> [[WideBuilder]]+        maybecommcol cs+          | layout_ == LayoutBare = zipWith (:) cs+          | otherwise             = id++        showcells, showtotrow :: [[BudgetDisplayCell]] -> [[WideBuilder]]+        (showcells, showtotrow) =+          (maybetranspose . map (zipWith showBudgetDisplayCell widths)       . maybetranspose+          ,maybetranspose . map (zipWith showBudgetDisplayCell totrowwidths) . maybetranspose)+          where+            -- | Combine a BudgetDisplayCell's rendered values into a "[PERCENT of GOAL]" rendering,+            -- respecting the given widths.+            showBudgetDisplayCell :: (Int, Int, Int) -> BudgetDisplayCell -> WideBuilder+            showBudgetDisplayCell (actualwidth, budgetwidth, percentwidth) (actual, mbudget) =+              flip WideBuilder (actualwidth + totalbudgetwidth) $+                toPadded actual <> maybe emptycell showBudgetGoalAndPercentage mbudget++              where+                toPadded (WideBuilder b w) = (TB.fromText . flip T.replicate " " $ actualwidth - w) <> b++                (totalpercentwidth, totalbudgetwidth) =+                  let totalpercentwidth' = if percentwidth == 0 then 0 else percentwidth + 5+                   in ( totalpercentwidth'+                      , if budgetwidth == 0 then 0 else budgetwidth + totalpercentwidth' + 3+                      )++                emptycell :: TB.Builder+                emptycell = TB.fromText $ T.replicate totalbudgetwidth " "++                showBudgetGoalAndPercentage :: (WideBuilder, Maybe WideBuilder) -> TB.Builder+                showBudgetGoalAndPercentage (goal, perc) =+                  let perct = case perc of+                        Nothing  -> T.replicate totalpercentwidth " "+                        Just pct -> T.replicate (percentwidth - wbWidth pct) " " <> wbToText pct <> "% of "+                   in TB.fromText $ " [" <> perct <> T.replicate (budgetwidth - wbWidth goal) " " <> wbToText goal <> "]"++            -- | Build a list of widths for each column.+            -- When --transpose is used, the totals row must be included in this list.+            widths :: [(Int, Int, Int)]+            widths = zip3 actualwidths budgetwidths percentwidths+              where+                actualwidths  = map (maximum' . map first3 ) $ cols+                budgetwidths  = map (maximum' . map second3) $ cols+                percentwidths = map (maximum' . map third3 ) $ cols+                catcolumnwidths = foldl' (zipWith (++)) $ repeat []+                cols = maybetranspose $ catcolumnwidths $ map (cellswidth . rowToBudgetCells) items ++ [cellswidth $ rowToBudgetCells totrow]++                cellswidth :: [BudgetCell] -> [[(Int, Int, Int)]]+                cellswidth row =+                  let cs = budgetCellsCommodities row+                      (showmixed, percbudget) = mkBudgetDisplayFns cs+                      disp = showcell showmixed percbudget+                      budgetpercwidth = wbWidth *** maybe 0 wbWidth+                      cellwidth (am, bm) = let (bw, pw) = maybe (0, 0) budgetpercwidth bm in (wbWidth am, bw, pw)+                   in map (map cellwidth . disp) row++            totrowwidths :: [(Int, Int, Int)]+            totrowwidths+              | transpose_ = drop (length texts) widths+              | otherwise = widths++            maybetranspose+              | transpose_ = transpose+              | otherwise  = id++        (accts', itemscs, texts) = unzip3 $ concat shownitems+          where+            shownitems :: [[(AccountName, WideBuilder, BudgetDisplayRow)]]+            shownitems =+              map (\i ->+                let+                  addacctcolumn = map (\(cs, cvals) -> (renderacct i, cs, cvals))+                  isunbudgetedrow = displayFull (prrName i) == unbudgetedAccountName+                in addacctcolumn $ showrow isunbudgetedrow $ rowToBudgetCells i)+              items+              where+                -- FIXME. Have to check explicitly for which to render here, since+                -- budgetReport sets accountlistmode to ALTree. Find a principled way to do+                -- this.+                renderacct row = case accountlistmode_ of+                  ALTree -> T.replicate ((prrDepth row - 1)*2) " " <> prrDisplayName row+                  ALFlat -> accountNameDrop (drop_) $ prrFullName row++        (totrowcs, totrowtexts)  = unzip  $ concat showntotrow+          where+            showntotrow :: [[(WideBuilder, BudgetDisplayRow)]]+            showntotrow = [showrow False $ rowToBudgetCells totrow]++        -- | Get the data cells from a row or totals row, maybe adding +        -- the row total and/or row average depending on options.+        rowToBudgetCells :: PeriodicReportRow a BudgetCell -> [BudgetCell]+        rowToBudgetCells (PeriodicReportRow _ as rowtot rowavg) = as+            ++ [rowtot | row_total_ && not (null as)]+            ++ [rowavg | average_   && not (null as)]++        -- | Render a row's data cells as "BudgetDisplayCell"s, and a rendered list of commodity symbols.+        -- Also requires a flag indicating whether this is the special <unbudgeted> row.+        -- (The types make that hard to check here.)+        showrow :: Bool -> [BudgetCell] -> [(WideBuilder, BudgetDisplayRow)]+        showrow isunbudgetedrow cells =+          let+            cs = budgetCellsCommodities cells+            -- #2071 If there are no commodities - because there are no actual or goal amounts -+            -- the zipped list would be empty, causing this row not to be shown.+            -- But rows like this sometimes need to be shown to preserve the account tree structure.+            -- So, ensure 0 will be shown as actual amount(s).+            -- Unfortunately this disables boring parent eliding, as if --no-elide had been used.+            -- (Just turning on --no-elide higher up doesn't work right.)+            -- Note, no goal amount will be shown for these rows,+            -- whereas --no-elide is likely to show a goal amount aggregated from children.+            cs1 = if null cs && not isunbudgetedrow then [""] else cs+            (showmixed, percbudget) = mkBudgetDisplayFns cs1+          in+            zip (map wbFromText cs1) $+            transpose $+            map (showcell showmixed percbudget)+            cells++        budgetCellsCommodities :: [BudgetCell] -> [CommoditySymbol]+        budgetCellsCommodities = S.toList . foldl' S.union mempty . map budgetCellCommodities+          where+            budgetCellCommodities :: BudgetCell -> S.Set CommoditySymbol+            budgetCellCommodities (am, bm) = f am `S.union` f bm+              where f = maybe mempty maCommodities++        -- | Render a "BudgetCell"'s amounts as "BudgetDisplayCell"s (one per commodity).+        showcell :: BudgetShowAmountsFn -> BudgetCalcPercentagesFn -> BudgetCell -> BudgetDisplayRow+        showcell showCommodityAmounts calcCommodityPercentages (mactual, mbudget) =+          zip actualamts budgetinfos+          where+            actual = fromMaybe nullmixedamt mactual+            actualamts = showCommodityAmounts actual+            budgetinfos =+              case mbudget of+                Nothing   -> repeat Nothing+                Just goal -> map Just $ showGoalAmountsAndPercentages goal+                where+                  showGoalAmountsAndPercentages :: MixedAmount -> [(WideBuilder, Maybe WideBuilder)]+                  showGoalAmountsAndPercentages goal = zip amts mpcts+                    where+                      amts  = showCommodityAmounts goal+                      mpcts = map (showrounded <$>) $ calcCommodityPercentages actual goal+                        where showrounded = wbFromText . T.pack . show . roundTo 0++        -- | Make budget info display helpers that adapt to --layout=wide.+        mkBudgetDisplayFns :: [CommoditySymbol] -> (BudgetShowAmountsFn, BudgetCalcPercentagesFn)+        mkBudgetDisplayFns cs = case layout_ of+          LayoutWide width ->+               ( pure . showMixedAmountB oneLineNoCostFmt{displayMaxWidth=width, displayColour=color_}+               , \a -> pure . percentage a)+          _ -> ( showMixedAmountLinesB noCostFmt{displayCommodity=layout_/=LayoutBare, displayCommodityOrder=Just cs, displayMinWidth=Nothing, displayColour=color_}+               , \a b -> map (percentage' a b) cs)+          where+            -- | Calculate the percentage of actual change to budget goal to show, if any.+            -- If valuing at cost, both amounts are converted to cost before comparing.+            -- A percentage will not be shown if:+            --+            -- - actual or goal are not the same, single, commodity+            --+            -- - the goal is zero+            --+            percentage :: Change -> BudgetGoal -> Maybe Percentage+            percentage actual budget =+              case (costedAmounts actual, costedAmounts budget) of+                ([a], [b]) | (acommodity a == acommodity b || amountLooksZero a) && not (amountLooksZero b)+                    -> Just $ 100 * aquantity a / aquantity b+                _   -> Nothing+              where+                costedAmounts = case conversionop_ of+                    Just ToCost -> amounts . mixedAmountCost+                    _           -> amounts++            -- | Like percentage, but accept multicommodity actual and budget amounts,+            -- and extract the specified commodity from both.+            percentage' :: Change -> BudgetGoal -> CommoditySymbol -> Maybe Percentage+            percentage' am bm c = case ((,) `on` find ((==) c . acommodity) . amounts) am bm of+                (Just a, Just b) -> percentage (mixedAmount a) (mixedAmount b)+                _                -> Nothing++-- XXX generalise this with multiBalanceReportAsCsv ?+-- | Render a budget report as CSV. Like multiBalanceReportAsCsv,+-- but includes alternating actual and budget amount columns.+budgetReportAsCsv :: ReportOpts -> BudgetReport -> [[Text]]+budgetReportAsCsv ropts report+  = map (map Ods.cellContent) $+    budgetReportAsSpreadsheet ropts report++budgetReportAsSpreadsheet :: ReportOpts -> BudgetReport -> [[Ods.Cell Text]]+budgetReportAsSpreadsheet+  ReportOpts{..}+  (PeriodicReport colspans items totrow)+  = (if transpose_ then transpose else id) $++  -- heading row+  (map (\content -> (cell content) {Ods.cellStyle = Ods.Head}) $+  "Account" :+  ["Commodity" | layout_ == LayoutBare ]+   ++ concatMap (\spn -> [showDateSpan spn, "budget"]) colspans+   ++ concat [["Total"  ,"budget"] | row_total_]+   ++ concat [["Average","budget"] | average_]+  ) :++  -- account rows+  concatMap (rowAsTexts prrFullName) items++  -- totals row+  ++ map (map (\c -> c {Ods.cellStyle = Ods.Body Ods.Total}))+        (concat [ rowAsTexts (const totalRowHeadingBudgetCsv) totrow | not no_total_ ])++  where+    cell = Ods.defaultCell+    flattentuples tups = concat [[a,b] | (a,b) <- tups]+    showNorm = maybe Ods.emptyCell (fmap wbToText . cellFromMixedAmount oneLineNoCostFmt)++    rowAsTexts :: (PeriodicReportRow a BudgetCell -> Text)+               -> PeriodicReportRow a BudgetCell+               -> [[Ods.Cell Text]]+    rowAsTexts render row@(PeriodicReportRow _ as (rowtot,budgettot) (rowavg, budgetavg))+      | layout_ /= LayoutBare = [cell (render row) : map showNorm vals]+      | otherwise =+            joinNames . zipWith (:) (map cell cs)  -- add symbols and names+          . transpose                   -- each row becomes a list of Text quantities+          . map (map (fmap wbToText) . cellsFromMixedAmount dopts . fromMaybe nullmixedamt)+          $ vals+      where+        cs = S.toList . mconcat . map maCommodities $ catMaybes vals+        dopts = oneLineNoCostFmt{displayCommodity=layout_ /= LayoutBare, displayCommodityOrder=Just cs, displayMinWidth=Nothing}+        vals = flattentuples as+            ++ concat [[rowtot, budgettot] | row_total_]+            ++ concat [[rowavg, budgetavg] | average_]++        joinNames = map (cell (render row) :)+++-- tests  tests_Balance = testGroup "Balance" [ 

@@ -6,7 +6,62 @@ some kind of numeric data. This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc. -_FLAGS+Flags:+     --sum                  show sum of posting amounts (default)+     --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).+     --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)+     --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)+  -r --related              show postings' siblings instead+  -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+     --invert               display all amounts with reversed sign+     --transpose            transpose rows and columns+     --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+  -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@@ -70,8 +125,8 @@  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. In txt output in a colour-supporting-terminal, negative amounts are shown in red.+(multi-period reports only:) html, fods (Added in 1.40). In txt output+in a colour-supporting terminal, negative amounts are shown in red.  Simple balance report @@ -799,11 +854,11 @@ "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"+"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

@@ -5,7 +5,50 @@ Show the end balances in asset and liability accounts. Amounts are shown with normal positive sign, as in conventional financial statements. -_FLAGS+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+     --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+  -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

@@ -6,7 +6,50 @@ balances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements. -_FLAGS+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+     --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+  -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

@@ -7,7 +7,49 @@ Amounts are shown with normal positive sign, as in conventional financial statements. -_FLAGS+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+     --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+  -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

@@ -2,7 +2,8 @@  Check for various kinds of errors in your data. -_FLAGS+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

@@ -9,7 +9,35 @@ You can append or copy these to your journal file(s) when you are happy with how they look. -_FLAGS+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: 

@@ -2,7 +2,8 @@  List the codes seen in transactions, in the order parsed. -_FLAGS+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

@@ -2,4 +2,5 @@  List all commodity/currency symbols used or declared in the journal. -_FLAGS+Flags:+no command-specific flags

@@ -2,7 +2,9 @@  Play demos of hledger usage in the terminal, if asciinema is installed. -_FLAGS+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:

@@ -2,7 +2,8 @@  List the unique descriptions that appear in transactions. -_FLAGS+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

@@ -4,18 +4,22 @@ shows any transactions to this account which are in one file but not in the other. -More precisely, for each posting affecting this account in either file,-it looks for a corresponding posting in the other file which posts the-same amount to the same account (ignoring date, description, etc.) Since-postings not transactions are compared, this also works when multiple-bank transactions have been combined into a single journal entry.+Flags:+no command-specific flags -This is useful eg if you have downloaded an account's transactions from-your bank (eg as CSV data). When hledger and your bank disagree about-the account balance, you can compare the bank data with your journal to-find out the cause.+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). -_FLAGS+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: 

@@ -22,8 +22,8 @@ filesmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Files.txt")   []-  [generalflagsgroup2]-  []+  cligeneralflagsgroups2+  hiddenflags   ([], Just $ argsFlag "[REGEX]")  -- | The files command.

@@ -3,4 +3,5 @@ List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. -_FLAGS+Flags:+no command-specific flags

@@ -3,7 +3,11 @@ 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+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

@@ -2,7 +2,9 @@  Import new transactions from one or more data files to the main journal. -_FLAGS+Flags:+     --catchup              just mark all transactions as already imported+     --dry-run              just show the transactions to be imported  This command detects new transactions in each FILE argument since it was last run, and appends them to the main journal.

@@ -6,7 +6,49 @@ Amounts are shown with normal positive sign, as in conventional financial statements. -_FLAGS+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+     --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+  -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.

@@ -2,7 +2,8 @@  List the unique notes that appear in transactions. -_FLAGS+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

@@ -2,7 +2,9 @@  List the unique payee/payer names that appear in transactions. -_FLAGS+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

@@ -5,6 +5,10 @@ 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. @@ -14,5 +18,3 @@ --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.--_FLAGS

@@ -27,7 +27,7 @@ import System.Console.CmdArgs.Explicit  import Hledger-import Hledger.Read.CsvUtils (CSV, printCSV, printTSV)+import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Cli.CliOptions import Hledger.Cli.Utils import System.Exit (exitFailure)

@@ -2,7 +2,28 @@  Show full journal entries, representing transactions. -_FLAGS+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+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, beancount, csv, tsv, 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).

@@ -27,7 +27,7 @@ import System.Console.CmdArgs.Explicit (flagNone, flagReq)  import Hledger hiding (per)-import Hledger.Read.CsvUtils (CSV, CsvRecord, printCSV, printTSV)+import Hledger.Write.Csv (CSV, CsvRecord, printCSV, printTSV) import Hledger.Cli.CliOptions import Hledger.Cli.Utils import Text.Tabular.AsciiWide hiding (render)@@ -41,7 +41,7 @@   ([flagNone ["cumulative"] (setboolopt "cumulative")      "show running total from report start date (default)"   ,flagNone ["historical","H"] (setboolopt "historical")-     "show historical running total/balance (includes postings before report start date)\n "+     "show historical running total/balance (includes postings before report start date)"   ,flagNone ["average","A"] (setboolopt "average")      "show running average of posting amounts instead of total (implies --empty)"   ,let arg = "DESC" in@@ -49,6 +49,9 @@     ("fuzzy search for one recent posting with description closest to "++arg)   ,flagNone ["related","r"] (setboolopt "related") "show postings' siblings instead"   ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign"+  ,flagReq  ["sort"] (\s opts -> Right $ setopt "sort" s opts) "FIELDS" +    ("sort by: " <> sortKeysDescription+    <> ", or a comma-separated combination of these. For a descending sort, prefix with -. (Default: date)")   ,flagReq  ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N"      ("set output width (default: " ++ #ifdef mingw32_HOST_OS

@@ -4,7 +4,27 @@  Show postings and their running total. -_FLAGS+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)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, csv, tsv, 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@@ -55,6 +75,13 @@ 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 

@@ -4,7 +4,15 @@ For now the only rewrite available is adding new postings, like print --auto. -_FLAGS+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

@@ -325,10 +325,10 @@  calculateCashFlow :: WhichDate -> [Transaction] -> Query -> CashFlow calculateCashFlow wd trans query =-  [ (postingDateOrDate2 wd p, pamount p) | p <- filter (matchesPosting query) (concatMap realPostings trans), maIsNonZero (pamount p) ]+  [ (postingDateOrDate2 wd p, pamount p) | p <- concatMap (filter (matchesPosting query) . realPostings) trans, maIsNonZero (pamount p) ]  total :: [Transaction] -> Query -> MixedAmount-total trans query = sumPostings . filter (matchesPosting query) $ concatMap realPostings trans+total trans query = sumPostings (concatMap (filter (matchesPosting query) . realPostings) trans)  unMix :: MixedAmount -> Quantity unMix a =

@@ -3,7 +3,12 @@ Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. -_FLAGS+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

@@ -2,7 +2,9 @@  Show journal and performance statistics. -_FLAGS+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

@@ -2,7 +2,10 @@  List the tags used in the journal, or their values. -_FLAGS+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.

@@ -2,7 +2,8 @@  Run built-in unit tests. -_FLAGS+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

@@ -1,5 +1,6 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE RecordWildCards   #-}+{-# LANGUAGE LambdaCase #-} {-|  Common helpers for making multi-section balance report commands@@ -19,16 +20,18 @@ import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as TB import Data.Time.Calendar (Day, addDays)-import System.Console.CmdArgs.Explicit as C-import Hledger.Read.CsvUtils (CSV, printCSV, printTSV)+import System.Console.CmdArgs.Explicit as C (Mode, flagNone, flagReq)+import Hledger.Write.Csv (CSV, printCSV, printTSV) import Lucid as L hiding (value_) import Safe (tailDef)-import Text.Tabular.AsciiWide as Tab hiding (render)+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 (when)  -- | Description of a compound balance report command, -- from which we generate the command's cmdargs mode and IO action.@@ -44,7 +47,7 @@ -- it should be added to or subtracted from the grand total. -- data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec {-  cbcdoc      :: CommandDoc,                      -- ^ the command's name(s) and documentation+  cbcdoc      :: CommandHelpStr,                  -- ^ the command's name(s) and documentation   cbctitle    :: String,                          -- ^ overall report title   cbcqueries  :: [CBCSubreportSpec DisplayName],  -- ^ subreport details   cbcaccum    :: BalanceAccumulation              -- ^ how to accumulate balances (per-period, cumulative, historical)@@ -64,7 +67,7 @@     ,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\n "+      "show sum of posting amounts compared to budget goals defined by periodic transactions"     ,flagNone ["change"] (setboolopt "change")        ("accumulate amounts from column start to column end (in multicolumn reports)"@@ -74,7 +77,7 @@            ++ defaultMarker Cumulative)     ,flagNone ["historical","H"] (setboolopt "historical")        ("accumulate amounts from journal start to column end (includes postings before report start date)"-           ++ defaultMarker Historical ++ "\n ")+           ++ defaultMarker Historical)     ]     ++ flattreeflags True ++     [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"@@ -122,7 +125,8 @@     ropts' = ropts{balanceaccum_=balanceaccumulation}      title =-      T.pack cbctitle+         maybe "" (<>" ") mintervalstr+      <> T.pack cbctitle       <> " "       <> titledatestr       <> maybe "" (" "<>) mtitleclarification@@ -141,6 +145,8 @@             enddates = map (addDays (-1)) . mapMaybe spanEnd $ cbrDates cbr  -- these spans will always have a definite end date             requestedspan = fst $ reportSpan j rspec +        mintervalstr = showInterval interval_+         -- when user overrides, add an indication to the report title         -- Do we need to deal with overridden BalanceCalculation?         mtitleclarification = case (balancecalc_, balanceaccumulation, mbalanceAccumulationOverride) of@@ -184,6 +190,24 @@       "json" -> toJsonText       x      -> error' $ unsupportedOutputFormatError x +-- | Show a simplified description of an Interval.+showInterval :: Interval -> Maybe T.Text+showInterval = \case+  NoInterval -> Nothing+  Days 1     -> Just "Daily"+  Weeks 1    -> Just "Weekly"+  Weeks 2    -> Just "Biweekly"+  Months 1   -> Just "Monthly"+  Months 2   -> Just "Bimonthly"+  Months 3   -> Just "Quarterly"+  Months 6   -> Just "Half-yearly"+  Months 12  -> Just "Yearly"+  Quarters 1 -> Just "Quarterly"+  Quarters 2 -> Just "Half-yearly"+  Years 1    -> Just "Yearly"+  Years 2    -> Just "Biannual"+  _          -> Just "Periodic"+ -- | Summarise one or more (inclusive) end dates, in a way that's -- visually different from showDateSpan, suggesting discrete end dates -- rather than a continuous span.@@ -215,40 +239,60 @@  -} compoundBalanceReportAsText :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> TL.Text-compoundBalanceReportAsText ropts-  (CompoundPeriodicReport title _colspans subreports netrow) =-    TB.toLazyText $-      TB.fromText title <> TB.fromText "\n\n" <>-      balanceReportTableAsText ropts bigtable'+compoundBalanceReportAsText ropts (CompoundPeriodicReport title _colspans subreports totalsrow) =+  TB.toLazyText $+    TB.fromText title <> TB.fromText "\n\n" <>+    multiBalanceReportTableAsText ropts bigtablewithtotalsrow   where     bigtable =       case map (subreportAsTable ropts) subreports of-        []   -> Tab.empty-        r:rs -> foldl' (concatTables DoubleLine) r rs-    bigtable'-      | no_total_ ropts || length subreports == 1 =-          bigtable-      | otherwise =-        let totalrows = multiBalanceRowAsTableText ropts netrow-            rh = Tab.Group NoLine $ map Header ("Net:" : replicate (length totalrows - 1) "")-            ch = Header [] -- ignored-         in ((concatTables Tab.DoubleLine) bigtable $ Table rh ch totalrows)+        []   -> Tabular.empty+        r:rs -> foldl' (concatTables tableInterSubreportBorder) r rs+    bigtablewithtotalsrow =+      if no_total_ ropts || length subreports == 1+      then bigtable+      else concatTables tableGrandTotalsTopBorder bigtable totalstable+        where+          -- Append the report's grand column totals at the bottom of the table.+          -- Note "row" is confusingly overloaded here; *Report rows, Table rows,+          -- and visually apparent table rows are all distinct.+          -- With multiple currencies, in some layout modes, the column totals (a single report row)+          -- occupy multiple lines, which currently we put into multiple table rows,+          -- for convenience I guess, borderless so they look like a single visual row.+          --+          -- multiBalanceRowAsText gets a matrix of each line of each column total rendered as text+          -- (actually as WideBuilders), in line-major-order:+          --  [+          --   [COL1LINE1, COL2LINE1]+          --   [COL1LINE2, COL2LINE2]+          --  ]+          coltotalslines = multiBalanceRowAsText ropts totalsrow+          totalstable = Table+            (Group NoLine $ map Header $ "Net:" : replicate (length coltotalslines - 1) "")  -- row headers+            (Header [])     -- column headers, concatTables will discard these+            coltotalslines  -- cell values               -- | Convert a named multi balance report to a table suitable for     -- concatenating with others to make a compound balance report table.-    subreportAsTable ropts1 (title1, r, _) = t+    subreportAsTable ropts1 (title1, r, _) = tablewithtitle       where-        -- convert to table-        Table lefthdrs tophdrs cells = balanceReportAsTable ropts1 r-        -- tweak the layout-        t = Table (Tab.Group Tab.SingleLine [Tab.Header title1, lefthdrs]) tophdrs ([]:cells)+        tablewithtitle = Table+          (Group tableSubreportTitleBottomBorder [Header title1, lefthdrs])  -- row headers+          tophdrs     -- column headers+          ([]:cells)  -- cell values+          where+            Table lefthdrs tophdrs cells = multiBalanceReportAsTable ropts1 r +    tableSubreportTitleBottomBorder = SingleLine+    tableInterSubreportBorder       = DoubleLine+    tableGrandTotalsTopBorder       = DoubleLine+ -- | Render a compound balance report as CSV. -- Subreports' CSV is concatenated, with the headings rows replaced by a -- subreport title row, and an overall title row, one headings row, and an -- optional overall totals row is added. compoundBalanceReportAsCsv :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> CSV-compoundBalanceReportAsCsv ropts (CompoundPeriodicReport title colspans subreports netrow) =+compoundBalanceReportAsCsv ropts (CompoundPeriodicReport title colspans subreports totalrow) =     addtotals $       padRow title       : ( "Account"@@ -276,13 +320,13 @@             map (length . prDates . second3) subreports     addtotals       | no_total_ ropts || length subreports == 1 = id-      | otherwise = (++ fmap ("Net:" : ) (multiBalanceRowAsCsvText ropts colspans netrow))+      | otherwise = (++ map ("Net:" : ) (multiBalanceRowAsCsvText ropts colspans totalrow))  -- | Render a compound balance report as HTML. compoundBalanceReportAsHtml :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> Html () compoundBalanceReportAsHtml ropts cbr =   let-    CompoundPeriodicReport title colspans subreports netrow = cbr+    CompoundPeriodicReport title colspans subreports totalrow = cbr     colspanattr = colspan_ $ T.pack $ show $ sum [       1,       length colspans,@@ -294,16 +338,14 @@     blankrow = tr_ $ td_ [colspanattr] $ toHtmlRaw ("&nbsp;"::String)      titlerows =-      (tr_ $ th_ [colspanattr, leftattr] $ h2_ $ toHtml title)-      : [thRow $-         "" : ["Commodity" | layout_ ropts == LayoutBare] ++-         map (reportPeriodName (balanceaccum_ ropts) colspans) colspans-         ++ (if row_total_ ropts then ["Total"] else [])-         ++ (if average_ ropts then ["Average"] else [])-        ]--    thRow :: [T.Text] -> Html ()-    thRow = tr_ . mconcat . map (th_ . toHtml)+      [tr_ $ th_ [colspanattr, leftattr] $ h2_ $ toHtml title+      ,tr_ $ do+          th_ ""+          when (layout_ ropts == LayoutBare) $ th_ "Commodity"+          mconcat $ map (th_ [style_ alignright] . toHtml . reportPeriodName (balanceaccum_ ropts) colspans) colspans+          th_ $ if row_total_ ropts then "Total"   else ""+          th_ $ if average_ ropts   then "Average" else ""+      ]      -- Make rows for a subreport: its title row, not the headings row,     -- the data rows, any totals row, and a blank row for whitespace.@@ -312,20 +354,30 @@       let         (_,bodyrows,mtotalsrows) = multiBalanceReportHtmlRows ropts mbr       in-           [tr_ $ th_ [colspanattr, leftattr] $ toHtml subreporttitle]+           [tr_ $ th_ [colspanattr, leftattr, class_ "account"] $ toHtml subreporttitle]         ++ bodyrows         ++ mtotalsrows         ++ [blankrow] -    totalrows | no_total_ ropts || length subreports == 1 = []-      | otherwise = multiBalanceReportHtmlFootRow ropts <$> (("Net:" :) <$> multiBalanceRowAsCsvText ropts colspans netrow)+    totalrows =+      if no_total_ ropts || length subreports == 1 then []+      else+        multiBalanceRowAsCsvText ropts colspans totalrow  -- make a table of rendered lines of the report totals row+        & zipWith (:) ("Net:":repeat "")                  -- insert a headings column, with Net: on the first line only+        & zipWith3                                        -- convert to a list of HTML totals rows, marking the first for special styling+          (\f isfirstline r -> f isfirstline r)+          (repeat (multiBalanceReportHtmlFootRow ropts))+          (True : repeat False)+   in do-    style_ (T.unlines [""-      ,"td { padding:0 0.5em; }"-      ,"td:nth-child(1) { white-space:nowrap; }"-      ,"tr:nth-child(even) td { background-color:#eee; }"-      ])     link_ [rel_ "stylesheet", href_ "hledger.css"]+    stylesheet_ [+      ("table",collapse),+      ("th, td",lpad),+      ("th.account, td.account","padding-left:0;"),+      ("td:nth-child(1)", "white-space:nowrap"),+      ("tr:nth-child(even) td", "background-color:#eee")+      ]     table_ $ mconcat $          titlerows       ++ [blankrow]

@@ -0,0 +1,220 @@+{-|+Read extra CLI arguments from a hledger config file.+-}++{-# LANGUAGE ScopedTypeVariables #-}+{-# LANGUAGE NamedFieldPuns #-}+{-# LANGUAGE MultiWayIf #-}++module Hledger.Cli.Conf (+   getConf+  ,confLookup+)+where++import Control.Monad (void, forM)+import Control.Monad.Identity (Identity)+import Data.Functor ((<&>))+import qualified Data.Map as M+import Data.Maybe (catMaybes)+import Data.Text (Text)+import qualified Data.Text as T (pack)+import System.Directory (getHomeDirectory, getXdgDirectory, XdgDirectory (XdgConfig), doesFileExist, getCurrentDirectory)+import System.FilePath ((</>), takeDirectory)+import Text.Megaparsec+import Text.Megaparsec.Char++import Hledger (error', strip, words', RawOpts, expandPath)+import Hledger.Read.Common+import Hledger.Utils.Parse+import Hledger.Utils.Debug+import Safe (lastDef)+import Hledger.Data.RawOptions (collectopts)+++-- | A hledger config file.+data Conf = Conf {+   confFile :: FilePath+  -- ,confText :: String+  ,confFormat :: Int+  ,confSections :: [ConfSection]+} deriving (Eq,Show)++-- | One section in a hledger config file.+data ConfSection = ConfSection {+   csName :: SectionName+  ,csArgs :: [Arg]+} deriving (Eq,Show)++-- | The name of a config file section, with surrounding brackets and whitespace removed.+type SectionName = String++-- | A command line argument to be passed to CmdArgs.process.+-- It seems this should be a single command line argument (or flag or flag value).+-- If it contains spaces, those are treated as part of a single argument, as with CMD a "b c".+type Arg = String++nullconf = Conf {+   confFile = ""+  ,confFormat = 1+  ,confSections = []+}++-- | The --conf or --no-conf or default config file specified by command line options.+data ConfFileSpec =+    SomeConfFile FilePath  -- ^ use config file specified with --conf+  | NoConfFile             -- ^ don't use any config file (--no-conf)+  | AutoConfFile           -- ^ use the config file found by directory search (default)+  deriving (Eq,Show)++-- Get the conf file specification from options,+-- considering the rightmost --conf or --no-conf option if any.+confFileSpecFromRawOpts :: RawOpts -> ConfFileSpec+confFileSpecFromRawOpts = lastDef AutoConfFile . collectopts cfsFromRawOpt+  where+    cfsFromRawOpt ("conf",f)    = Just $ SomeConfFile f+    cfsFromRawOpt ("no-conf",_) = Just $ NoConfFile+    cfsFromRawOpt _             = Nothing++-- config reading++-- | Fetch all the arguments/options defined in a section with this name, if it exists.+-- This should be "general" for the unnamed first section, or a hledger command name.+confLookup :: SectionName -> Conf -> [Arg]+confLookup cmd Conf{confSections} =+  maybe [] (concatMap words') $  -- XXX PARTIAL+  M.lookup cmd $+  M.fromList [(csName,csArgs) | ConfSection{csName,csArgs} <- confSections]++-- | Try to read a hledger config from a config file specified by --conf,+-- or the first config file found in any of several default file paths.+-- If --no-conf was used, or if no file was specified or found, this returns a null Conf.+-- If a specified file, or the first file found, can not be read or parsed, this raises an error.+-- Otherwise this returns the parsed Conf, and the file path.+getConf :: RawOpts -> IO (Conf, Maybe FilePath)+getConf rawopts = do+  defconfpaths <- defaultConfFilePaths+  defconffiles <- fmap catMaybes $ forM defconfpaths $ \f -> do+    exists <- doesFileExist f+    return $ if exists then Just f else Nothing+  case (confFileSpecFromRawOpts rawopts, defconffiles) of+    -- As in Cli.hs, conf debug output always goes to stderr;+    -- that's ok as conf is a hledger cli feature for now.+    (SomeConfFile f,   _) -> getCurrentDirectory >>= flip expandPath f >>= readConfFile+    (NoConfFile, _)       -> return $ traceAt 1 "ignoring config files" (nullconf, Nothing)+    (AutoConfFile,f:_)    -> dbg8IO "found config files" defconffiles >> dbg1IO "using config file" f >> readConfFile f+    (AutoConfFile,[] )    -> return $ traceAt 1 "no config file found" (nullconf, Nothing)++-- | Read this config file and parse its contents, or raise an error.+readConfFile :: FilePath -> IO (Conf, Maybe FilePath)+readConfFile f = do+  ecs <- readFile f <&> parseConf f . T.pack+  case ecs of+    Left err -> error' $ errorBundlePretty err -- customErrorBundlePretty err+    Right cs -> return (nullconf{+       confFile     = f+      ,confFormat   = 1+      ,confSections = cs+      },+      Just f+      )++-- | Get the possible paths for a hledger config file, depending on the current directory.+defaultConfFilePaths :: IO [FilePath]+defaultConfFilePaths = do+  ds   <- confDirs+  home <- getHomeDirectory+  return $ dbg8 "possible config files" $+    flip map ds $ \d -> d </> if d==home then ".hledger.conf" else "hledger.conf"++-- | Get the directories to check for a hledger config file.+confDirs :: IO [FilePath]+confDirs = do+  xdgc <- getXdgDirectory XdgConfig "hledger"+  home <- getHomeDirectory+  here <- getCurrentDirectory+  dirs <- getDirsUpToRoot here+  let dirs2 = if home `elem` dirs then dirs else dirs <> [home]+  let dirs3 = if xdgc `elem` dirs2 then dirs2 else dirs2 <> [xdgc]+  return $ dbg8 "searching config dirs" dirs3++-- | Get this directory and all of its parents up to /.+getDirsUpToRoot :: FilePath -> IO [FilePath]+getDirsUpToRoot dir = return $ go [] dir+  where+    go seen d = if+      | d `elem` seen || length seen >= 100 -> []  -- just in case+      | d=="/"    -> [d]+      | otherwise -> d : go (d:seen) (takeDirectory d)++-- config file parsing++parseConf :: FilePath -> Text -> Either (ParseErrorBundle Text HledgerParseErrorData) [ConfSection]+parseConf = runParser confp++dp :: String -> TextParser m ()+dp = const $ return ()  -- no-op+-- dp = dbgparse 1  -- trace parse state at this --debug level++whitespacep, commentlinesp, restoflinep :: TextParser Identity ()+whitespacep   = void $ {- dp "whitespacep"   >> -} many spacenonewline+commentlinesp = void $ {- dp "commentlinesp" >> -} many (emptyorcommentlinep2 "#")+restoflinep   = void $ {- dp "restoflinep"   >> -} whitespacep >> emptyorcommentlinep2 "#"++confp :: TextParser Identity [ConfSection]  -- a monadic TextParser to allow reusing other hledger parsers+confp = do+  dp "confp"+  commentlinesp+  genas <- many arglinep+  let s = ConfSection "general" genas+  ss <- many $ do+    (n, ma) <- sectionstartp+    as <- many arglinep+    return $ ConfSection n (maybe as (:as) ma)+  eof+  return $ s:ss++-- parse a section name and possibly arguments written on the same line+sectionstartp :: TextParser Identity (String, Maybe String)+sectionstartp = do+  dp "sectionstartp"+  char '['+  n <- fmap strip $ some $ noneOf "]#\n"+  char ']'+  -- dp "sectionstartp2"+  whitespacep+  -- dp "sectionstartp3"+  ma <- fmap (fmap strip) $ optional $ some $ noneOf "#\n"+  -- dp "sectionstartp4"+  restoflinep+  -- dp "sectionstartp5"+  commentlinesp+  -- dp "sectionstartp6"+  return (n, ma)++arglinep :: TextParser Identity String+arglinep = do+  dp "arglinep"+  notFollowedBy $ char '['+  -- dp "arglinep2"+  whitespacep+  -- dp "arglinep3"+  a <- some $ noneOf "#\n"+  -- dp "arglinep4"+  restoflinep+  commentlinesp+  return $ strip a+++-- initialiseAndParseJournal :: ErroringJournalParser IO ParsedJournal -> InputOpts+--                           -> FilePath -> Text -> ExceptT String IO Journal+-- initialiseAndParseJournal parser iopts f txt =+--     prettyParseErrors $ runParserT (evalStateT parser initJournal) f txt+--   where+--     y = first3 . toGregorian $ _ioDay iopts+--     initJournal = nulljournal{jparsedefaultyear = Just y, jincludefilestack = [f]}+--     -- Flatten parse errors and final parse errors, and output each as a pretty String.+--     prettyParseErrors :: ExceptT FinalParseError IO (Either (ParseErrorBundle Text HledgerParseErrorData) a)+--                       -> ExceptT String IO a+--     prettyParseErrors = withExceptT customErrorBundlePretty . liftEither+--                     <=< withExceptT (finalErrorBundlePretty . attachSource f txt)

@@ -21,6 +21,7 @@ import qualified Data.ByteString.Char8 as BC import Data.Maybe (fromMaybe) import Data.String+import System.Environment (setEnv) import System.IO import System.IO.Temp import System.Process@@ -147,15 +148,19 @@ -- | Display one of the hledger tldr pages, using "tldr". runTldrForPage :: TldrPage -> IO () runTldrForPage name =-  let tldrprog = "tldr" in   case tldr name of     Nothing -> error' $ "sorry, there's no " <> name <> " tldr page yet"     Just b -> (do       withSystemTempFile (name++".md") $ \f h -> do         BC.hPutStrLn h b         hClose h-        callCommand $ dbg1 "tldr command" $ unwords [tldrprog, "-r", f]+        -- tldr clients tend to auto-update their data, try to discourage that here+        -- tealdeer - doesn't auto-update by default+        -- tlrc - ?+        -- tldr-node-client - undocumented env var suggested in output+        setEnv "TLDR_AUTO_UPDATE_DISABLED" "1"+        callCommand $ dbg1 "tldr command" $ "tldr --render " <> f       ) `catch` (\(_e::IOException) -> do-        hPutStrLn stderr $ "Could not run " <> tldrprog <> ", using fallback viewer:\n"+        hPutStrLn stderr $ "Warning: could not run tldr --render, using fallback viewer instead.\n"         BC.putStrLn b       )

@@ -13,7 +13,7 @@  - Import new transactions from all CSV files, using the same rules for all: -`hledger import --rules-file {{common.rules}} *.csv`+`hledger import --rules {{common.rules}} *.csv`  - Show conversion errors or results while editing `bank.csv.rules`: 

@@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34 " "hledger User Manuals"+.TH "HLEDGER\-UI" "1" "September 2024" "hledger-ui-1.40 " "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.34.+This manual is for hledger\[aq]s terminal interface, version 1.40. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for@@ -70,12 +70,13 @@ .IP .EX General input/data transformation flags:-  \-f \-\-file=FILE            Read data from FILE, or from stdin if \-. Can be-                            specified more than once. If not specified, reads-                            from $LEDGER_FILE or $HOME/.hledger.journal.-     \-\-rules\-file=RULEFILE  Use conversion rules from this file for+  \-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.rules for each such FILE.+                            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@@ -138,7 +139,6 @@      \-\-pretty[=YN]          Use box\-drawing characters in text output? Can be                             \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].                             If YN is specified, the equals is required.-     \-\-debug=[1\-9]          show this level of debug output (default: 1)  General help flags:   \-h \-\-help                 show command line help@@ -146,6 +146,7 @@      \-\-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) .EE .PP With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to@@ -177,31 +178,10 @@ (\f[CR]CTRL\-p\f[R]/\f[CR]CTRL\-n\f[R]/\f[CR]CTRL\-f\f[R]/\f[CR]CTRL\-b\f[R]) and VI\-style (\f[CR]k\f[R],\f[CR]j\f[R],\f[CR]l\f[R],\f[CR]h\f[R]) movement keys are also supported.-A tip: movement speed is limited by your keyboard repeat rate, to move-faster you may want to adjust it.-(If you\[aq]re on a mac, the karabiner app is one way to do that.) .PP-With shift pressed, the cursor keys adjust the report period, limiting-the transactions to be shown (by default, all are shown).-\f[CR]SHIFT\-DOWN/UP\f[R] steps downward and upward through these-standard report period durations: year, quarter, month, week, day.-Then, \f[CR]SHIFT\-LEFT/RIGHT\f[R] moves to the previous/next period.-\f[CR]T\f[R] sets the report period to today.-With the \f[CR]\-w/\-\-watch\f[R] option, when viewing a-\[dq]current\[dq] period (the current day, week, month, quarter, or-year), the period will move automatically to track the current date.-To set a non\-standard period, you can use \f[CR]/\f[R] and a-\f[CR]date:\f[R] query.-.PP-(Mac users: SHIFT\-DOWN/UP keys do not work by default in Terminal, as-of MacOS Monterey.-You can configure them as follows: open Terminal, press CMD\-comma to-open preferences, click Profiles, select your current terminal profile-on the left, click Keyboard on the right, click + and add this for-Shift\-Down: \f[CR]\[rs]033[1;2B\f[R], click + and add this for-Shift\-Up: \f[CR]\[rs]033[1;2A\f[R].-Press the Escape key to enter the \f[CR]\[rs]033\f[R] part, you-can\[aq]t type it directly.)+(Tip: movement speed is limited by your keyboard repeat rate, to move+faster you may want to adjust it.+On a mac, the Karabiner app is one way to do that.) .PP \f[CR]/\f[R] lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger\-web.@@ -217,6 +197,31 @@ transactions generated by rule. \f[CR]F\f[R] toggles forecast mode, in which future/forecasted transactions are shown.+.PP+Pressing \f[CR]SHIFT\-DOWN\f[R] narrows the report period, and pressing+\f[CR]SHIFT\-UP\f[R] expands it again.+When narrowed, the current report period is displayed in the header+line, pressing \f[CR]SHIFT\-LEFT\f[R] or \f[CR]SHIFT\-RIGHT\f[R] moves+to the previous or next period, and pressing \f[CR]T\f[R] sets the+period to \[dq]today\[dq].+If you are using \f[CR]\-w/\-\-watch\f[R] and viewing a narrowed period+containing today, the view will follow any changes in system date+(moving to the period containing the new date).+.PP+You can also specify a non\-standard period with \f[CR]/\f[R] and a+\f[CR]date:\f[R] query; in this case, the period is not movable with the+arrow keys.+.PP+(Tip: arrow keys with Shift do not work out of the box in all terminal+software.+Eg in Apple\[aq]s Terminal, the SHIFT\-DOWN and SHIFT\-UP keys must be+configured as follows: in Terminal\[aq]s preferences, click Profiles,+select your current profile on the left, click Keyboard on the right,+click + and add this for SHIFT\-DOWN: \f[CR]\[rs]033[1;2B\f[R], click ++and add this for SHIFT\-UP: \f[CR]\[rs]033[1;2A\f[R].+\ In other terminals (Windows Terminal ?)+you might need to configure SHIFT\-RIGHT and SHIFT\-LEFT to emit+\f[CR]\[rs]033[1;2C\f[R] and \f[CR]\[rs]033[1;2D\f[R] respectively.) .PP \f[CR]ESCAPE\f[R] resets the UI state and jumps back to the top screen, restoring the app\[aq]s initial state at startup.

@@ -18,7 +18,7 @@ or 'hledger ui -- [OPTS] [QUERYARGS]' -   This manual is for hledger's terminal interface, version 1.34.  See+   This manual is for hledger's terminal interface, version 1.40.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -81,12 +81,13 @@    and also supports many of hledger's general options:  General input/data transformation flags:-  -f --file=FILE            Read data from FILE, or from stdin if -. Can be-                            specified more than once. If not specified, reads-                            from $LEDGER_FILE or $HOME/.hledger.journal.-     --rules-file=RULEFILE  Use conversion rules from this file for+  -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.rules for each such FILE.+                            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@@ -149,7 +150,6 @@      --pretty[=YN]          Use box-drawing characters in text output? Can be                             'y'/'yes' or 'n'/'no'.                             If YN is specified, the equals is required.-     --debug=[1-9]          show this level of debug output (default: 1)  General help flags:   -h --help                 show command line help@@ -157,6 +157,7 @@      --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)     With hledger-ui, the '--debug' option sends debug output to a 'hledger-ui.log' file in the current directory.@@ -191,27 +192,11 @@ returns to the previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END' move up and down through lists.  Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') and VI-style ('k','j','l','h')-movement keys are also supported.  A tip: movement speed is limited by-your keyboard repeat rate, to move faster you may want to adjust it.-(If you're on a mac, the karabiner app is one way to do that.)--   With shift pressed, the cursor keys adjust the report period,-limiting the transactions to be shown (by default, all are shown).-'SHIFT-DOWN/UP' steps downward and upward through these standard report-period durations: year, quarter, month, week, day.  Then,-'SHIFT-LEFT/RIGHT' moves to the previous/next period.  'T' sets the-report period to today.  With the '-w/--watch' option, when viewing a-"current" period (the current day, week, month, quarter, or year), the-period will move automatically to track the current date.  To set a-non-standard period, you can use '/' and a 'date:' query.+movement keys are also supported. -   (Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as-of MacOS Monterey.  You can configure them as follows: open Terminal,-press CMD-comma to open preferences, click Profiles, select your current-terminal profile on the left, click Keyboard on the right, click + and-add this for Shift-Down: '\033[1;2B', click + and add this for Shift-Up:-'\033[1;2A'.  Press the Escape key to enter the '\033' part, you can't-type it directly.)+   (Tip: movement speed is limited by your keyboard repeat rate, to move+faster you may want to adjust it.  On a mac, the Karabiner app is one+way to do that.)     '/' lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger-web.  While editing@@ -226,6 +211,26 @@ transactions generated by rule.  'F' toggles forecast mode, in which future/forecasted transactions are shown. +   Pressing 'SHIFT-DOWN' narrows the report period, and pressing+'SHIFT-UP' expands it again.  When narrowed, the current report period+is displayed in the header line, pressing 'SHIFT-LEFT' or 'SHIFT-RIGHT'+moves to the previous or next period, and pressing 'T' sets the period+to "today".  If you are using '-w/--watch' and viewing a narrowed period+containing today, the view will follow any changes in system date+(moving to the period containing the new date).++   You can also specify a non-standard period with '/' and a 'date:'+query; in this case, the period is not movable with the arrow keys.++   (Tip: arrow keys with Shift do not work out of the box in all+terminal software.  Eg in Apple's Terminal, the SHIFT-DOWN and SHIFT-UP+keys must be configured as follows: in Terminal's preferences, click+Profiles, select your current profile on the left, click Keyboard on the+right, click + and add this for SHIFT-DOWN: '\033[1;2B', click + and add+this for SHIFT-UP: '\033[1;2A'.  In other terminals (Windows Terminal ?)+you might need to configure SHIFT-RIGHT and SHIFT-LEFT to emit+'\033[1;2C' and '\033[1;2D' respectively.)+    'ESCAPE' resets the UI state and jumps back to the top screen, restoring the app's initial state at startup.  Or, it cancels minibuffer data entry or the help dialog.@@ -532,34 +537,34 @@ Node: Top221 Node: OPTIONS1870 Ref: #options1968-Node: MOUSE8148-Ref: #mouse8243-Node: KEYS8480-Ref: #keys8573-Node: SCREENS13228-Ref: #screens13332-Node: Menu screen13968-Ref: #menu-screen14089-Node: Cash accounts screen14284-Ref: #cash-accounts-screen14461-Node: Balance sheet accounts screen14645-Ref: #balance-sheet-accounts-screen14861-Node: Income statement accounts screen14981-Ref: #income-statement-accounts-screen15202-Node: All accounts screen15366-Ref: #all-accounts-screen15547-Node: Register screen15729-Ref: #register-screen15888-Node: Transaction screen18172-Ref: #transaction-screen18330-Node: Error screen19747-Ref: #error-screen19869-Node: WATCH MODE20113-Ref: #watch-mode20230-Node: ENVIRONMENT21689-Ref: #environment21805-Node: BUGS21996-Ref: #bugs22079+Node: MOUSE8234+Ref: #mouse8329+Node: KEYS8566+Ref: #keys8659+Node: SCREENS13394+Ref: #screens13498+Node: Menu screen14134+Ref: #menu-screen14255+Node: Cash accounts screen14450+Ref: #cash-accounts-screen14627+Node: Balance sheet accounts screen14811+Ref: #balance-sheet-accounts-screen15027+Node: Income statement accounts screen15147+Ref: #income-statement-accounts-screen15368+Node: All accounts screen15532+Ref: #all-accounts-screen15713+Node: Register screen15895+Ref: #register-screen16054+Node: Transaction screen18338+Ref: #transaction-screen18496+Node: Error screen19913+Ref: #error-screen20035+Node: WATCH MODE20279+Ref: #watch-mode20396+Node: ENVIRONMENT21855+Ref: #environment21971+Node: BUGS22162+Ref: #bugs22245  End Tag Table 

@@ -11,7 +11,7 @@        hledger ui -- [OPTS] [QUERYARGS]  DESCRIPTION-       This manual is for hledger's terminal  interface,  version  1.34.   See+       This manual is for hledger's terminal  interface,  version  1.40.   See        also the hledger manual for common concepts and file formats.         hledger  is a robust, user-friendly, cross-platform set of programs for@@ -59,12 +59,13 @@        and also supports many of hledger's general options:                General input/data transformation flags:-                -f --file=FILE            Read data from FILE, or from stdin if -. Can be-                                          specified more than once. If not specified, reads-                                          from $LEDGER_FILE or $HOME/.hledger.journal.-                   --rules-file=RULEFILE  Use conversion rules from this file for+                -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.rules for each such FILE.+                                          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@@ -127,7 +128,6 @@                    --pretty[=YN]          Use box-drawing characters in text output? Can be                                           'y'/'yes' or 'n'/'no'.                                           If YN is specified, the equals is required.-                   --debug=[1-9]          show this level of debug output (default: 1)                General help flags:                 -h --help                 show command line help@@ -135,6 +135,7 @@                    --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)         With  hledger-ui,  the  --debug  option  sends  debug   output   to   a        hledger-ui.log file in the current directory.@@ -160,28 +161,11 @@        The  cursor  keys navigate: RIGHT or ENTER goes deeper, LEFT returns to        the  previous  screen,  UP/DOWN/PGUP/PGDN/HOME/END  move  up  and  down        through  lists.  Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style-       (k,j,l,h) movement keys are also supported.  A tip: movement  speed  is-       limited  by  your  keyboard repeat rate, to move faster you may want to-       adjust it.  (If you're on a mac, the karabiner app is  one  way  to  do-       that.)--       With  shift pressed, the cursor keys adjust the report period, limiting-       the  transactions  to  be  shown   (by   default,   all   are   shown).-       SHIFT-DOWN/UP  steps  downward and upward through these standard report-       period   durations:   year,   quarter,   month,   week,   day.    Then,-       SHIFT-LEFT/RIGHT  moves to the previous/next period.  T sets the report-       period to today.  With the -w/--watch option, when viewing a  "current"-       period  (the  current  day,  week, month, quarter, or year), the period-       will move automatically to track the current date.  To set a  non-stan--       dard period, you can use / and a date: query.+       (k,j,l,h) movement keys are also supported. -       (Mac  users:  SHIFT-DOWN/UP keys do not work by default in Terminal, as-       of MacOS Monterey.  You can configure them as follows:  open  Terminal,-       press  CMD-comma  to open preferences, click Profiles, select your cur--       rent terminal profile on the left, click Keyboard on the right, click +-       and add this for Shift-Down:  \033[1;2B,  click  +  and  add  this  for-       Shift-Up:  \033[1;2A.  Press the Escape key to enter the \033 part, you-       can't type it directly.)+       (Tip: movement speed is limited by your keyboard repeat rate,  to  move+       faster  you  may want to adjust it.  On a mac, the Karabiner app is one+       way to do that.)         / lets you set a general filter query limiting the  data  shown,  using        the  same query terms as in hledger and hledger-web.  While editing the@@ -195,52 +179,72 @@        actions  generated  by  rule.   F  toggles  forecast mode, in which fu-        ture/forecasted transactions are shown. -       ESCAPE resets the UI state and jumps back to the top screen,  restoring+       Pressing SHIFT-DOWN narrows the report period,  and  pressing  SHIFT-UP+       expands  it  again.   When  narrowed, the current report period is dis-+       played in the header line, pressing SHIFT-LEFT or SHIFT-RIGHT moves  to+       the previous or next period, and pressing T sets the period to "today".+       If  you  are  using -w/--watch and viewing a narrowed period containing+       today, the view will follow any changes in system date (moving  to  the+       period containing the new date).++       You can also specify a non-standard period with / and a date: query; in+       this case, the period is not movable with the arrow keys.++       (Tip:  arrow keys with Shift do not work out of the box in all terminal+       software.  Eg in Apple's Terminal, the  SHIFT-DOWN  and  SHIFT-UP  keys+       must  be  configured  as follows: in Terminal's preferences, click Pro-+       files, select your current profile on the left, click Keyboard  on  the+       right,  click + and add this for SHIFT-DOWN: \033[1;2B, click + and add+       this for SHIFT-UP: \033[1;2A.   In other terminals (Windows Terminal ?)+       you  might  need  to  configure  SHIFT-RIGHT  and  SHIFT-LEFT  to  emit+       \033[1;2C and \033[1;2D respectively.)++       ESCAPE  resets the UI state and jumps back to the top screen, restoring        the app's initial state at startup.  Or, it cancels minibuffer data en-        try or the help dialog.         CTRL-l redraws the screen and centers the selection if possible (selec--       tions  near  the top won't be centered, since we don't scroll above the+       tions near the top won't be centered, since we don't scroll  above  the        top). -       g reloads from the data file(s) and updates the current screen and  any-       previous  screens.   (With  large  files, this could cause a noticeable+       g  reloads from the data file(s) and updates the current screen and any+       previous screens.  (With large files, this  could  cause  a  noticeable        pause.) -       I toggles balance assertion  checking.   Disabling  balance  assertions+       I  toggles  balance  assertion  checking.  Disabling balance assertions        temporarily can be useful for troubleshooting. -       a  runs  command-line  hledger's  add  command, and reloads the updated+       a runs command-line hledger's add  command,  and  reloads  the  updated        file.  This allows some basic data entry. -       A is like a, but runs the hledger-iadd tool, which provides a  terminal-       interface.   This key will be available if hledger-iadd is installed in+       A  is like a, but runs the hledger-iadd tool, which provides a terminal+       interface.  This key will be available if hledger-iadd is installed  in        $path. -       E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a  ""-       -nw)  on  the  journal file.  With some editors (emacs, vi), the cursor-       will be positioned at the current transaction  when  invoked  from  the-       register  and transaction screens, and at the error location (if possi-+       E  runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""+       -nw) on the journal file.  With some editors (emacs,  vi),  the  cursor+       will  be  positioned  at  the current transaction when invoked from the+       register and transaction screens, and at the error location (if  possi-        ble) when invoked from the error screen. -       B toggles cost mode, showing amounts converted to their cost's  commod-+       B  toggles cost mode, showing amounts converted to their cost's commod-        ity (see hledger manual > Cost reporting. -       V  toggles  value mode, showing amounts converted to their market value+       V toggles value mode, showing amounts converted to their  market  value        (see hledger manual > Valuation flag).  More specifically, -       1. By default, the V key toggles showing end value (--value=end) on  or-          off.   The  valuation date will be the report end date if specified,+       1. By  default, the V key toggles showing end value (--value=end) on or+          off.  The valuation date will be the report end date  if  specified,           otherwise today. -       2. If you  started  hledger-ui  with  some  other  valuation  (such  as+       2. If  you  started  hledger-ui  with  some  other  valuation  (such as           --value=then,EUR), the V key toggles that off or on. -       Cost/value  tips:  -  When showing end value, you can change the report-       end date without restarting, by pressing /  and  adding  a  query  like-       date:..YYYY-MM-DD.   -  Either cost mode, or value mode, can be active,-       but not both at once.  Cost mode takes precedence.  - There's  not  yet-       any  visual indicator that cost or value mode is active, other than the+       Cost/value tips: - When showing end value, you can  change  the  report+       end  date  without  restarting,  by  pressing / and adding a query like+       date:..YYYY-MM-DD.  - Either cost mode, or value mode, can  be  active,+       but  not  both at once.  Cost mode takes precedence.  - There's not yet+       any visual indicator that cost or value mode is active, other than  the        amount values.         q quits the application.@@ -248,47 +252,47 @@        Additional screen-specific keys are described below.  SCREENS-       At startup, hledger-ui shows a menu screen by default.  From  here  you+       At  startup,  hledger-ui shows a menu screen by default.  From here you        can navigate to other screens using the cursor keys: UP/DOWN to select,-       RIGHT  to  move  to the selected screen, LEFT to return to the previous+       RIGHT to move to the selected screen, LEFT to return  to  the  previous        screen.  Or you can use ESC to return directly to the top menu screen. -       You can also use a command line flag to specific  a  different  startup+       You  can  also  use a command line flag to specific a different startup        screen (--cs, --bs, --is, --all, or --register=ACCT).     Menu screen-       This  is  the  top-most  screen.  From here you can navigate to several-       screens listing accounts of various types.  Note some of these may  not+       This is the top-most screen.  From here you  can  navigate  to  several+       screens  listing accounts of various types.  Note some of these may not        show anything until you have configured account types.     Cash accounts screen        This screen shows "cash" (ie, liquid asset) accounts (like hledger bal--       ancesheet  type:c).   It  always shows balances (historical ending bal-+       ancesheet type:c).  It always shows balances  (historical  ending  bal-        ances on the date shown in the title line).     Balance sheet accounts screen-       This screen shows asset, liability and equity  accounts  (like  hledger+       This  screen  shows  asset, liability and equity accounts (like hledger        balancesheetequity).  It always shows balances.     Income statement accounts screen-       This  screen  shows revenue and expense accounts (like hledger incomes--       tatement).  It always shows changes  (balance  changes  in  the  period+       This screen shows revenue and expense accounts (like  hledger  incomes-+       tatement).   It  always  shows  changes  (balance changes in the period        shown in the title line).     All accounts screen-       This  screen  shows  all accounts in your journal (unless filtered by a-       query; like hledger balance).  It shows balances by  default;  you  can+       This screen shows all accounts in your journal (unless  filtered  by  a+       query;  like  hledger  balance).  It shows balances by default; you can        toggle showing changes with the H key.     Register screen-       This  screen  shows  the  transactions  affecting a particular account.+       This screen shows the  transactions  affecting  a  particular  account.        Each line represents one transaction, and shows: -       o the other account(s) involved, in abbreviated form.   (If  there  are-         both  real  and virtual postings, it shows only the accounts affected+       o the  other  account(s)  involved, in abbreviated form.  (If there are+         both real and virtual postings, it shows only the  accounts  affected          by real postings.) -       o the overall change to the current account's balance; positive for  an+       o the  overall change to the current account's balance; positive for an          inflow to this account, negative for an outflow.         o the running total after the transaction.  With the H key you can tog-@@ -296,90 +300,90 @@           o the period total, which is from just the transactions displayed -         o or  the  historical  total, which includes any undisplayed transac--           tions before the start of the report period (and matching the  fil--           ter  query  if  any).   This will be the running historical balance-           (what you would see on a bank's website, eg) if not disturbed by  a+         o or the historical total, which includes  any  undisplayed  transac-+           tions  before the start of the report period (and matching the fil-+           ter query if any).  This will be  the  running  historical  balance+           (what  you would see on a bank's website, eg) if not disturbed by a            query. -       Note,  this  screen combines each transaction's in-period postings to a-       single line item, dated with  the  earliest  in-period  transaction  or-       posting  date  (like hledger's aregister).  So custom posting dates can-       cause the running balance to be temporarily inaccurate.   (See  hledger+       Note, this screen combines each transaction's in-period postings  to  a+       single  line  item,  dated  with  the earliest in-period transaction or+       posting date (like hledger's aregister).  So custom posting  dates  can+       cause  the  running balance to be temporarily inaccurate.  (See hledger        manual > aregister and posting dates.) -       Transactions  affecting  this account's subaccounts will be included in+       Transactions affecting this account's subaccounts will be  included  in        the register if the accounts screen is in tree mode, or if it's in list-       mode but this account has subaccounts which are  not  shown  due  to  a-       depth  limit.   In  other words, the register always shows the transac--       tions contributing to the balance shown on the accounts  screen.   Tree+       mode  but  this  account  has  subaccounts which are not shown due to a+       depth limit.  In other words, the register always  shows  the  transac-+       tions  contributing  to the balance shown on the accounts screen.  Tree        mode/list mode can be toggled with t here also. -       U  toggles  filtering  by  unmarked  status, showing or hiding unmarked+       U toggles filtering by unmarked  status,  showing  or  hiding  unmarked        transactions.  Similarly, P toggles pending transactions, and C toggles-       cleared transactions.  (By default, transactions with all statuses  are-       shown;  if  you activate one or two status filters, only those transac-+       cleared  transactions.  (By default, transactions with all statuses are+       shown; if you activate one or two status filters, only  those  transac-        tions are shown; and if you activate all three, the filter is removed.)         R toggles real mode, in which virtual postings are ignored. -       z toggles nonzero mode, in which only transactions  posting  a  nonzero-       change  are  shown (hledger-ui shows zero items by default, unlike com-+       z  toggles  nonzero  mode, in which only transactions posting a nonzero+       change are shown (hledger-ui shows zero items by default,  unlike  com-        mand-line hledger).         Press RIGHT to view the selected transaction in detail.     Transaction screen-       This screen shows a single transaction, as  a  general  journal  entry,-       similar  to  hledger's  print command and journal format (hledger_jour-+       This  screen  shows  a  single transaction, as a general journal entry,+       similar to hledger's print command and  journal  format  (hledger_jour-        nal(5)). -       The transaction's date(s) and any cleared flag, transaction  code,  de--       scription,  comments, along with all of its account postings are shown.-       Simple transactions have two postings, but there can  be  more  (or  in+       The  transaction's  date(s) and any cleared flag, transaction code, de-+       scription, comments, along with all of its account postings are  shown.+       Simple  transactions  have  two  postings, but there can be more (or in        certain cases, fewer). -       UP  and  DOWN will step through all transactions listed in the previous-       account register screen.  In the title bar, the numbers in  parentheses-       show  your  position  within that account register.  They will vary de-+       UP and DOWN will step through all transactions listed in  the  previous+       account  register screen.  In the title bar, the numbers in parentheses+       show your position within that account register.  They  will  vary  de-        pending on which account register you came from (remember most transac--       tions appear in multiple account registers).  The #N  number  preceding+       tions  appear  in multiple account registers).  The #N number preceding        them is the transaction's position within the complete unfiltered jour-        nal, which is a more stable id (at least until the next reload).         On this screen (and the register screen), the E key will open your text-       editor  with the cursor positioned at the current transaction if possi-+       editor with the cursor positioned at the current transaction if  possi-        ble. -       This screen has a limitation with showing file  updates:  it  will  not-       show  them  until you exit and re-enter it.  So eg to see the effect of+       This  screen  has  a  limitation with showing file updates: it will not+       show them until you exit and re-enter it.  So eg to see the  effect  of        using the E key, currently you must: - press E, edit and save the file,-       then exit the editor, returning to hledger-ui - press g to  reload  the-       file  (or  use  -w/--watch  mode)  -  press LEFT then RIGHT to exit and+       then  exit  the editor, returning to hledger-ui - press g to reload the+       file (or use -w/--watch mode) - press  LEFT  then  RIGHT  to  exit  and        re-enter the transaction screen.     Error screen-       This screen will appear if there is a problem, such as a  parse  error,-       when  you  press g to reload.  Once you have fixed the problem, press g+       This  screen  will appear if there is a problem, such as a parse error,+       when you press g to reload.  Once you have fixed the problem,  press  g        again to reload and resume normal operation.  (Or, you can press escape        to cancel the reload attempt.)  WATCH MODE-       One of hledger-ui's best  features  is  the  auto-reloading  -w/--watch-       mode.   With  this flag, it will update the display automatically when-+       One  of  hledger-ui's  best  features  is the auto-reloading -w/--watch+       mode.  With this flag, it will update the display  automatically  when-        ever changes are saved to the data files. -       This is very useful when reconciling.  A good workflow is to have  your-       bank's  online  register  open  in a browser window, for reference; the-       journal file open in an editor window; and hledger-ui in watch mode  in+       This  is very useful when reconciling.  A good workflow is to have your+       bank's online register open in a browser  window,  for  reference;  the+       journal  file open in an editor window; and hledger-ui in watch mode in        a terminal window, eg:                $ hledger-ui --watch --register checking -C -       As  you mark things cleared in the editor, you can see the effect imme--       diately without having to context  switch.   This  leaves  more  mental-       bandwidth  for  your accounting.  Of course you can still interact with-       hledger-ui when needed, eg to toggle cleared mode, or  to  explore  the+       As you mark things cleared in the editor, you can see the effect  imme-+       diately  without  having  to  context  switch.  This leaves more mental+       bandwidth for your accounting.  Of course you can still  interact  with+       hledger-ui  when  needed,  eg to toggle cleared mode, or to explore the        history.         There are currently some limitations with --watch:@@ -387,27 +391,27 @@        It may not work correctly for you, depending on platform or system con-        figuration.  (Eg #836.) -       At  least  on mac, there can be a slow build-up of CPU usage over time,-       until the program is restarted  (or,  suspending  and  restarting  with+       At least on mac, there can be a slow build-up of CPU usage  over  time,+       until  the  program  is  restarted  (or, suspending and restarting with        CTRL-z fg may be enough). -       It  will  not detect file changes made by certain editors, such as Jet--       brains IDEs or gedit, or on certain less common filesystems.  (To  work-       around,   press   g   to   reload  manually,  or  try  #1617's  fs.ino-+       It will not detect file changes made by certain editors, such  as  Jet-+       brains  IDEs or gedit, or on certain less common filesystems.  (To work+       around,  press  g  to  reload  manually,   or   try   #1617's   fs.ino-        tify.max_user_watches workaround and let us know.) -       If you are viewing files  mounted  from  another  machine,  the  system+       If  you  are  viewing  files  mounted  from another machine, the system        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+       LEDGER_FILE The main journal  file  to  use  when  not  specified  with        -f/--file.  Default: $HOME/.hledger.journal.  BUGS        We  welcome  bug  reports  in  the  hledger  issue  tracker  (shortcut:-       http://bugs.hledger.org),  or on the #hledger chat or hledger mail list+       http://bugs.hledger.org), or on the #hledger chat or hledger mail  list        (https://hledger.org/support).         Some known issues:@@ -419,7 +423,7 @@        The Transaction screen does not update from file changes until you exit        and re-endter it (see SCREENS > Transaction above). -       --watch is not yet fully  robust  on  all  platforms  (see  Watch  mode+       --watch  is  not  yet  fully  robust  on  all platforms (see Watch mode        above).  @@ -440,4 +444,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.34                    June 2024                     HLEDGER-UI(1)+hledger-ui-1.40                 September 2024                   HLEDGER-UI(1)

@@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34 " "hledger User Manuals"+.TH "HLEDGER\-WEB" "1" "September 2024" "hledger-web-1.40 " "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.34.+This manual is for hledger\[aq]s web interface, version 1.40. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for@@ -121,12 +121,13 @@ .IP .EX General input/data transformation flags:-  \-f \-\-file=FILE            Read data from FILE, or from stdin if \-. Can be-                            specified more than once. If not specified, reads-                            from $LEDGER_FILE or $HOME/.hledger.journal.-     \-\-rules\-file=RULEFILE  Use conversion rules from this file for+  \-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.rules for each such FILE.+                            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@@ -189,7 +190,6 @@      \-\-pretty[=YN]          Use box\-drawing characters in text output? Can be                             \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].                             If YN is specified, the equals is required.-     \-\-debug=[1\-9]          show this level of debug output (default: 1)  General help flags:   \-h \-\-help                 show command line help@@ -197,6 +197,7 @@      \-\-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) .EE .PP hledger\-web shows accounts with zero balances by default (like

@@ -18,7 +18,7 @@ or 'hledger web -- [OPTS] [QUERY]' -   This manual is for hledger's web interface, version 1.34.  See also+   This manual is for hledger's web interface, version 1.40.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -126,12 +126,13 @@    hledger-web also supports many of hledger's general options:  General input/data transformation flags:-  -f --file=FILE            Read data from FILE, or from stdin if -. Can be-                            specified more than once. If not specified, reads-                            from $LEDGER_FILE or $HOME/.hledger.journal.-     --rules-file=RULEFILE  Use conversion rules from this file for+  -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.rules for each such FILE.+                            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@@ -194,7 +195,6 @@      --pretty[=YN]          Use box-drawing characters in text output? Can be                             'y'/'yes' or 'n'/'no'.                             If YN is specified, the equals is required.-     --debug=[1-9]          show this level of debug output (default: 1)  General help flags:   -h --help                 show command line help@@ -202,6 +202,7 @@      --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)     hledger-web shows accounts with zero balances by default (like 'hledger-ui', and unlike 'hledger').  Using the '-E/--empty' flag will@@ -524,22 +525,22 @@ Node: Top223 Node: OPTIONS2566 Ref: #options2671-Node: PERMISSIONS10859-Ref: #permissions10998-Node: EDITING UPLOADING DOWNLOADING12210-Ref: #editing-uploading-downloading12391-Node: RELOADING13225-Ref: #reloading13359-Node: JSON API13792-Ref: #json-api13907-Node: DEBUG OUTPUT19441-Ref: #debug-output19566-Node: Debug output19593-Ref: #debug-output-119694-Node: ENVIRONMENT20111-Ref: #environment20230-Node: BUGS20347-Ref: #bugs20431+Node: PERMISSIONS10945+Ref: #permissions11084+Node: EDITING UPLOADING DOWNLOADING12296+Ref: #editing-uploading-downloading12477+Node: RELOADING13311+Ref: #reloading13445+Node: JSON API13878+Ref: #json-api13993+Node: DEBUG OUTPUT19527+Ref: #debug-output19652+Node: Debug output19679+Ref: #debug-output-119780+Node: ENVIRONMENT20197+Ref: #environment20316+Node: BUGS20433+Ref: #bugs20517  End Tag Table 

@@ -11,7 +11,7 @@        hledger web -- [OPTS] [QUERY]  DESCRIPTION-       This manual is for hledger's web interface, version 1.34.  See also the+       This manual is for hledger's web interface, version 1.40.  See also the        hledger manual for common concepts and file formats.         hledger is a robust, user-friendly, cross-platform set of programs  for@@ -103,12 +103,13 @@        hledger-web also supports many of hledger's general options:                General input/data transformation flags:-                -f --file=FILE            Read data from FILE, or from stdin if -. Can be-                                          specified more than once. If not specified, reads-                                          from $LEDGER_FILE or $HOME/.hledger.journal.-                   --rules-file=RULEFILE  Use conversion rules from this file for+                -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.rules for each such FILE.+                                          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@@ -171,7 +172,6 @@                    --pretty[=YN]          Use box-drawing characters in text output? Can be                                           'y'/'yes' or 'n'/'no'.                                           If YN is specified, the equals is required.-                   --debug=[1-9]          show this level of debug output (default: 1)                General help flags:                 -h --help                 show command line help@@ -179,6 +179,7 @@                    --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)         hledger-web   shows  accounts  with  zero  balances  by  default  (like        hledger-ui, and unlike hledger).  Using the -E/--empty  flag  will  re-@@ -473,4 +474,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.34                   June 2024                    HLEDGER-WEB(1)+hledger-web-1.40                September 2024                  HLEDGER-WEB(1)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "June 2024" "hledger-1.34 " "hledger User Manuals"+.TH "HLEDGER" "1" "September 2024" "hledger-1.40 " "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.34.+This manual is for hledger\[aq]s command line interface, version 1.40. 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!@@ -42,13 +42,15 @@ It is detailed, so do skip ahead or skim when needed. You can read it on hledger.org, or as an info manual or man page on your system.-You can also get it from hledger itself with+You can also open a built\-in copy, at a point of interest, by running .PD 0 .P .PD-\f[CR]hledger \-\-man\f[R], \f[CR]hledger \-\-info\f[R] or+\f[CR]hledger \-\-man [CMD]\f[R], \f[CR]hledger \-\-info [CMD]\f[R] or \f[CR]hledger help [TOPIC]\f[R]. .PP+(And for shorter help, try \f[CR]hledger \-\-tldr [CMD]\f[R].)+.PP 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).@@ -109,7 +111,7 @@ You can specify a file with \f[CR]\-f\f[R], like so .IP .EX-$ hledger \-f FILE print+$ hledger \-f FILE [\-f FILE2 ...] print .EE .PP Files are most often in hledger\[aq]s journal format, with the@@ -337,17 +339,28 @@ \f[CR]hledger\-web \-\-serve\f[R]. .SH Options Run \f[CR]hledger \-h\f[R] to see general command line help.-The following general options are common to most hledger commands.-General options can be written either before or after the command name.+Options can be written either before or after the command name.+These options are specific to the \f[CR]hledger\f[R] CLI: .IP .EX+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+.EE+.PP+And the following general options are common to most hledger commands:+.IP+.EX General input/data transformation flags:-  \-f \-\-file=FILE            Read data from FILE, or from stdin if \-. Can be-                            specified more than once. If not specified, reads-                            from $LEDGER_FILE or $HOME/.hledger.journal.-     \-\-rules\-file=RULEFILE  Use conversion rules from this file for+  \-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.rules for each such FILE.+                            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@@ -410,7 +423,6 @@      \-\-pretty[=YN]          Use box\-drawing characters in text output? Can be                             \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].                             If YN is specified, the equals is required.-     \-\-debug=[1\-9]          show this level of debug output (default: 1)  General help flags:   \-h \-\-help                 show command line help@@ -418,6 +430,7 @@      \-\-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) .EE .PP Usually hledger accepts any unambiguous flag prefix, eg you can write@@ -708,12 +721,71 @@ argument. Eg: \f[CR]hledger bal \[at]foo.args\f[R]. .PP-Inside the argument file, each line should contain just one option or+(Inside the argument file, each line should contain just one option or argument.-Don\[aq]t use spaces except inside quotes (or you\[aq]ll see a confusing-error); write \f[CR]=\f[R] (or nothing) between a flag and its argument.+Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing+between a flag and its argument. For the special characters mentioned above, use one less level of-quoting than you would at the command prompt.+quoting than you would at the command prompt.)+.PP+Argument files are now superseded by..+.SS Config files+As of hledger 1.40, you can optionally save command line options (or+arguments) to be used when running hledger commands, in a config file.+Here\[aq]s a small example:+.IP+.EX+\f[I]# General options are listed first, one or more per line.\f[R]+\f[I]# These will be used with all hledger commands that support them.\f[R]+\-\-pretty++\f[I]# Options following a \[ga][COMMANDNAME]\[ga] heading are used with that hledger command only.\f[R]+\f[B][print]\f[R]+\-\-explicit \-\-show\-costs+.EE+.PP+To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.+Its options will be inserted near the start of your command line (so you+can override them if needed).+Or, you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config+file and execute it like a script.+.PP+Or, you can set up an automatic config file that is used whenever you+run hledger.+This can be \f[CR]hledger.conf\f[R] in the current directory or above,+or \f[CR].hledger.conf\f[R] in your home directory+(\f[CR]\[ti]/.hledger.conf\f[R]), or \f[CR]hledger.conf\f[R] in your XDG+config directory (\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).+.PP+You can ignore config files by adding the \f[CR]\-n/\-\-no\-conf\f[R]+flag.+This is useful when using hledger in scripts, or when troubleshooting.+(When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are+used, the right\-most wins.)+To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or+\f[CR]\-\-debug=8\f[R].+.PP+Here is another example config file you could start with:+https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample+.PP+Automatic config files are convenient, but have a cost: it\[aq]s easy to+change a report\[aq]s behaviour, or break scripts/applications which use+hledger, in unintended ways that will surprise you later.+They change the nature of hledger somewhat, making it less transparent+and predictable.+If you decide to use one, here are some tips:+.IP \[bu] 2+Be conservative about what you put in it.+Try to consider the effect on all your reports.+.IP \[bu] 2+Whenever a hledger command does not work as expected, try it again with+\f[CR]\-n\f[R].+.IP \[bu] 2+If that helps, you can run it with \f[CR]\-\-debug\f[R] to see how a+config file affected it.+.PP+This feature has been added in hledger 1.40 and is considered+\f[I]experimental\f[R]. .SH Output .SS Output destination hledger commands send their output to the terminal by default.@@ -740,7 +812,7 @@ .PP .TS tab(@);-lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).+lw(13.6n) lw(12.2n) lw(12.2n) lw(12.2n) lw(12.2n) lw(4.1n) lw(3.4n). T{ \- T}@T{@@ -750,6 +822,8 @@ T}@T{ html T}@T{+fods+T}@T{ json T}@T{ sql@@ -764,6 +838,7 @@ T}@T{ Y T}@T{+T}@T{ Y T}@T{ T}@@ -774,8 +849,10 @@ T}@T{ Y \f[I]1\f[R] T}@T{-Y \f[I]1,2\f[R]+Y \f[I]1\f[R] T}@T{+Y \f[I]1\f[R]+T}@T{ Y T}@T{ T}@@ -788,6 +865,7 @@ T}@T{ Y \f[I]1\f[R] T}@T{+T}@T{ Y T}@T{ T}@@ -800,6 +878,7 @@ T}@T{ Y \f[I]1\f[R] T}@T{+T}@T{ Y T}@T{ T}@@ -812,6 +891,7 @@ T}@T{ Y \f[I]1\f[R] T}@T{+T}@T{ Y T}@T{ T}@@ -824,6 +904,7 @@ T}@T{ Y \f[I]1\f[R] T}@T{+T}@T{ Y T}@T{ T}@@ -835,6 +916,7 @@ Y T}@T{ T}@T{+T}@T{ Y T}@T{ Y@@ -847,6 +929,7 @@ Y T}@T{ T}@T{+T}@T{ Y T}@T{ T}@@ -854,9 +937,6 @@ .IP \[bu] 2 \f[I]1 Also affected by the balance commands\[aq] \f[CI]\-\-layout\f[I] option.\f[R]-.IP \[bu] 2-\f[I]2 \f[CI]balance\f[I] does not support html output without a report-interval or with \f[CI]\-\-budget\f[I].\f[R] .PP The output format is selected by the \f[CR]\-O/\-\-output\-format=FMT\f[R] option:@@ -967,14 +1047,12 @@ otherwise, colour will be used if the output (terminal or file) supports it. .SS Box\-drawing-In terminal output, you can enable unicode box\-drawing characters to-render prettier tables:-.IP \[bu] 2-if the \f[CR]\-\-pretty\f[R] option is given a value of \f[CR]yes\f[R]-or \f[CR]always\f[R] (or \f[CR]no\f[R] or \f[CR]never\f[R]), unicode-characters will (or will not) be used;-.IP \[bu] 2-otherwise, unicode characters will not be used.+In terminal (text) output, to minimise the risk of display problems,+table borders are drawn using only ascii characters by default.+.PP+To see tables with prettier unicode box\-drawing characters, add the+\f[CR]\-\-pretty\f[R] flag.+This will also show outer borders and inter\-column borders. .SS Paging When showing long output in the terminal, hledger will try to use the pager specified by the \f[CR]PAGER\f[R] environment variable, or@@ -1063,7 +1141,7 @@ .PP Many users, though, edit the journal file with a text editor, and track changes with a version control system such as git.-Editor addons such as ledger\-mode or hledger\-mode for Emacs,+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.@@ -3658,8 +3736,8 @@ directory. Eg when asked to read \f[CR]foo/FILE.csv\f[R], hledger looks for \f[CR]foo/FILE.csv.rules\f[R].-You can specify a different rules file with the-\f[CR]\-\-rules\-file\f[R] option.+You can specify a different rules file with the \f[CR]\-\-rules\f[R]+option. .PP 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@@ -4547,8 +4625,8 @@ If you use multiple \f[CR]\-f\f[R] options to read multiple CSV files at once, hledger will look for a correspondingly\-named rules file for each CSV file.-But if you use the \f[CR]\-\-rules\-file\f[R] option, that rules file-will be used for all the CSV files.+But if you specify a rules file with \f[CR]\-\-rules\f[R], that rules+file will be used for all the CSV files. .SS Reading files specified by rule Instead of specifying a CSV file in the command line, you can specify a rules file, as in \f[CR]hledger \-f foo.csv.rules CMD\f[R].@@ -5288,11 +5366,17 @@ .PP To generate time logs, ie to clock in and clock out, you could: .IP \[bu] 2-use emacs and the built\-in timeclock.el, or the extended-timeclock\-x.el and perhaps the extras in ledgerutils.el+use these shell aliases at the command line:+.RS 2+.IP+.EX+alias ti=\[aq]echo i \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] $* >>$TIMELOG\[aq]+alias to=\[aq]echo o \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] >>$TIMELOG\[aq]+.EE+.RE .IP \[bu] 2-at the command line, use these bash aliases:-\f[CR]cli     alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq]     alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]+or Emacs\[aq]s built\-in timeclock.el, or the extended timeclock\-x.el,+and perhaps the extras in ledgerutils.el .IP \[bu] 2 or use the old \f[CR]ti\f[R] and \f[CR]to\f[R] scripts in the ledger 2.x repository.@@ -5646,26 +5730,62 @@ .PP More complex intervals can be specified using \f[CR]\-p/\-\-period\f[R], described below.-.SS Date adjustment-When there is a report interval (other than daily), report start/end-dates which have been inferred, eg from the journal, are automatically-adjusted to natural period boundaries.-This is convenient for producing simple periodic reports.-More precisely:+.SS Date adjustments+.SS Start date adjustment+If you let hledger infer a report\[aq]s start date, it will adjust the+date to the previous natural boundary of the report interval, for+convenient periodic reports.+(If you don\[aq]t want that, specify a start date.)+.PP+For example, if the journal\[aq]s first transaction is on january 10th, .IP \[bu] 2-an inferred start date will be adjusted earlier if needed to fall on a-natural period boundary+\f[CR]hledger register\f[R] (no report interval) will start the report+on january 10th. .IP \[bu] 2-an inferred end date will be adjusted later if needed to make the last-period the same length as the others.+\f[CR]hledger register \-\-monthly\f[R] will start the report on the+previous month boundary, january 1st.+.IP \[bu] 2+\f[CR]hledger register \-\-monthly \-\-begin 1/5\f[R] will start the+report on january 5th [1]. .PP-By contrast, start/end dates which have been specified explicitly, with-\f[CR]\-b\f[R], \f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R], will-not be adjusted (since hledger 1.29).-This makes it possible to specify non\-standard report periods, but it-also means that if you are specifying a start date, you should pick one-that\[aq]s on a period boundary if you want to see simple report period-headings.+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).+.SS End date adjustment+A report\[aq]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.+.PP+For example, if the journal\[aq]s last transaction is on february 20th,+.IP \[bu] 2+\f[CR]hledger register\f[R] will end the report on february 20th.+.IP \[bu] 2+\f[CR]hledger register \-\-monthly\f[R] will end the report at the end+of february.+.IP \[bu] 2+\f[CR]hledger register \-\-monthly \-\-end 2/14\f[R] also will end the+report at the end of february.+.IP \[bu] 2+\f[CR]hledger register \-\-monthly \-\-begin 1/5 \-\-end 2/14\f[R] will+end the report on march 4th [1].+.PP+[1] Since hledger 1.29.+.SS Period headings+With non\-standard subperiods, hledger will show+\[dq]STARTDATE..ENDDATE\[dq] headings.+With standard subperiods (ie, starting on a natural interval boundary),+you\[aq]ll see more compact headings, which are usually preferable.+(Though month names will be in english, currently.)+.PP+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 \f[CR]\-b 2024\f[R] or \f[CR]1/1\f[R] as a+shortcut for a start of year, or \f[CR]2024\-04\f[R] or+\f[CR]202404\f[R] or \f[CR]Apr\f[R] for a start of month or quarter.)+.PP+For weekly reports, choose a date that\[aq]s a Monday.+(You can try different dates until you see the short headings, or write+eg \f[CR]\-b \[aq]3 weeks ago\[aq]\f[R].) .SS Period expressions The \f[CR]\-p/\-\-period\f[R] option specifies a period expression, which is a compact way of expressing a start date, end date, and/or@@ -5832,7 +5952,7 @@ .IP \[bu] 2 \f[CR]every Nth WEEKDAYNAME [of month]\f[R] .PP-Yearly on a custom day:+Yearly on a custom month and day: .IP \[bu] 2 \f[CR]every MM/DD [of year]\f[R] (month number and day of month number) .IP \[bu] 2@@ -6478,7 +6598,7 @@ .EE .PP Here there are no ordinary transactions, so the forecasted transactions-begin on the first occurence after today\[aq]s date.+begin on the first occurrence after today\[aq]s date. (You won\[aq]t normally use \f[CR]\-\-today\f[R]; it\[aq]s just to make these examples reproducible.) .SS Forecast reports@@ -7714,7 +7834,6 @@ \f[CR]\-\-cumulative\f[R] is omitted to save space, it works like \f[CR]\-H\f[R] but with a zero starting balance. .SH PART 4: COMMANDS-\  .PP Here are the standard commands, which you can list by running \f[CR]hledger\f[R].@@ -7807,6 +7926,14 @@ pager. With a (case insensitive) TOPIC argument, try to open it at that section heading.+.IP+.EX+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)+.EE .PP This command shows the hledger manual built in to your hledger executable.@@ -7843,6 +7970,12 @@ .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.@@ -7877,6 +8010,11 @@ .SH Data entry commands .SS add Record new transactions with interactive prompting in the console.+.IP+.EX+Flags:+     \-\-no\-new\-accounts      don\[aq]t allow creating new accounts+.EE .PP Many hledger users edit their journals directly with a text editor, or generate them from CSV.@@ -7907,9 +8045,6 @@ \f[CR]tomorrow\f[R]). If the input area is empty, it will insert the default value. .IP \[bu] 2-If the journal defines a default commodity, it will be added to any bare-numbers entered.-.IP \[bu] 2 A parenthesised transaction code may be entered following a date. .IP \[bu] 2 Comments and tags may be entered following a description or amount.@@ -7953,6 +8088,12 @@ There is a detailed tutorial at https://hledger.org/add.html. .SS import Import new transactions from one or more data files to the main journal.+.IP+.EX+Flags:+     \-\-catchup              just mark all transactions as already imported+     \-\-dry\-run              just show the transactions to be imported+.EE .PP This command detects new transactions in each FILE argument since it was last run, and appends them to the main journal.@@ -8097,6 +8238,23 @@ .SH Basic report commands .SS accounts List account names.+.IP+.EX+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+.EE .PP This command lists account names. By default it shows all known accounts, either used in transactions or@@ -8160,6 +8318,11 @@ .EE .SS codes List the codes seen in transactions, in the order parsed.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP This command prints the value of each transaction\[aq]s code field, in the order transactions were parsed.@@ -8210,8 +8373,18 @@ .EE .SS commodities List all commodity/currency symbols used or declared in the journal.+.IP+.EX+Flags:+no command\-specific flags+.EE .SS descriptions List the unique descriptions that appear in transactions.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP This command lists the unique descriptions that appear in transactions, in alphabetic order.@@ -8229,8 +8402,18 @@ List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown.+.IP+.EX+Flags:+no command\-specific flags+.EE .SS notes List the unique notes that appear in transactions.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP This command lists the unique notes that appear in transactions, in alphabetic order.@@ -8247,6 +8430,12 @@ .EE .SS payees List the unique payee/payer names that appear in transactions.+.IP+.EX+Flags:+     \-\-declared             show payees declared with payee directives+     \-\-used                 show payees referenced by transactions+.EE .PP This command lists unique payee/payer names which have been declared with payee directives (\-\-declared), used in transaction descriptions@@ -8272,6 +8461,12 @@ from costs. With \-\-show\-reverse, also show additional prices inferred by reversing known prices.+.IP+.EX+Flags:+     \-\-show\-reverse         also show the prices inferred by reversing known+                            prices+.EE .PP Price amounts are always displayed with their full precision, except for reverse prices which are limited to 8 decimal digits.@@ -8285,6 +8480,12 @@ report with \-\-debug=2. .SS stats Show journal and performance statistics.+.IP+.EX+Flags:+  \-v \-\-verbose              show more detailed output+  \-o \-\-output\-file=FILE     write output to FILE.+.EE .PP The stats command shows summary information for the whole journal, or a matched part of it.@@ -8333,6 +8534,13 @@ \-O/\-\-output\-format). .SS tags List the tags used in the journal, or their values.+.IP+.EX+Flags:+     \-\-values               list tag values instead of tag names+     \-\-parsed               show tags/values in the order they were parsed,+                            including duplicates+.EE .PP This command lists the tag names used in the journal, whether on transactions, postings, or account declarations.@@ -8359,6 +8567,31 @@ .SH Standard report commands .SS print Show full journal entries, representing transactions.+.IP+.EX+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+  \-O \-\-output\-format=FMT    select the output format. Supported formats:+                            txt, beancount, csv, tsv, json, sql.+  \-o \-\-output\-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.+.EE .PP The print command displays full journal entries (transactions) from the journal file, sorted by date (or with \f[CR]\-\-date2\f[R], by secondary@@ -8552,6 +8785,21 @@ .PP Show the transactions and running balances in one account, with each transaction on one line.+.IP+.EX+Flags:+     \-\-txn\-dates            filter strictly by transaction date, not posting+                            date. Warning: this can show a wrong running+                            balance.+     \-\-no\-elide             don\[aq]t show only 2 commodities per amount+  \-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.+.EE .PP \f[CR]aregister\f[R] shows the overall transactions affecting a particular account (and any subaccounts).@@ -8641,6 +8889,30 @@ (reg) .PP Show postings and their running total.+.IP+.EX+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\[aq] 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)+  \-O \-\-output\-format=FMT    select the output format. Supported formats:+                            txt, csv, tsv, json.+  \-o \-\-output\-file=FILE     write output to FILE. A file extension matching+                            one of the above formats selects that format.+.EE .PP The register command displays matched postings, across all accounts, in date order, with their running total or running historical balance.@@ -8700,6 +8972,16 @@ normally displayed as negative numbers. It\[aq]s also useful to show postings on the checking account together with the related account:+.PP+The \f[CR]\-\-sort=FIELDS\f[R] flag sorts by the fields given, which can+be any of \f[CR]account\f[R], \f[CR]amount\f[R], \f[CR]absamount\f[R],+\f[CR]date\f[R], or \f[CR]desc\f[R]/\f[CR]description\f[R], optionally+separated by commas.+For example, \f[CR]\-\-sort account,amount\f[R] will group all+transactions in each account, sorted by transaction amount.+Each field can be negated by a preceding \f[CR]\-\f[R], so+\f[CR]\-\-sort \-amount\f[R] will show transactions ordered from+smallest amount to largest amount. .IP .EX $ hledger register \-\-related \-\-invert assets:checking@@ -8795,6 +9077,53 @@ Show the end balances in asset and liability accounts. Amounts are shown with normal positive sign, as in conventional financial statements.+.IP+.EX+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+     \-\-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\[aq]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\[aq]s+                            total+     \-\-layout=ARG           how to show multi\-commodity amounts:+                            \[aq]wide[,WIDTH]\[aq]: all commodities on one line+                            \[aq]tall\[aq]        : each commodity on a new line+                            \[aq]bare\[aq]        : bare numbers, symbols in a column+  \-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.+.EE .PP This command displays a balance sheet, showing historical ending balances of asset and liability accounts.@@ -8848,6 +9177,53 @@ balances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements.+.IP+.EX+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+     \-\-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\[aq]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\[aq]s+                            total+     \-\-layout=ARG           how to show multi\-commodity amounts:+                            \[aq]wide[,WIDTH]\[aq]: all commodities on one line+                            \[aq]tall\[aq]        : each commodity on a new line+                            \[aq]bare\[aq]        : bare numbers, symbols in a column+  \-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.+.EE .PP This report shows accounts declared with the \f[CR]Asset\f[R], \f[CR]Cash\f[R], \f[CR]Liability\f[R] or \f[CR]Equity\f[R] type (see@@ -8909,6 +9285,52 @@ assets. Amounts are shown with normal positive sign, as in conventional financial statements.+.IP+.EX+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+     \-\-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\[aq]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\[aq]s+                            total+     \-\-layout=ARG           how to show multi\-commodity amounts:+                            \[aq]wide[,WIDTH]\[aq]: all commodities on one line+                            \[aq]tall\[aq]        : each commodity on a new line+                            \[aq]bare\[aq]        : bare numbers, symbols in a column+  \-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.+.EE .PP This report shows accounts declared with the \f[CR]Cash\f[R] type (see account types).@@ -8960,6 +9382,52 @@ Show revenue inflows and expense outflows during the report period. Amounts are shown with normal positive sign, as in conventional financial statements.+.IP+.EX+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+     \-\-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\[aq]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\[aq]s+                            total+     \-\-layout=ARG           how to show multi\-commodity amounts:+                            \[aq]wide[,WIDTH]\[aq]: all commodities on one line+                            \[aq]tall\[aq]        : each commodity on a new line+                            \[aq]bare\[aq]        : bare numbers, symbols in a column+  \-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.+.EE .PP This command displays an income statement, showing revenues and expenses during one or more periods.@@ -9015,6 +9483,65 @@ with some kind of numeric data. This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc.+.IP+.EX+Flags:+     \-\-sum                  show sum of posting amounts (default)+     \-\-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).+     \-\-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)+     \-\-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)+  \-r \-\-related              show postings\[aq] siblings instead+  \-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\[aq]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\[aq]s+                            total+     \-\-invert               display all amounts with reversed sign+     \-\-transpose            transpose rows and columns+     \-\-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+  \-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.+.EE .PP \f[CR]balance\f[R] is one of hledger\[aq]s oldest and most versatile commands, for listing account balances, balance changes, values, value@@ -9104,7 +9631,7 @@ This command supports the output destination and output format options, with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports-only:) \f[CR]html\f[R].+only:) \f[CR]html\f[R], \f[CR]fods\f[R] (\f[I]Added in 1.40\f[R]). In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative amounts are shown in red. .SS Simple balance report@@ -10011,11 +10538,11 @@ \[dq]Assets:US:ETrade\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq] \[dq]Assets:US:ETrade\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq] \[dq]Assets:US:ETrade\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]-\[dq]total\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]-\[dq]total\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]-\[dq]total\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]-\[dq]total\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]-\[dq]total\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]+\[dq]Total:\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]+\[dq]Total:\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]+\[dq]Total:\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]+\[dq]Total:\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]+\[dq]Total:\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq] .EE .PP Bare layout will sometimes display an extra row for the no\-symbol@@ -10109,6 +10636,15 @@ .SS roi Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return on your investments.+.IP+.EX+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+.EE .PP At a minimum, you need to supply a query (which could be just an account name) to select your investment(s) with \f[CR]\-\-inv\f[R], and another@@ -10303,6 +10839,11 @@ .SH Chart commands .SS activity Show an ascii barchart of posting counts per interval.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP The activity command displays an ascii histogram showing transaction counts by day, week, month or other reporting interval (by day is the@@ -10329,6 +10870,38 @@ 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.+.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+  \-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\[aq]s description+     \-\-close\-acct=ACCT      set closing transaction\[aq]s destination account+     \-\-open\-desc=DESC       set opening transaction\[aq]s description+     \-\-open\-acct=ACCT       set opening transaction\[aq]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)+.EE .PP \f[CR]close\f[R] currently has six modes, selected by a single mode flag:@@ -10543,6 +11116,18 @@ Print all transactions, rewriting the postings of matched transactions. For now the only rewrite available is adding new postings, like print \-\-auto.+.IP+.EX+Flags:+     \-\-add\-posting=\[aq]ACCT  AMTEXPR\[aq]  add a posting to ACCT, which may be+                                    parenthesised. AMTEXPR is either a literal+                                    amount, or *N which means the transaction\[aq]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+.EE .PP This is a start at a generic rewriter of transaction entries. It reads the default journal and prints the transactions, like print,@@ -10688,6 +11273,11 @@ .SH Maintenance commands .SS check Check for various kinds of errors in your data.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP hledger provides a number of built\-in correctness checks to help validate your data and prevent errors.@@ -10799,18 +11389,25 @@ Compares a particular account\[aq]s transactions in two input files. It shows any transactions to this account which are in one file but not in the other.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP-More precisely, for each posting affecting this account in either file,-it looks for a corresponding posting in the other file which posts the-same amount to the same account (ignoring date, description, etc.)-Since postings not transactions are compared, this also works when+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).+.PP+Since it compares postings, not transactions, this also works when multiple bank transactions have been combined into a single journal entry. .PP-This is useful eg if you have downloaded an account\[aq]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.+This command is useful eg if you have downloaded an account\[aq]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. .PP Examples: .IP@@ -10827,6 +11424,11 @@ .EE .SS test Run built\-in unit tests.+.IP+.EX+Flags:+no command\-specific flags+.EE .PP This command runs the unit tests built in to hledger and hledger\-lib, printing the results on stdout.

@@ -26,11815 +26,12366 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). -   This manual is for hledger's command line interface, version 1.34.-It also describes the common options, file formats and concepts used by-all hledger programs.  It might accidentally teach you some-bookkeeping/accounting as well!  You don't need to know everything in-here to use hledger productively, but when you have a question about-functionality, this doc should answer it.  It is detailed, so do skip-ahead or skim when needed.  You can read it on hledger.org, or as an-info manual or man page on your system.  You can also get it from-hledger itself with-'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'.--   The main function of the hledger CLI is to read plain text files-describing financial transactions, crunch the numbers, and print a-useful report on the terminal (or save it as HTML, CSV, JSON or SQL).-Many reports are available, as subcommands.  hledger will also detect-other 'hledger-*' executables as extra subcommands.--   hledger usually reads from (and appends to) a journal file specified-by the 'LEDGER_FILE' environment variable (defaulting to-'$HOME/.hledger.journal'); or you can specify files with '-f' options.-It can also read timeclock files, timedot files, or any CSV/SSV/TSV file-with a date field.--   Here is a small journal file describing one transaction:--2015-10-16 bought food-  expenses:food          $10-  assets:cash--   Transactions are dated movements of money (etc.)  between two or more-_accounts_: bank accounts, your wallet, revenue/expense categories,-people, etc.  You can choose any account names you wish, using ':' to-indicate subaccounts.  There must be at least two spaces between account-name and amount.  Positive amounts are inflow to that account (_debit_),-negatives are outflow from it (_credit_).  (Some reports show revenue,-liability and equity account balances as negative numbers as a result;-this is normal.)--   hledger's add command can help you add transactions, or you can-install other data entry UIs like hledger-web or hledger-iadd.  For more-extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM-+ vim-ledger, or VS Code + hledger-vscode are some good choices (see-https://hledger.org/editors.html).--   To get started, run 'hledger add' and follow the prompts, or save-some entries like the above in '$HOME/.hledger.journal', then try-commands like:--$ hledger print -x-$ hledger aregister assets-$ hledger balance-$ hledger balancesheet-$ hledger incomestatement--   Run 'hledger' to list the commands.  See also the "Starting a journal-file" and "Setting opening balances" sections in PART 5: COMMON TASKS.--* Menu:--* PART 1 USER INTERFACE::-* Input::-* Commands::-* Options::-* 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 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 the commands list, run 'hledger' with no arguments.  The-commands are described in detail in PART 4: COMMANDS, below.--   To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]',--   * CMD is the full command name, or its standard abbreviation shown in-     the commands list, or any unambiguous prefix of the name.--   * CMDOPTS are command-specific options, if any.  Command-specific-     options must be written after the command name.  Eg: 'hledger print-     -x'.--   * CMDARGS are additional arguments to the command, if any.  Most-     hledger commands accept arguments representing a query, to limit-     the data in some way.  Eg: 'hledger reg assets:checking'.--   To list a command's options, arguments, and documentation in the-terminal, run 'hledger CMD -h'.  Eg: 'hledger bal -h'.--* Menu:--* Add-on commands::---File: hledger.info,  Node: Add-on commands,  Up: Commands--3.1 Add-on commands-===================--In addition to the built-in commands, you can install _add-on commands_:-programs or scripts named "hledger-SOMETHING", which will also appear in-hledger's commands list.  If you used the hledger-install script, you-will have several add-ons installed already.  Some more can be found in-hledger's bin/ directory, documented at-https://hledger.org/scripts.html.--   More precisely, add-on commands are programs or scripts in your-shell's PATH, whose name starts with "hledger-" and ends with no-extension or a recognised extension (".bat", ".com", ".exe", ".hs",-".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),-and (on unix and mac) which has executable permission for the current-user.--   You can run add-on commands using hledger, much like built-in-commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'.  But note-the double hyphen argument, required before add-on-specific options.-Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'.  If this causes-difficulty, you can always run the add-on directly, without using-'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.---File: hledger.info,  Node: Options,  Next: Output,  Prev: Commands,  Up: Top--4 Options-*********--Run 'hledger -h' to see general command line help.  The following-general options are common to most hledger commands.  General options-can be written either before or after the command name.--General input/data transformation flags:-  -f --file=FILE            Read data from FILE, or from stdin if -. Can be-                            specified more than once. If not specified, reads-                            from $LEDGER_FILE or $HOME/.hledger.journal.-     --rules-file=RULEFILE  Use conversion rules from this file for-                            converting subsequent CSV/SSV/TSV files. If not-                            specified, uses FILE.rules for each such FILE.-     --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-     --depth=NUM            or -NUM: show only top NUM levels of accounts-  -E --empty                Show zero items, which are normally hidden.-                            In hledger-ui & hledger-web, do the opposite.-  -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'-     --color=YN --colour    Use ANSI color codes in text output? Can be-                            'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.-     --pretty[=YN]          Use box-drawing characters in text output? Can be-                            'y'/'yes' or 'n'/'no'.-                            If YN is specified, the equals is required.-     --debug=[1-9]          show this level of debug output (default: 1)--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--   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::---File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Up: Options--4.1 Special characters-======================--* Menu:--* Single escaping shell metacharacters::-* Double escaping regular expression metacharacters::-* Triple escaping for add-on commands::-* Less escaping::---File: hledger.info,  Node: Single escaping shell metacharacters,  Next: Double escaping regular expression metacharacters,  Up: Special characters--4.1.1 Single escaping (shell metacharacters)-----------------------------------------------In shell command lines, characters significant to your shell - such as-spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped"-if you want hledger to see them.  This is done by enclosing them in-single or double quotes, or by writing a backslash before them.  Eg to-match an account name containing a space:--$ hledger register 'credit card'--   or:--$ hledger register credit\ card--   Windows users should keep in mind that 'cmd' treats single quote as a-regular character, so you should be using double quotes exclusively.-PowerShell treats both single and double quotes as quotes.---File: hledger.info,  Node: Double escaping regular expression metacharacters,  Next: Triple escaping for add-on commands,  Prev: Single escaping shell metacharacters,  Up: Special characters--4.1.2 Double escaping (regular expression metacharacters)------------------------------------------------------------Characters significant in regular expressions (described below) - such-as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be-"regex-escaped" if you don't want them to be interpreted by hledger's-regular expression engine.  This is done by writing backslashes before-them, but since backslash is typically also a shell metacharacter, both-shell-escaping and regex-escaping will be needed.  Eg to match a literal-'$' sign while using the bash shell:--$ hledger balance cur:'\$'--   or:--$ hledger balance cur:\\$---File: hledger.info,  Node: Triple escaping for add-on commands,  Next: Less escaping,  Prev: Double escaping regular expression metacharacters,  Up: Special characters--4.1.3 Triple escaping (for add-on commands)----------------------------------------------When you use hledger to run an external add-on command (described-below), one level of shell-escaping is lost from any options or-arguments intended for by the add-on command, so those need an extra-level of shell-escaping.  Eg to match a literal '$' sign while using the-bash shell and running an add-on command ('ui'):--$ hledger ui cur:'\\$'--   or:--$ hledger ui cur:\\\\$--   If you wondered why _four_ backslashes, perhaps this helps:--unescaped:        '$'-escaped:          '\$'-double-escaped:   '\\$'-triple-escaped:   '\\\\$'--   Or, you can avoid the extra escaping by running the add-on executable-directly:--$ hledger-ui cur:\\$---File: hledger.info,  Node: Less escaping,  Prev: Triple escaping for add-on commands,  Up: Special characters--4.1.4 Less escaping----------------------Options and arguments are sometimes used in places other than the shell-command line, where shell-escaping is not needed, so there you should-use one less level of escaping.  Those places include:--   * an @argumentfile-   * hledger-ui's filter field-   * hledger-web's search form-   * GHCI's prompt (used by developers).---File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Options--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.--   Some things to note:--   * In the 'alias' directive and '--alias' option, regular expressions-     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in-     hledger, these are not required.--   * In queries, to match a regular expression metacharacter like '$' as-     a literal character, prepend a backslash.  Eg to search for amounts-     with the dollar sign in hledger-web, write 'cur:\$'.--   * On the command line, some metacharacters like '$' have a special-     meaning to the shell and so must be escaped at least once more.-     See Special characters.---File: hledger.info,  Node: Argument files,  Prev: Regular expressions,  Up: 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'.--   Inside the argument file, each line should contain just one option or-argument.  Don't use spaces except inside quotes (or you'll see a-confusing error); write '=' (or nothing) between a flag and its-argument.  For the special characters mentioned above, use one less-level of quoting than you would at the command prompt.---File: hledger.info,  Node: Output,  Next: Environment,  Prev: Options,  Up: Top--5 Output-********--* Menu:--* Output destination::-* Output format::-* Commodity styles::-* Colour::-* Box-drawing::-* Paging::-* Debug output::---File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output--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:---                 txt             csv/tsv         html              json  sql---------------------------------------------------------------------------------aregister         Y               Y               Y                 Y-balance           Y _1_           Y _1_           Y _1,2_           Y-balancesheet      Y _1_           Y _1_           Y _1_             Y-balancesheetequityY _1_           Y _1_           Y _1_             Y-cashflow          Y _1_           Y _1_           Y _1_             Y-incomestatement   Y _1_           Y _1_           Y _1_             Y-print             Y               Y                                 Y     Y-register          Y               Y                                 Y--   * _1 Also affected by the balance commands' '--layout' option._-   * _2 'balance' does not support html output without a report interval-     or with '--budget'._--   The output format is selected by the '-O/--output-format=FMT' option:--$ hledger print -O csv    # print CSV on stdout--   or by the filename extension of an output file specified with the-'-o/--output-file=FILE.FMT' option:--$ hledger balancesheet -o foo.csv    # write CSV to foo.csv--   The '-O' option can be combined with '-o' to override the file-extension, if needed:--$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt--   Some notes about the various output formats:--* Menu:--* CSV output::-* HTML output::-* JSON output::-* SQL output::---File: hledger.info,  Node: CSV output,  Next: HTML output,  Up: Output format--5.2.1 CSV output-------------------   * In CSV output, digit group marks (such as thousands separators) are-     disabled automatically.---File: hledger.info,  Node: HTML output,  Next: JSON output,  Prev: CSV output,  Up: Output format--5.2.2 HTML output--------------------   * HTML output can be styled by an optional 'hledger.css' file in the-     same directory.---File: hledger.info,  Node: JSON output,  Next: SQL output,  Prev: HTML output,  Up: Output format--5.2.3 JSON output--------------------   * This is not yet much used; real-world feedback is welcome.--   * Our JSON is rather large and verbose, since it is a faithful-     representation of hledger's internal data types.  To understand the-     JSON, read the Haskell type definitions, which are mostly in-     https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.-     hledger-web's OpenAPI specification may also be relevant.--   * hledger represents quantities as Decimal values storing up to 255-     significant digits, eg for repeating decimals.  Such numbers can-     arise in practice (from automatically-calculated transaction-     prices), and would break most JSON consumers.  So in JSON, we show-     quantities as simple Numbers with at most 10 decimal places.  We-     don't limit the number of integer digits, but that part is under-     your control.  We hope this approach will not cause problems in-     practice; if you find otherwise, please let us know.  (Cf #1195)---File: hledger.info,  Node: SQL output,  Prev: JSON output,  Up: Output format--5.2.4 SQL output-------------------   * This is not yet much used; real-world feedback is welcome.--   * SQL output is expected to work at least with SQLite, MySQL and-     Postgres.--   * For SQLite, it will be more useful if you modify the generated 'id'-     field to be a PRIMARY KEY. Eg:--     $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...--   * SQL output is structured with the expectations that statements will-     be executed in the empty database.  If you already have tables-     created via SQL output of hledger, you would probably want to-     either clear tables of existing data (via 'delete' or 'truncate'-     SQL statements) or drop tables completely as otherwise your-     postings will be duped.---File: hledger.info,  Node: Commodity styles,  Next: Colour,  Prev: Output format,  Up: Output--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: Colour,  Next: Box-drawing,  Prev: Commodity styles,  Up: Output--5.4 Colour-==========--In terminal output, some commands can produce colour when the terminal-supports it:--   * if the '--color/--colour' option is given a value of 'yes' or-     'always' (or 'no' or 'never'), colour will (or will not) be used;-   * otherwise, if the 'NO_COLOR' environment variable is set, colour-     will not be used;-   * otherwise, colour will be used if the output (terminal or file)-     supports it.---File: hledger.info,  Node: Box-drawing,  Next: Paging,  Prev: Colour,  Up: Output--5.5 Box-drawing-===============--In terminal output, you can enable unicode box-drawing characters to-render prettier tables:--   * if the '--pretty' option is given a value of 'yes' or 'always' (or-     'no' or 'never'), unicode characters will (or will not) be used;-   * otherwise, unicode characters will not be used.---File: hledger.info,  Node: Paging,  Next: Debug output,  Prev: Box-drawing,  Up: Output--5.6 Paging-==========--When showing long output in the terminal, hledger will try to use the-pager specified by the 'PAGER' environment variable, or 'less', or-'more'.  (A pager is a helper program that shows one page at a time-rather than scrolling everything off screen).  Currently it does this-only for help output, not for reports; specifically,--   * when listing commands, with 'hledger'-   * when showing help with 'hledger [CMD] --help',-   * when viewing manuals with 'hledger help' or 'hledger --man'.--   Note the pager is expected to handle ANSI codes, which hledger uses-eg for bold emphasis.  For the common pager 'less' (and its 'more'-compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment-variables to make this work.  If you use a different pager, you might-need to configure it similarly, to avoid seeing junk on screen (let us-know).  Otherwise, you can set the 'NO_COLOR' environment variable to 1-to disable all ANSI output (see Colour).---File: hledger.info,  Node: Debug output,  Prev: Paging,  Up: Output--5.7 Debug output-================--We intend hledger to be relatively easy to troubleshoot, introspect and-develop.  You can add '--debug[=N]' to any hledger command line to see-additional debug output.  N ranges from 1 (least output, the default) to-9 (maximum output).  Typically you would start with 1 and increase until-you are seeing enough.  Debug output goes to stderr, and is not affected-by '-o/--output-file' (unless you redirect stderr to stdout, eg:-'2>&1').  It will be interleaved with normal output, which can help-reveal when parts of the code are evaluated.  To capture debug output in-a log file instead, you can usually redirect stderr, eg:--hledger bal --debug=3 2>hledger.log---File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top--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.--   *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'/'--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 addons-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and-hledger-vscode for Visual Studio Code, make this easier, adding colour,-formatting, tab completion, and useful commands.  See Editor-configuration at hledger.org for the full list.--   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 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 virtual postings,  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 virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and subaccounts,  Up: Balance assertions--8.12.7 Assertions and virtual postings-----------------------------------------Balance assertions always consider both real and virtual postings; they-are not affected by the '--real/-R' flag or 'real:' query.---File: hledger.info,  Node: Assertions and auto postings,  Next: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions--8.12.8 Assertions and auto postings--------------------------------------Balance assertions _are_ affected by the '--auto' flag, which generates-auto postings, which can alter account balances.  Because auto postings-are optional in hledger, accounts affected by them effectively have two-balances.  But balance assertions can only test one or the other of-these.  So to avoid making fragile assertions, either:--   * assert the balance calculated with '--auto', and always use-     '--auto' with that file-   * or assert the balance calculated without '--auto', and never use-     '--auto' with that file-   * or avoid balance assertions on accounts affected by auto postings-     (or avoid auto postings entirely).---File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and auto postings,  Up: Balance assertions--8.12.9 Assertions and precision----------------------------------Balance assertions compare the exactly calculated amounts, which are not-always what is shown by reports.  Eg a commodity directive may limit the-display precision, but this will not affect balance assertions.  Balance-assertion failure messages show exact amounts.---File: hledger.info,  Node: Posting comments,  Next: 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, which you can then search or pivot on.--   A tag is a word, optionally hyphenated, immediately followed by a-full colon, in the comment of a transaction, a posting, or an account-directive.  Eg: '2024-01-01 a transaction ; foo:' Note this is an-exception to the usual rule that things in comments are ignored.--   You can write multiple tags on one line, separated by comma.  Or you-can write each tag on its own comment line (no comma needed in this-case).--   For example, here are five different tags: one on the-'assets:checking' account, two on the transaction, and two on the-'expenses:food' posting:--account assets:checking         ; accounttag:--2017/1/16 bought groceries      ; transactiontag-1:-    ; transactiontag-2:-    assets:checking        $-1-    expenses:food           $1  ; postingtag:, another-posting-tag:--   Postings also inherit tags from their transaction and their account.-And transactions also acquire tags from their postings (and postings'-accounts).  So in the example above, the expenses posting effectively-has all five tags (by inheriting from the account and transaction), and-the transaction also has all five tags (by acquiring from the expenses-posting).--* Menu:--* Tag names::-* Special tags::-* Tag values::---File: hledger.info,  Node: Tag names,  Next: Special tags,  Up: Tags--8.15.1 Tag names-------------------Most non-whitespace characters are allowed in tag names.  Eg '😀:' is a-valid tag.--   You can list the tag names used in your journal with the tags-command:-'hledger tags [NAMEREGEX]'--   In commands which use a query, you can match by tag name.  Eg:-'hledger print tag:NAMEREGEX'--   You can declare valid tag names with the tag directive and then check-them with the check command.---File: hledger.info,  Node: Special tags,  Next: Tag values,  Prev: Tag names,  Up: Tags--8.15.2 Special tags----------------------Some tag names have special significance to hledger.  There's not much-harm in using them yourself, but some could produce an error message,-particularly the 'date:' and 'type:' tags.  They are explained-elsewhere, but here is a quick list for reference:--   Tags you can set to influence hledger's behaviour:-- date                   -- overrides a posting's date- date2                  -- overrides a posting's secondary date- type                   -- declares an account's type--   Tags hledger adds to indicate generated data:-- t                      -- appears on postings generated by timedot letters- 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- generated-transaction  -- appears on generated periodic txns (with --verbose-tags)- generated-posting      -- appears on generated auto postings (with --verbose-tags)- modified               -- appears on txns which have had auto postings added (with --verbose-tags)-Not displayed, but queryable:- _generated-transaction -- exists on generated periodic txns (always)- _generated-posting     -- exists on generated auto postings (always)- _modified              -- exists on txns which have had auto postings added (always)--   Tags hledger uses internally:-- _conversion-matched    -- exists on postings which have been matched with a nearby @/@@ cost annotation---File: hledger.info,  Node: Tag values,  Prev: Special tags,  Up: Tags--8.15.3 Tag values--------------------Tags can have a value, which is any text after the colon up until a-comma or end of line, with surrounding whitespace removed.  Ending at-comma allows us to write multiple tags on one line, but also means that-tag values can not contain commas.--   Eg in the following posting, the three tags' values are "value 1",-"value 2", and "" (empty) respectively:--    expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz--   Multiple tags with the same name are additive rather than overriding:-when the same tag name is seen again with a new value, the new-name:value pair is added to the tags.  It is not possible to override a-previous tag's value or remove a tag.--   You can list all the values used for a particular tag in the journal-with-'hledger tags TAGNAME --values'--   You can match on tag values with a query like-'tag:NAMEREGEX=VALUEREGEX'---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, hledger will-report an error if any transaction uses an account name that has not-been declared by an account directive.  Some notes:--   * The declaration is case-sensitive; transactions must use the-     correct account name capitalisation.-   * The account directive's scope is "whole file and below" (see-     directives).  This means it affects all of the current file, and-     any files it includes, but not parent or sibling files.  The-     position of account directives within the file does not matter,-     though it's usual to put them at the top.-   * Accounts can only be declared in 'journal' files, but will affect-     included files of all types.-   * It's currently not possible to declare "all possible subaccounts"-     with a wildcard; every account posted to must be declared.---File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive--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::---File: hledger.info,  Node: Auto postings and multiple files,  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).--* Menu:--* Auto postings and dates::-* Auto postings and transaction balancing / inferred amounts / balance assertions::-* Auto posting tags::-* Auto postings on forecast transactions only::---File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings and multiple files--8.26.1.1 Auto postings and dates-................................--A posting date (or secondary date) in the matched posting, or (taking-precedence) a posting date in the auto posting rule itself, will also be-used in the generated posting.---File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings and multiple files--8.26.1.2 Auto postings and transaction balancing / inferred-...........................................................--amounts / balance assertions Currently, auto postings are added:--   * after missing amounts are inferred, and transactions are checked-     for balancedness,-   * but before balance assertions are checked.--   Note this means that journal entries must be balanced both before and-after auto postings are added.  This changed in hledger 1.12+; see #893-for background.--   This also means that you cannot have more than one auto-posting with-a missing amount applied to a given transaction, as it will be unable to-infer amounts.---File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings and multiple files--8.26.1.3 Auto posting tags-..........................--Automated postings will have some extra tags:--   * 'generated-posting:= QUERY' - shows this was generated by an auto-     posting rule, and the query-   * '_generated-posting:= QUERY' - a hidden tag, which does not appear-     in hledger's output.  This can be used to match postings generated-     "just now", rather than generated in the past and saved to the-     journal.--   Also, any transaction that has been changed by auto posting rules-will have these tags added:--   * 'modified:' - this transaction was modified-   * '_modified:' - a hidden tag not appearing in the comment; this-     transaction was modified "just now".---File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings and multiple files--8.26.1.4 Auto postings on forecast transactions only-....................................................--Tip: you can can make auto postings that will apply to forecast-transactions but not recorded transactions, by adding-'tag:_generated-transaction' to their QUERY. This can be useful when-generating new journal entries to be saved in the journal.---File: hledger.info,  Node: Other syntax,  Prev: Auto postings,  Up: Journal--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-file' 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.---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:--  1. A record matcher is a word or single-line text fragment or regular-     expression ('REGEX'), which hledger will try to match-     case-insensitively anywhere within the CSV record.-     Eg: 'whole foods'--  2. A field matcher is preceded with a percent sign and CSV field name-     ('%CSVFIELD REGEX').  hledger will try to match these just within-     the named CSV field.-     Eg: '%date 2023'--   The regular expression is (as usual in hledger) a POSIX extended-regular expression, that also supports GNU word boundaries ('\b', '\B',-'\<', '\>'), and nothing else.  If you have trouble, see "Regular-expressions" in the hledger manual-(https://hledger.org/hledger.html#regular-expressions).--* Menu:--* What matchers match::-* Combining matchers::-* Match groups::---File: hledger.info,  Node: What matchers match,  Next: Combining matchers,  Up: Matchers--9.14.1 What matchers match-----------------------------With record matchers, it's important to know that the record matched is-not the original CSV record, but a modified one: separators will be-converted to commas, and enclosing double quotes (but not enclosing-whitespace) are removed.  So for example, when reading an SSV file, if-the original record was:--2023-01-01; "Acme, Inc.";  1,000--   the regex would see, and try to match, this modified record text:--2023-01-01,Acme, Inc.,  1,000---File: hledger.info,  Node: Combining matchers,  Next: Match groups,  Prev: What matchers match,  Up: Matchers--9.14.2 Combining matchers----------------------------When an if block has multiple matchers, they are combined as follows:--   * By default they are OR'd (any of them can match)-   * When a matcher is preceded by ampersand ('&', at the start of the-     line) it will be AND'ed with the previous matcher (all in the-     AND'ed group must match)-   * _Added in 1.32_ When a matcher is preceded by an exclamation mark-     ('!'), it is negated (it must not match).--   Note currently there is a limitation: you can't use both '&' and '!'-on the same line (you can't AND a negated matcher).---File: hledger.info,  Node: Match groups,  Prev: Combining matchers,  Up: Matchers--9.14.3 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 use the '--rules-file' option, that rules file will be-used for all the CSV files.---File: hledger.info,  Node: Reading files specified by rule,  Next: Valid transactions,  Prev: Reading multiple CSV files,  Up: Working with CSV--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 emacs and the built-in timeclock.el, or the extended-     timeclock-x.el and perhaps the extras in ledgerutils.el--   * at the command line, use these bash aliases: 'cli alias ti="echo i-     `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date-     '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'--   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.-     These rely on a "timeclock" executable which I think is just the-     ledger 2 executable renamed.---File: hledger.info,  Node: Timedot,  Next: PART 3 REPORTING CONCEPTS,  Prev: Timeclock,  Up: Top--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.--* 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 adjustment::-* 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 adjustment,  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 adjustment,  Next: Period expressions,  Prev: Report intervals,  Up: Time periods--13.4 Date adjustment-====================--When there is a report interval (other than daily), report start/end-dates which have been inferred, eg from the journal, are automatically-adjusted to natural period boundaries.  This is convenient for producing-simple periodic reports.  More precisely:--   * an inferred start date will be adjusted earlier if needed to fall-     on a natural period boundary--   * an inferred end date will be adjusted later if needed to make the-     last period the same length as the others.--   By contrast, start/end dates which have been specified explicitly,-with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger-1.29).  This makes it possible to specify non-standard report periods,-but it also means that if you are specifying a start date, you should-pick one that's on a period boundary if you want to see simple report-period headings.---File: hledger.info,  Node: Period expressions,  Prev: Date adjustment,  Up: Time periods--13.5 Period expressions-=======================--The '-p/--period' option specifies a period expression, which is a-compact way of expressing a start date, end date, and/or report-interval.--   Here's a period expression with a start and end date (specifying the-first quarter of 2009):--'-p "from 2009/1/1 to 2009/4/1"'--   Several keywords like "from" and "to" are supported for readability;-these are optional.  "to" can also be written as ".."  or "-".  The-spaces are also optional, as long as you don't run two dates together.-So the following are equivalent to the above:--'-p "2009/1/1 2009/4/1"'-'-p2009/1/1to2009/4/1'-'-p2009/1/1..2009/4/1'--   Dates are smart dates, so if the current year is 2009, these are also-equivalent to the above:--'-p "1/1 4/1"'-'-p "jan-apr"'-'-p "this year to 4/1"'--   If you specify only one date, the missing start or end date will be-the earliest or latest transaction date in the journal:--'-p "from 2009/1/1"'   everything after january 1, 2009-'-p "since 2009/1"'    the same, since is a synonym-'-p "from 2009"'       the same-'-p "to 2009"'         everything before january 1, 2009--   You can also specify a period by writing a single partial or full-date:--'-p "2009"'     the year 2009; equivalent to “2009/1/1 to 2010/1/1”-'-p "2009/1"'   the month of january 2009; equivalent to “2009/1/1 to-                2009/2/1”-'-p             the first day of 2009; equivalent to “2009/1/1 to-"2009/1/1"'     2009/1/2”--   or by using the "Q" quarter-year syntax (case insensitive):--'-p "2009Q1"'    first quarter of 2009, equivalent to “2009/1/1 to-                 2009/4/1”-'-p "q4"'        fourth quarter of the current year--* Menu:--* Period expressions with a report interval::-* More complex report intervals::-* Multiple weekday intervals::---File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions--13.5.1 Period expressions with a report interval---------------------------------------------------A period expression can also begin with a report interval, separated-from the start/end dates (if any) by a space or the word 'in':--'-p "weekly from 2009/1/1 to 2009/4/1"'-'-p "monthly in 2008"'-'-p "quarterly"'---File: hledger.info,  Node: More complex report intervals,  Next: Multiple weekday intervals,  Prev: Period expressions with a report interval,  Up: Period expressions--13.5.2 More complex report intervals---------------------------------------Some more complex intervals can be specified within period expressions,-such as:--   * 'biweekly' (every two weeks)-   * 'fortnightly'-   * 'bimonthly' (every two months)-   * 'every day|week|month|quarter|year'-   * 'every N days|weeks|months|quarters|years'--   Weekly on a custom day:--   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted-     after the number)-   * 'every WEEKDAYNAME' (full or three-letter english weekday name,-     case insensitive)--   Monthly on a custom day:--   * 'every Nth day [of month]' ('31st day' will be adjusted to each-     month's last day)-   * 'every Nth WEEKDAYNAME [of month]'--   Yearly on a custom day:--   * 'every MM/DD [of year]' (month number and day of month number)-   * 'every MONTHNAME DDth [of year]' (full or three-letter english-     month name, case insensitive, and day of month number)-   * 'every DDth MONTHNAME [of year]' (equivalent to the above)--   Examples:--'-p "bimonthly from-2008"'-'-p "every 2 weeks"'-'-p "every 5 months from-2009/03"'-'-p "every 2nd day of       periods will go from Tue to Tue-week"'-'-p "every Tue"'            same-'-p "every 15th day"'       period boundaries will be on 15th of each-                            month-'-p "every 2nd Monday"'     period boundaries will be on second Monday-                            of each month-'-p "every 11/05"'          yearly periods with boundaries on 5th of-                            November-'-p "every 5th November"'   same-'-p "every Nov 5th"'        same--   Show historical balances at end of the 15th day of each month (N is-an end date, exclusive as always):--$ hledger balance -H -p "every 16th day"--   Group postings from the start of wednesday to end of the following-tuesday (N is both (inclusive) start date and (exclusive) end date):--$ hledger register checking -p "every 3rd day of week"---File: hledger.info,  Node: Multiple weekday intervals,  Prev: More complex report intervals,  Up: Period expressions--13.5.3 Multiple weekday intervals------------------------------------This special form is also supported:--   * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english-     weekday names, case insensitive)--   Also, 'weekday' and 'weekendday' are shorthand for-'mon,tue,wed,thu,fri' and 'sat,sun'.--   This is mainly intended for use with '--forecast', to generate-periodic transactions on arbitrary days of the week.  It may be less-useful with '-p', since it divides each week into subperiods of unequal-length, which is unusual.  (Related: #1632)--   Examples:--'-p "every         dates will be Mon, Wed, Fri; periods will be-mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun-'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will-weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun-'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri-weekendday"'---File: hledger.info,  Node: Depth,  Next: Queries,  Prev: Time periods,  Up: Top--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.---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.  Remember these can also be-prefixed with *'not:'* to convert them into a negative match.--   *'acct:REGEX'* or *'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.--   *'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.--   *'code:REGEX'*-Match by transaction code (eg check number).--   *'cur:REGEX'*-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX. (For a partial-match, use '.*REGEX.*').  Note, to match special characters which are-regex-significant, you need to escape them with '\'.  And for characters-which are significant to your shell you may need one more level of-escaping.  So eg to match the dollar sign:-'hledger print cur:\\$'.--   *'desc:REGEX'*-Match transaction descriptions.--   *'date:PERIODEXPR'*-Match dates (or with the '--date2' flag, secondary dates) within the-specified period.  PERIODEXPR is a period expression with no report-interval.  Examples:-'date:2016', 'date:thismonth', 'date:2/1-2/15',-'date:2021-07-27..nextquarter'.--   *'date2:PERIODEXPR'*-Match secondary dates within the specified period (independent of the-'--date2' flag).--   *'depth:N'*-Match (or display, depending on command) accounts at or above this-depth.--   *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg)-Match with a boolean combination of queries (which must be enclosed in-quotes).  See Combining query terms below.--   *'note:REGEX'*-Match transaction notes (the part of the description right of '|', or-the whole description if there's no '|').--   *'payee:REGEX'*-Match transaction payee/payer names (the part of the description left of-'|', or the whole description if there's no '|').--   *'real:, real:0'*-Match real or virtual postings respectively.--   *'status:, status:!, status:*'*-Match unmarked, pending, or cleared transactions respectively.--   *'type:TYPECODES'*-Match by account type (see Declaring accounts > Account types).-'TYPECODES' is one or more of the single-letter account type codes-'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match-their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain-kinds of account alias can disrupt account types, see Rewriting accounts-> Aliases and account types.--   *'tag:REGEX[=REGEX]'*-Match by tag name, and optionally also by tag value.  (To match only by-value, use 'tag:.=REGEX'.)--   When querying by tag, note that:--   * Accounts also inherit the tags of their parent accounts-   * Postings also inherit the tags of their account and their-     transaction-   * Transactions also acquire the tags of their postings.--   (*'inacct:ACCTNAME'*-A special query term used automatically in hledger-web only: tells-hledger-web to show the transaction register for an account.)---File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries--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 occurence after today's date.  (You-won't normally use '--today'; it's just to make these examples-reproducible.)---File: hledger.info,  Node: Forecast reports,  Next: Forecast tags,  Prev: Inspecting forecast transactions,  Up: Forecasting--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.---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.--   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.--   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.--   Many hledger users edit their journals directly with a text editor,-or generate them from CSV. For more interactive data entry, there is the-'add' command, which prompts interactively on the console for new-transactions, and appends them to the main journal file (which should be-in journal format).  Existing transactions are not changed.  This is one-of the few hledger commands that writes to the journal file (see also-'import').--   To use it, just run 'hledger add' and follow the prompts.  You can-add as many transactions as you like; when you are finished, enter '.'-or press control-d or control-c to exit.--   Features:--   * add tries to provide useful defaults, using the most similar (by-     description) recent transaction (filtered by the query, if any) as-     a template.-   * You can also set the initial defaults with command line arguments.-   * Readline-style edit keys can be used during data entry.-   * The tab key will auto-complete whenever possible - accounts,-     payees/descriptions, dates ('yesterday', 'today', 'tomorrow').  If-     the input area is empty, it will insert the default value.-   * If the journal defines a default commodity, it will be added to any-     bare numbers entered.-   * A parenthesised transaction code may be entered following a date.-   * Comments and tags may be entered following a description or amount.-   * If you make a mistake, enter '<' at any prompt to go one step-     backward.-   * Input prompts are displayed in a different colour when the terminal-     supports it.--   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.--   This command detects new transactions in each FILE argument since it-was last run, and appends them to the main journal.--   Or with '--dry-run', it just print the transactions that would be-added.--   Or with '--catchup', it just marks all of the FILEs' current-transactions as already imported.--   This is one of the few hledger commands that writes to the journal-file (see also 'add').  It only appends; existing data will not be-changed.--   The input files are specified as arguments, so to import one or more-CSV files to your main journal, you will run 'hledger import bank.csv'-or perhaps 'hledger import *.csv'.--   Note you can import from any file format, though CSV files are the-most common import source, and these docs focus on that case.  The-target file (main journal) should be in journal format.--* Menu:--* Date skipping::-* Import testing::-* Importing balance assignments::-* Import and commodity styles::---File: hledger.info,  Node: Date skipping,  Next: Import testing,  Up: import--26.2.1 Date skipping-----------------------'import' tries to import only the transactions which are new since the-last import, ignoring any that it has seen in previous runs.  So if your-bank's CSV includes the last three months of data, you can download and-'import' it every month (or week, or day) and only the new transactions-will be imported each time.--   It works as follows: for each imported 'FILE',--   * It tries to read the latest date previously seen, from-     '.latest.FILE' in the same directory-   * Then it processes 'FILE', ignoring transactions on or before that-     date--   And after a successful import, unless '--dry-run' was used, it-updates the '.latest.FILE'(s) for next time.  This is a simple system-that works for most real-world CSV files; it assumes the following are-true, or true enough:--  1. the name of the input file is stable across successive downloads-  2. new items always have the newest dates-  3. item dates are stable across downloads-  4. the order of same-date items is stable across downloads.--   Tips:--   * To help ensure a stable file name, remember you can use a CSV rules-     file as an input file.--   * If you have a bank whose CSV dates or ordering occasionally change,-     you can reduce the chance of this happening in new transactions by-     importing more often.  (If it happens in old transactions, that's-     harmless.)--   Note this is just one kind of "deduplication": not reprocessing the-same dates across successive runs.  'import' doesn't detect other kinds-of duplication, such as the same transaction appearing multiple times-within a single run, or a new transaction that looks identical to a-transaction already in the journal.  (Because these can happen-legitimately in real-world data.)--   Here's a situation where you need to run 'import' with care: say you-download but forget to import 'bank.1.csv', and a week later you-download 'bank.2.csv' with some overlapping data.  You should not-process both of these as a single import ('hledger import bank.1.csv-bank.2.csv'), because the overlapping transactions would not be-deduplicated.  Instead, import one file at a time, using the same-filename each time:--$ mv bank.1.csv bank.csv; hledger import bank.csv-$ mv bank.2.csv bank.csv; hledger import bank.csv--   Normally you don't need to think about '.latest.*' files, but you can-create or modify them to catch up to a certain date, or delete them to-mark all transactions as new.  Their format is a single ISO-format-'YYYY-MM-DD' date, optionally repeated on multiple lines, meaning "I-have seen the transactions before this date, and this many of them on-this date".--   'hledger print --new' also uses and updates these '.latest.*' files,-but it is less often used.--   Related: CSV > Working with CSV > Deduplicating, importing.---File: hledger.info,  Node: Import testing,  Next: Importing balance assignments,  Prev: Date skipping,  Up: import--26.2.2 Import testing------------------------With '--dry-run', the transactions that will be imported are printed to-the terminal, without updating your journal or state files.  The output-is valid journal format, like the print command, so you can re-parse it.-Eg, to see any importable transactions which CSV rules have not-categorised:--$ hledger import --dry bank.csv | hledger -f- -I print unknown--   or (live updating):--$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'--   Note: when importing from multiple files at once, it's currently-possible for some .latest files to be updated successfully, while the-actual import fails because of a problem in one of the files, leaving-them out of sync (and causing some transactions to be missed).  To-prevent this, do a -dry-run first and fix any problems before the real-import.---File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: Import testing,  Up: import--26.2.3 Importing balance assignments---------------------------------------Entries added by import will have their posting amounts made explicit-(like 'hledger print -x').  This means that any balance assignments in-imported files must be evaluated; but, imported files don't get to see-the main file's account balances.  As a result, importing entries with-balance assignments (eg from an institution that provides only balances-and not posting amounts) will probably generate incorrect posting-amounts.  To avoid this problem, use print instead of import:--$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE--   (If you think import should leave amounts implicit like print does,-please test it and send a pull request.)---File: hledger.info,  Node: Import and commodity styles,  Prev: Importing balance assignments,  Up: import--26.2.4 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: 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.--   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.--   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.---File: hledger.info,  Node: descriptions,  Next: files,  Prev: commodities,  Up: Basic report commands--27.4 descriptions-=================--List the unique descriptions that appear in transactions.--   This command lists the unique descriptions that appear in-transactions, in alphabetic order.  You can add a query to select a-subset of transactions.--   Example:--$ hledger descriptions-Store Name-Gas Station | Petrol-Person A---File: hledger.info,  Node: 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.---File: hledger.info,  Node: notes,  Next: payees,  Prev: files,  Up: Basic report commands--27.6 notes-==========--List the unique notes that appear in transactions.--   This command lists the unique notes that appear in transactions, in-alphabetic order.  You can add a query to select a subset of-transactions.  The note is the part of the transaction description after-a | character (or if there is no |, the whole description).--   Example:--$ hledger notes-Petrol-Snacks---File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: Basic report commands--27.7 payees-===========--List the unique payee/payer names that appear in transactions.--   This command lists unique payee/payer names which have been declared-with payee directives (-declared), used in transaction descriptions-(-used), or both (the default).--   The payee/payer is the part of the transaction description before a |-character (or if there is no |, the whole description).--   You can add query arguments to select a subset of transactions.  This-implies -used.--   Example:--$ hledger payees-Store Name-Gas Station-Person A---File: hledger.info,  Node: prices,  Next: 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.--   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.--   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.--   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.--   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.--   'aregister' shows the overall transactions affecting a particular-account (and any subaccounts).  Each report line represents one-transaction in this account.  Transactions before the report start date-are always included in the running balance ('--historical' mode is-always on).--   This is a more "real world", bank-like view than the 'register'-command (which shows individual postings, possibly from multiple-accounts, not necessarily in historical mode).  As a quick rule of-thumb: - use 'aregister' for reviewing and reconciling real-world-asset/liability accounts - use 'register' for reviewing detailed-revenues/expenses.--   'aregister' requires one argument: the account to report on.  You can-write either the full account name, or a case-insensitive regular-expression which will select the alphabetically first matched account.--   When there are multiple matches, the alphabetically-first choice can-be surprising; eg if you have 'assets:per:checking 1' and-'assets:biz:checking 2' accounts, 'hledger areg checking' would select-'assets:biz:checking 2'.  It's just a convenience to save typing, so if-in doubt, write the full account name, or a distinctive substring that-matches uniquely.--   Transactions involving subaccounts of this account will also be-shown.  'aregister' ignores depth limits, so its final total will always-match a balance report with similar arguments.--   Any additional arguments form a query which will filter the-transactions shown.  Note some queries will disturb the running balance,-causing it to be different from the account's real-world running-balance.--   An example: this shows the transactions and historical running-balance during july, in the first account whose name contains-"checking":--$ hledger areg checking date:jul--   Each 'aregister' line item shows:--   * the transaction's date (or the relevant posting's date if-     different, see below)-   * the names of all the other account(s) involved in this transaction-     (probably abbreviated)-   * the total change to this account's balance from this transaction-   * the account's historical running balance after this transaction.--   Transactions making a net change of zero are not shown by default;-add the '-E/--empty' flag to show them.--   For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted.  If you want to-ensure perfect alignment, at the cost of more time and memory, use the-'--align-all' flag.--   This command also supports the output destination and output format-options.  The output formats supported are 'txt', 'csv', 'tsv' (_Added-in 1.32_), 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.--   The register command displays matched postings, across all accounts,-in date order, with their running total or running historical balance.-(See also the 'aregister' command, which shows matched transactions in a-specific account.)--   register normally shows line per posting, but note that-multi-commodity amounts will occupy multiple lines (one line per-commodity).--   It is typically used with a query selecting a particular account, to-see that account's activity:--$ hledger register checking-2008/01/01 income               assets:bank:checking            $1           $1-2008/06/01 gift                 assets:bank:checking            $1           $2-2008/06/02 save                 assets:bank:checking           $-1           $1-2008/12/31 pay off              assets:bank:checking           $-1            0--   With '--date2', it shows and sorts by secondary date instead.--   For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted.  If you want to-ensure perfect alignment, at the cost of more time and memory, use the-'--align-all' flag.--   The '--historical'/'-H' flag adds the balance from any undisplayed-prior postings to the running total.  This is useful when you want to-see only recent activity, with a historically accurate running balance:--$ hledger register checking -b 2008/6 --historical-2008/06/01 gift                 assets:bank:checking            $1           $2-2008/06/02 save                 assets:bank:checking           $-1           $1-2008/12/31 pay off              assets:bank:checking           $-1            0--   The '--depth' option limits the amount of sub-account detail-displayed.--   The '--average'/'-A' flag shows the running average posting amount-instead of the running total (so, the final number displayed is the-average for the whole report period).  This flag implies '--empty' (see-below).  It is affected by '--historical'.  It works best when showing-just one account and one commodity.--   The '--related'/'-r' flag shows the _other_ postings in the-transactions of the postings which would normally be shown.--   The '--invert' flag negates all amounts.  For example, it can be used-on an income account where amounts are normally displayed as negative-numbers.  It's also useful to show postings on the checking account-together with the related account:--$ hledger register --related --invert assets:checking--   With a reporting interval, register shows summary postings, one per-interval, aggregating the postings to each account:--$ hledger register --monthly income-2008/01                 income:salary                          $-1          $-1-2008/06                 income:gifts                           $-1          $-2--   Periods with no activity, and summary postings with a zero amount,-are not shown by default; use the '--empty'/'-E' flag to see them:--$ hledger register --monthly income -E-2008/01                 income:salary                          $-1          $-1-2008/02                                                          0          $-1-2008/03                                                          0          $-1-2008/04                                                          0          $-1-2008/05                                                          0          $-1-2008/06                 income:gifts                           $-1          $-2-2008/07                                                          0          $-2-2008/08                                                          0          $-2-2008/09                                                          0          $-2-2008/10                                                          0          $-2-2008/11                                                          0          $-2-2008/12                                                          0          $-2--   Often, you'll want to see just one line per interval.  The '--depth'-option helps with this, causing subaccounts to be aggregated:--$ hledger register --monthly assets --depth 1h-2008/01                 assets                                  $1           $1-2008/06                 assets                                 $-1            0-2008/12                 assets                                 $-1          $-1--   Note when using report intervals, if you specify start/end dates-these will be adjusted outward if necessary to contain a whole number of-intervals.  This ensures that the first and last intervals are full-length and comparable to the others in the report.--   With '-m DESC'/'--match=DESC', register does a fuzzy search for one-recent posting whose description is most similar to DESC. DESC should-contain at least two characters.  If there is no similar-enough match,-no posting will be shown and the program exit code will be non-zero.--* Menu:--* Custom register output::---File: hledger.info,  Node: Custom register output,  Up: register--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.--   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.--   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.--   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.--   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.--   '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::-* 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'.  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: Some useful balance reports,  Prev: Budget report,  Up: balance--29.1.15 Balance report layout--------------------------------The '--layout' option affects how balance reports show multi-commodity-amounts and commodity symbols, which can improve readability.  It can-also normalise the data for easy consumption by other programs.  It has-four possible values:--   * '--layout=wide[,WIDTH]': commodities are shown on a single line,-     optionally elided to WIDTH-   * '--layout=tall': each commodity is shown on a separate line-   * '--layout=bare': commodity symbols are in their own column, amounts-     are bare numbers-   * '--layout=tidy': data is normalised to easily-consumed "tidy" form,-     with one row per data value--   Here are the '--layout' modes supported by each output format 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: Some useful balance reports,  Prev: Balance report layout,  Up: balance--29.1.16 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.--   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.--   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.--   '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.--   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.--   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.--   More precisely, for each posting affecting this account in either-file, it looks for a corresponding posting in the other file which posts-the same amount to the same account (ignoring date, description, etc.)-Since postings not transactions are compared, this also works when-multiple bank transactions have been combined into a single journal-entry.--   This is useful eg if you have downloaded an account's transactions-from your bank (eg as CSV data).  When hledger and your bank disagree-about the account balance, you can compare the bank data with your-journal to find out the cause.--   Examples:--$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only:--2014/01/01 Opening Balances-    assets:bank:giro              EUR ...-    ...-    equity:opening balances       EUR -...--These transactions are in the second file only:---File: hledger.info,  Node: test,  Prev: diff,  Up: Maintenance commands--32.3 test-=========--Run built-in unit tests.--   This command runs the unit tests built in to hledger and hledger-lib,-printing the results on stdout.  If any test fails, the exit code will-be non-zero.--   This is mainly used by hledger developers, but you can also use it to-sanity-check the installed hledger executable on your platform.  All-tests are expected to pass - if you ever see a failure, please report as-a bug!--   This command also accepts tasty test runner options, written after a-- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,-with ANSI colour codes disabled:--$ hledger test -- -pData.Amount --color=never--   For help on these, see https://github.com/feuerbach/tasty#options-('-- --help' currently doesn't show them).---File: hledger.info,  Node: PART 5 COMMON TASKS,  Next: 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"---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:-http://bugs.hledger.org), or on the #hledger chat or hledger mail list-(https://hledger.org/support).--   Some known issues and limitations:--   The need to precede add-on command options with '--' when invoked-from hledger is awkward.  (See Command options, Constructing command-lines.)--   A UTF-8-aware system locale must be configured to work with non-ascii-data.  (See Unicode characters, Troubleshooting.)--   On Microsoft Windows, depending whether you are running in a CMD-window or a Cygwin/MSYS/Mintty window and how you installed hledger,-non-ascii characters and colours may not be supported, and the tab key-may not be supported by 'hledger add'.  (Running in a WSL window should-resolve these.)--   When processing large data files, hledger uses more memory than-Ledger.--* Menu:--* Troubleshooting::---File: hledger.info,  Node: Troubleshooting,  Up: BUGS--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).-   * 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 INTERFACE4267-Ref: #part-1-user-interface4406-Node: Input4406-Ref: #input4516-Node: Text encoding5483-Ref: #text-encoding5597-Node: Data formats6163-Ref: #data-formats6298-Node: Standard input7887-Ref: #standard-input8027-Node: Multiple files8276-Ref: #multiple-files8415-Node: Strict mode9013-Ref: #strict-mode9123-Node: Commands9847-Ref: #commands9949-Node: Add-on commands11016-Ref: #add-on-commands11118-Node: Options12234-Ref: #options12335-Node: Special characters18185-Ref: #special-characters18322-Node: Single escaping shell metacharacters18485-Ref: #single-escaping-shell-metacharacters18726-Node: Double escaping regular expression metacharacters19329-Ref: #double-escaping-regular-expression-metacharacters19640-Node: Triple escaping for add-on commands20166-Ref: #triple-escaping-for-add-on-commands20426-Node: Less escaping21070-Ref: #less-escaping21224-Node: Unicode characters21548-Ref: #unicode-characters21713-Node: Regular expressions23212-Ref: #regular-expressions23375-Node: hledger's regular expressions26471-Ref: #hledgers-regular-expressions26630-Node: Argument files28016-Ref: #argument-files28142-Node: Output28639-Ref: #output28741-Node: Output destination28868-Ref: #output-destination28999-Node: Output format29424-Ref: #output-format29570-Node: CSV output31167-Ref: #csv-output31283-Node: HTML output31386-Ref: #html-output31524-Node: JSON output31618-Ref: #json-output31756-Node: SQL output32741-Ref: #sql-output32857-Node: Commodity styles33592-Ref: #commodity-styles33732-Node: Colour34470-Ref: #colour34588-Node: Box-drawing34992-Ref: #box-drawing35110-Node: Paging35400-Ref: #paging35514-Node: Debug output36467-Ref: #debug-output36573-Node: Environment37236-Ref: #environment37360-Node: PART 2 DATA FORMATS37927-Ref: #part-2-data-formats38070-Node: Journal38070-Ref: #journal38179-Node: Journal cheatsheet40547-Ref: #journal-cheatsheet40674-Node: Comments46761-Ref: #comments46889-Node: Transactions47705-Ref: #transactions47828-Node: Dates48842-Ref: #dates48949-Node: Simple dates48994-Ref: #simple-dates49110-Node: Posting dates49610-Ref: #posting-dates49728-Node: Status50697-Ref: #status50798-Node: Code52463-Ref: #code52566-Node: Description52798-Ref: #description52929-Node: Payee and note53485-Ref: #payee-and-note53591-Node: Transaction comments54576-Ref: #transaction-comments54729-Node: Postings55092-Ref: #postings55223-Node: Debits and credits56255-Ref: #debits-and-credits56402-Node: The two space delimiter56865-Ref: #the-two-space-delimiter57022-Node: Account names57430-Ref: #account-names57560-Node: Amounts59234-Ref: #amounts59362-Node: Decimal marks60263-Ref: #decimal-marks60390-Node: Digit group marks61367-Ref: #digit-group-marks61520-Node: Commodity62002-Ref: #commodity62131-Node: Costs63119-Ref: #costs63214-Node: Balance assertions65371-Ref: #balance-assertions65524-Node: Assertions and ordering66608-Ref: #assertions-and-ordering66797-Node: Assertions and multiple included files67336-Ref: #assertions-and-multiple-included-files67596-Node: Assertions and multiple -f files68096-Ref: #assertions-and-multiple--f-files68341-Node: Assertions and costs68738-Ref: #assertions-and-costs68947-Node: Assertions and commodities69388-Ref: #assertions-and-commodities69603-Node: Assertions and subaccounts71047-Ref: #assertions-and-subaccounts71273-Node: Assertions and virtual postings71717-Ref: #assertions-and-virtual-postings71955-Node: Assertions and auto postings72087-Ref: #assertions-and-auto-postings72317-Node: Assertions and precision72962-Ref: #assertions-and-precision73144-Node: Posting comments73411-Ref: #posting-comments73574-Node: Transaction balancing73951-Ref: #transaction-balancing74110-Node: Tags75953-Ref: #tags76072-Node: Tag names77415-Ref: #tag-names77522-Node: Special tags77910-Ref: #special-tags78042-Node: Tag values79555-Ref: #tag-values79665-Node: Directives80537-Ref: #directives80664-Node: Directives and multiple files81994-Ref: #directives-and-multiple-files82172-Node: Directive effects82939-Ref: #directive-effects83093-Node: account directive86095-Ref: #account-directive86251-Node: Account comments87545-Ref: #account-comments87696-Node: Account error checking88204-Ref: #account-error-checking88397-Node: Account display order89586-Ref: #account-display-order89774-Node: Account types90784-Ref: #account-types90925-Node: alias directive94558-Ref: #alias-directive94719-Node: Basic aliases95769-Ref: #basic-aliases95900-Node: Regex aliases96644-Ref: #regex-aliases96801-Node: Combining aliases97691-Ref: #combining-aliases97869-Node: Aliases and multiple files99145-Ref: #aliases-and-multiple-files99349-Node: end aliases directive99928-Ref: #end-aliases-directive100147-Node: Aliases can generate bad account names100296-Ref: #aliases-can-generate-bad-account-names100544-Node: Aliases and account types101129-Ref: #aliases-and-account-types101321-Node: commodity directive102017-Ref: #commodity-directive102191-Node: Commodity directive syntax103604-Ref: #commodity-directive-syntax103789-Node: Commodity error checking105240-Ref: #commodity-error-checking105421-Node: decimal-mark directive105715-Ref: #decimal-mark-directive105897-Node: include directive106294-Ref: #include-directive106458-Node: P directive107370-Ref: #p-directive107515-Node: payee directive108404-Ref: #payee-directive108553-Node: tag directive109026-Ref: #tag-directive109181-Node: Periodic transactions109638-Ref: #periodic-transactions109803-Node: Periodic rule syntax111792-Ref: #periodic-rule-syntax111970-Node: Periodic rules and relative dates112615-Ref: #periodic-rules-and-relative-dates112881-Node: Two spaces between period expression and description!113392-Ref: #two-spaces-between-period-expression-and-description113669-Node: Auto postings114353-Ref: #auto-postings114501-Node: Auto postings and multiple files117331-Ref: #auto-postings-and-multiple-files117495-Node: Auto postings and dates117896-Ref: #auto-postings-and-dates118144-Node: Auto postings and transaction balancing / inferred amounts / balance assertions118319-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions118675-Node: Auto posting tags119178-Ref: #auto-posting-tags119460-Node: Auto postings on forecast transactions only120096-Ref: #auto-postings-on-forecast-transactions-only120342-Node: Other syntax120589-Ref: #other-syntax120705-Node: Balance assignments121361-Ref: #balance-assignments121517-Node: Balance assignments and costs122889-Ref: #balance-assignments-and-costs123101-Node: Balance assignments and multiple files123311-Ref: #balance-assignments-and-multiple-files123541-Node: Bracketed posting dates123734-Ref: #bracketed-posting-dates123918-Node: D directive124432-Ref: #d-directive124600-Node: apply account directive126205-Ref: #apply-account-directive126385-Node: Y directive127072-Ref: #y-directive127232-Node: Secondary dates128060-Ref: #secondary-dates128214-Node: Star comments129545-Ref: #star-comments129705-Node: Valuation expressions130237-Ref: #valuation-expressions130414-Node: Virtual postings130536-Ref: #virtual-postings130713-Node: Other Ledger directives132160-Ref: #other-ledger-directives132356-Node: Other cost/lot notations132922-Ref: #other-costlot-notations133095-Node: CSV135684-Ref: #csv135775-Node: CSV rules cheatsheet137772-Ref: #csv-rules-cheatsheet137899-Node: source139697-Ref: #source139818-Node: separator140698-Ref: #separator140809-Node: skip141349-Ref: #skip141455-Node: date-format141999-Ref: #date-format142118-Node: timezone142842-Ref: #timezone142963-Node: newest-first143968-Ref: #newest-first144104-Node: intra-day-reversed144681-Ref: #intra-day-reversed144833-Node: decimal-mark145281-Ref: #decimal-mark145420-Node: fields list145759-Ref: #fields-list145896-Node: Field assignment147567-Ref: #field-assignment147709-Node: Field names148786-Ref: #field-names148915-Node: date field150118-Ref: #date-field150234-Node: date2 field150282-Ref: #date2-field150421-Node: status field150477-Ref: #status-field150618-Node: code field150667-Ref: #code-field150810-Node: description field150855-Ref: #description-field151013-Node: comment field151072-Ref: #comment-field151225-Node: account field151518-Ref: #account-field151666-Node: amount field152236-Ref: #amount-field152383-Node: currency field155075-Ref: #currency-field155226-Node: balance field155483-Ref: #balance-field155613-Node: if block156006-Ref: #if-block156125-Node: Matchers157533-Ref: #matchers157645-Node: What matchers match158442-Ref: #what-matchers-match158589-Node: Combining matchers159029-Ref: #combining-matchers159195-Node: Match groups159732-Ref: #match-groups159858-Node: if table160626-Ref: #if-table160746-Node: balance-type162627-Ref: #balance-type162754-Node: include163454-Ref: #include163579-Node: Working with CSV164023-Ref: #working-with-csv164168-Node: Rapid feedback164575-Ref: #rapid-feedback164706-Node: Valid CSV165158-Ref: #valid-csv165302-Node: File Extension166034-Ref: #file-extension166205-Node: Reading CSV from standard input166769-Ref: #reading-csv-from-standard-input166991-Node: Reading multiple CSV files167155-Ref: #reading-multiple-csv-files167384-Node: Reading files specified by rule167625-Ref: #reading-files-specified-by-rule167851-Node: Valid transactions169022-Ref: #valid-transactions169219-Node: Deduplicating importing169847-Ref: #deduplicating-importing170040-Node: Setting amounts171076-Ref: #setting-amounts171245-Node: Amount signs173603-Ref: #amount-signs173771-Node: Setting currency/commodity174668-Ref: #setting-currencycommodity174870-Node: Amount decimal places176044-Ref: #amount-decimal-places176248-Node: Referencing other fields177301-Ref: #referencing-other-fields177512-Node: How CSV rules are evaluated178409-Ref: #how-csv-rules-are-evaluated178624-Node: Well factored rules180077-Ref: #well-factored-rules180243-Node: CSV rules examples180567-Ref: #csv-rules-examples180700-Node: Bank of Ireland180765-Ref: #bank-of-ireland180900-Node: Coinbase182362-Ref: #coinbase182498-Node: Amazon183545-Ref: #amazon183668-Node: Paypal185387-Ref: #paypal185493-Node: Timeclock193137-Ref: #timeclock193242-Node: Timedot195418-Ref: #timedot195541-Node: Timedot examples198662-Ref: #timedot-examples198768-Node: PART 3 REPORTING CONCEPTS200939-Ref: #part-3-reporting-concepts201103-Node: Time periods201103-Ref: #time-periods201237-Node: Report start & end date201355-Ref: #report-start-end-date201507-Node: Smart dates202831-Ref: #smart-dates202984-Node: Report intervals204774-Ref: #report-intervals204929-Node: Date adjustment205347-Ref: #date-adjustment205507-Node: Period expressions206358-Ref: #period-expressions206499-Node: Period expressions with a report interval208263-Ref: #period-expressions-with-a-report-interval208497-Node: More complex report intervals208711-Ref: #more-complex-report-intervals208956-Node: Multiple weekday intervals210817-Ref: #multiple-weekday-intervals211006-Node: Depth211828-Ref: #depth211930-Node: Queries212226-Ref: #queries212328-Node: Query types213924-Ref: #query-types214045-Node: Combining query terms217279-Ref: #combining-query-terms217456-Node: Queries and command options219019-Ref: #queries-and-command-options219224-Node: Queries and account aliases219473-Ref: #queries-and-account-aliases219678-Node: Queries and valuation219798-Ref: #queries-and-valuation219955-Node: Pivoting220160-Ref: #pivoting220274-Node: Generating data222051-Ref: #generating-data222183-Node: Forecasting223851-Ref: #forecasting223976-Node: --forecast224507-Ref: #forecast224638-Node: Inspecting forecast transactions225608-Ref: #inspecting-forecast-transactions225810-Node: Forecast reports226940-Ref: #forecast-reports227113-Node: Forecast tags228049-Ref: #forecast-tags228209-Node: Forecast period in detail228669-Ref: #forecast-period-in-detail228863-Node: Forecast troubleshooting229757-Ref: #forecast-troubleshooting229925-Node: Budgeting230828-Ref: #budgeting230951-Node: Amount formatting231388-Ref: #amount-formatting231530-Node: Commodity display style231632-Ref: #commodity-display-style231786-Node: Rounding233473-Ref: #rounding233628-Node: Trailing decimal marks234078-Ref: #trailing-decimal-marks234257-Node: Amount parseability235011-Ref: #amount-parseability235167-Node: Cost reporting236592-Ref: #cost-reporting236734-Node: Recording costs237395-Ref: #recording-costs237531-Node: Reporting at cost239122-Ref: #reporting-at-cost239297-Node: Equity conversion postings239887-Ref: #equity-conversion-postings240101-Node: Inferring equity conversion postings242532-Ref: #inferring-equity-conversion-postings242795-Node: Combining costs and equity conversion postings243547-Ref: #combining-costs-and-equity-conversion-postings243857-Node: Requirements for detecting equity conversion postings244772-Ref: #requirements-for-detecting-equity-conversion-postings245094-Node: Infer cost and equity by default ?246294-Ref: #infer-cost-and-equity-by-default246523-Node: Value reporting246731-Ref: #value-reporting246873-Node: -V Value247612-Ref: #v-value247744-Node: -X Value in specified commodity247939-Ref: #x-value-in-specified-commodity248140-Node: Valuation date248289-Ref: #valuation-date248466-Node: Finding market price249249-Ref: #finding-market-price249460-Node: --infer-market-prices market prices from transactions250629-Ref: #infer-market-prices-market-prices-from-transactions250911-Node: Valuation commodity253673-Ref: #valuation-commodity253893-Node: --value Flexible valuation255106-Ref: #value-flexible-valuation255305-Node: Valuation examples256949-Ref: #valuation-examples257149-Node: Interaction of valuation and queries259081-Ref: #interaction-of-valuation-and-queries259321-Node: Effect of valuation on reports259798-Ref: #effect-of-valuation-on-reports260001-Node: PART 4 COMMANDS267696-Ref: #part-4-commands267839-Node: Help commands269912-Ref: #help-commands270057-Node: help270085-Ref: #help270174-Node: demo271543-Ref: #demo271632-Node: User interface commands272548-Ref: #user-interface-commands272717-Node: ui272742-Ref: #ui272834-Node: web272867-Ref: #web272961-Node: Data entry commands272995-Ref: #data-entry-commands273164-Node: add273193-Ref: #add273287-Node: import275678-Ref: #import275778-Node: Date skipping276786-Ref: #date-skipping276909-Node: Import testing279687-Ref: #import-testing279850-Node: Importing balance assignments280693-Ref: #importing-balance-assignments280900-Node: Import and commodity styles281549-Ref: #import-and-commodity-styles281729-Node: Basic report commands281958-Ref: #basic-report-commands282132-Node: accounts282259-Ref: #accounts282369-Node: codes284256-Ref: #codes284380-Node: commodities285244-Ref: #commodities285384-Node: descriptions285454-Ref: #descriptions285596-Node: files285887-Ref: #files286009-Node: notes286150-Ref: #notes286266-Node: payees286628-Ref: #payees286747-Node: prices287266-Ref: #prices287385-Node: stats288038-Ref: #stats288153-Node: tags289667-Ref: #tags-1289767-Node: Standard report commands290776-Ref: #standard-report-commands290961-Node: print291081-Ref: #print291189-Node: print explicitness292169-Ref: #print-explicitness292310-Node: print amount style293089-Ref: #print-amount-style293257-Node: print parseability294327-Ref: #print-parseability294497-Node: print other features295246-Ref: #print-other-features295423-Node: print output format295944-Ref: #print-output-format296090-Node: aregister299229-Ref: #aregister299362-Node: aregister and posting dates302243-Ref: #aregister-and-posting-dates302388-Node: register303144-Ref: #register303282-Node: Custom register output308313-Ref: #custom-register-output308442-Node: balancesheet309789-Ref: #balancesheet309944-Node: balancesheetequity311606-Ref: #balancesheetequity311773-Node: cashflow313793-Ref: #cashflow313943-Node: incomestatement315430-Ref: #incomestatement315567-Node: Advanced report commands317103-Ref: #advanced-report-commands317281-Node: balance317311-Ref: #balance317419-Node: balance features318578-Ref: #balance-features318718-Node: Simple balance report320628-Ref: #simple-balance-report320813-Node: Balance report line format322438-Ref: #balance-report-line-format322640-Node: Filtered balance report324798-Ref: #filtered-balance-report324990-Node: List or tree mode325317-Ref: #list-or-tree-mode325485-Node: Depth limiting326830-Ref: #depth-limiting326996-Node: Dropping top-level accounts327597-Ref: #dropping-top-level-accounts327797-Node: Showing declared accounts328107-Ref: #showing-declared-accounts328306-Node: Sorting by amount328837-Ref: #sorting-by-amount329004-Node: Percentages329674-Ref: #percentages329833-Node: Multi-period balance report330381-Ref: #multi-period-balance-report330581-Node: Balance change end balance333133-Ref: #balance-change-end-balance333342-Node: Balance report types334770-Ref: #balance-report-types334951-Node: Calculation type335449-Ref: #calculation-type335604-Node: Accumulation type336153-Ref: #accumulation-type336333-Node: Valuation type337254-Ref: #valuation-type337442-Node: Combining balance report types338443-Ref: #combining-balance-report-types338637-Node: Budget report340475-Ref: #budget-report340637-Node: Using the budget report342780-Ref: #using-the-budget-report342953-Node: Budget date surprises345056-Ref: #budget-date-surprises345256-Node: Selecting budget goals346420-Ref: #selecting-budget-goals346623-Node: Budgeting vs forecasting347368-Ref: #budgeting-vs-forecasting347545-Node: Balance report layout349045-Ref: #balance-report-layout349230-Node: Wide layout350183-Ref: #wide-layout350318-Node: Tall layout352588-Ref: #tall-layout352743-Node: Bare layout353894-Ref: #bare-layout354049-Node: Tidy layout355953-Ref: #tidy-layout356088-Node: Some useful balance reports357497-Ref: #some-useful-balance-reports357672-Node: roi358757-Ref: #roi358857-Node: Spaces and special characters in --inv and --pnl360669-Ref: #spaces-and-special-characters-in---inv-and---pnl360907-Node: Semantics of --inv and --pnl361395-Ref: #semantics-of---inv-and---pnl361632-Node: IRR and TWR explained363482-Ref: #irr-and-twr-explained363640-Node: Chart commands366893-Ref: #chart-commands367051-Node: activity367074-Ref: #activity367163-Node: Data generation commands367537-Ref: #data-generation-commands367711-Node: close367743-Ref: #close367849-Node: close --migrate368502-Ref: #close---migrate368627-Node: close --close370266-Ref: #close---close370408-Node: close --open370644-Ref: #close---open370783-Node: close --assert370893-Ref: #close---assert371037-Node: close --assign371258-Ref: #close---assign371404-Node: close --retain371930-Ref: #close---retain372081-Node: close customisation372826-Ref: #close-customisation373003-Node: close and balance assertions374470-Ref: #close-and-balance-assertions374665-Node: close examples375992-Ref: #close-examples376131-Node: Retain earnings376229-Ref: #retain-earnings376386-Node: Migrate balances to a new file376732-Ref: #migrate-balances-to-a-new-file376956-Node: More detailed close examples378084-Ref: #more-detailed-close-examples378280-Node: rewrite378306-Ref: #rewrite378416-Node: Re-write rules in a file380314-Ref: #re-write-rules-in-a-file380475-Node: Diff output format381624-Ref: #diff-output-format381805-Node: rewrite vs print --auto382897-Ref: #rewrite-vs.-print---auto383055-Node: Maintenance commands383611-Ref: #maintenance-commands383782-Node: check383820-Ref: #check383919-Node: Basic checks384868-Ref: #basic-checks384986-Node: Strict checks385821-Ref: #strict-checks385962-Node: Other checks386696-Ref: #other-checks386836-Node: Custom checks388551-Ref: #custom-checks388671-Node: diff389006-Ref: #diff389116-Node: test390158-Ref: #test390254-Node: PART 5 COMMON TASKS390996-Ref: #part-5-common-tasks391155-Node: Getting help391229-Ref: #getting-help391378-Node: Constructing command lines392138-Ref: #constructing-command-lines392319-Node: Starting a journal file392976-Ref: #starting-a-journal-file393158-Node: Setting LEDGER_FILE394360-Ref: #setting-ledger_file394532-Node: Setting opening balances395489-Ref: #setting-opening-balances395670-Node: Recording transactions398811-Ref: #recording-transactions398980-Node: Reconciling399536-Ref: #reconciling399668-Node: Reporting401925-Ref: #reporting402054-Node: Migrating to a new file406039-Ref: #migrating-to-a-new-file406189-Node: BUGS406488-Ref: #bugs406582-Node: Troubleshooting407461-Ref: #troubleshooting407561+   This manual is for hledger's command line interface, version 1.40.+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 the commands list, run 'hledger' with no arguments.  The+commands are described in detail in PART 4: COMMANDS, below.++   To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]',++   * CMD is the full command name, or its standard abbreviation shown in+     the commands list, or any unambiguous prefix of the name.++   * CMDOPTS are command-specific options, if any.  Command-specific+     options must be written after the command name.  Eg: 'hledger print+     -x'.++   * CMDARGS are additional arguments to the command, if any.  Most+     hledger commands accept arguments representing a query, to limit+     the data in some way.  Eg: 'hledger reg assets:checking'.++   To list a command's options, arguments, and documentation in the+terminal, run 'hledger CMD -h'.  Eg: 'hledger bal -h'.++* Menu:++* Add-on commands::+++File: hledger.info,  Node: Add-on commands,  Up: Commands++3.1 Add-on commands+===================++In addition to the built-in commands, you can install _add-on commands_:+programs or scripts named "hledger-SOMETHING", which will also appear in+hledger's commands list.  If you used the hledger-install script, you+will have several add-ons installed already.  Some more can be found in+hledger's bin/ directory, documented at+https://hledger.org/scripts.html.++   More precisely, add-on commands are programs or scripts in your+shell's PATH, whose name starts with "hledger-" and ends with no+extension or a recognised extension (".bat", ".com", ".exe", ".hs",+".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),+and (on unix and mac) which has executable permission for the current+user.++   You can run add-on commands using hledger, much like built-in+commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'.  But note+the double hyphen argument, required before add-on-specific options.+Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'.  If this causes+difficulty, you can always run the add-on directly, without using+'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.+++File: hledger.info,  Node: Options,  Next: 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+     --depth=NUM            or -NUM: show only top NUM levels of accounts+  -E --empty                Show zero items, which are normally hidden.+                            In hledger-ui & hledger-web, do the opposite.+  -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'+     --color=YN --colour    Use ANSI color codes in text output? Can be+                            'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.+     --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)++   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::+++File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Up: Options++4.1 Special characters+======================++* Menu:++* Single escaping shell metacharacters::+* Double escaping regular expression metacharacters::+* Triple escaping for add-on commands::+* Less escaping::+++File: hledger.info,  Node: Single escaping shell metacharacters,  Next: Double escaping regular expression metacharacters,  Up: Special characters++4.1.1 Single escaping (shell metacharacters)+--------------------------------------------++In shell command lines, characters significant to your shell - such as+spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped"+if you want hledger to see them.  This is done by enclosing them in+single or double quotes, or by writing a backslash before them.  Eg to+match an account name containing a space:++$ hledger register 'credit card'++   or:++$ hledger register credit\ card++   Windows users should keep in mind that 'cmd' treats single quote as a+regular character, so you should be using double quotes exclusively.+PowerShell treats both single and double quotes as quotes.+++File: hledger.info,  Node: Double escaping regular expression metacharacters,  Next: Triple escaping for add-on commands,  Prev: Single escaping shell metacharacters,  Up: Special characters++4.1.2 Double escaping (regular expression metacharacters)+---------------------------------------------------------++Characters significant in regular expressions (described below) - such+as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be+"regex-escaped" if you don't want them to be interpreted by hledger's+regular expression engine.  This is done by writing backslashes before+them, but since backslash is typically also a shell metacharacter, both+shell-escaping and regex-escaping will be needed.  Eg to match a literal+'$' sign while using the bash shell:++$ hledger balance cur:'\$'++   or:++$ hledger balance cur:\\$+++File: hledger.info,  Node: Triple escaping for add-on commands,  Next: Less escaping,  Prev: Double escaping regular expression metacharacters,  Up: Special characters++4.1.3 Triple escaping (for add-on commands)+-------------------------------------------++When you use hledger to run an external add-on command (described+below), one level of shell-escaping is lost from any options or+arguments intended for by the add-on command, so those need an extra+level of shell-escaping.  Eg to match a literal '$' sign while using the+bash shell and running an add-on command ('ui'):++$ hledger ui cur:'\\$'++   or:++$ hledger ui cur:\\\\$++   If you wondered why _four_ backslashes, perhaps this helps:++unescaped:        '$'+escaped:          '\$'+double-escaped:   '\\$'+triple-escaped:   '\\\\$'++   Or, you can avoid the extra escaping by running the add-on executable+directly:++$ hledger-ui cur:\\$+++File: hledger.info,  Node: Less escaping,  Prev: Triple escaping for add-on commands,  Up: Special characters++4.1.4 Less escaping+-------------------++Options and arguments are sometimes used in places other than the shell+command line, where shell-escaping is not needed, so there you should+use one less level of escaping.  Those places include:++   * an @argumentfile+   * hledger-ui's filter field+   * hledger-web's search form+   * GHCI's prompt (used by developers).+++File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Options++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.++   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'.++   (Inside the argument file, 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.  For the special characters+mentioned above, use one less level of quoting than you would at the+command prompt.)++   Argument files are now superseded by..+++File: hledger.info,  Node: Config files,  Prev: Argument files,  Up: Options++4.5 Config files+================++As of hledger 1.40, you can optionally save command line options (or+arguments) to be used when running hledger commands, in a config file.+Here's a small example:++# General options are listed first, one or more per line.+# These will be used with all hledger commands that support them.+--pretty++# Options following a `[COMMANDNAME]` 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 if needed).  Or, you can add a 'hledger --conf' shebang+line to a config file and execute it like a script.++   Or, you can set up an automatic config file that is used whenever you+run hledger.  This can be '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').++   You can ignore config files by adding the '-n/--no-conf' flag.  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'.++   Here is another example config file you could start with:+https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample++   Automatic config files are convenient, but have a cost: it's easy to+change a report's behaviour, or break scripts/applications which use+hledger, in unintended ways that will surprise you later.  They change+the nature of hledger somewhat, making it less transparent and+predictable.  If you decide to use one, here are some tips:++   * Be conservative about what you put in it.  Try to consider the+     effect on all your reports.+   * Whenever a hledger command does not work as expected, try it again+     with '-n'.+   * If that helps, you can run it with '--debug' to see how a config+     file affected it.++   This feature has been added in hledger 1.40 and is considered+_experimental_.+++File: hledger.info,  Node: Output,  Next: Environment,  Prev: Options,  Up: Top++5 Output+********++* Menu:++* Output destination::+* Output format::+* Commodity styles::+* Colour::+* Box-drawing::+* Paging::+* Debug output::+++File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output++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:++-              txt          csv/tsv      html         fods         json sql+-----------------------------------------------------------------------------+aregister      Y            Y            Y                         Y+balance        Y _1_        Y _1_        Y _1_        Y _1_        Y+balancesheet   Y _1_        Y _1_        Y _1_                     Y+balancesheetequityY _1_     Y _1_        Y _1_                     Y+cashflow       Y _1_        Y _1_        Y _1_                     Y+incomestatementY _1_        Y _1_        Y _1_                     Y+print          Y            Y                                      Y    Y+register       Y            Y                                      Y++   * _1 Also affected by the balance commands' '--layout' option._++   The output format is selected by the '-O/--output-format=FMT' option:++$ hledger print -O csv    # print CSV on stdout++   or by the filename extension of an output file specified with the+'-o/--output-file=FILE.FMT' option:++$ hledger balancesheet -o foo.csv    # write CSV to foo.csv++   The '-O' option can be combined with '-o' to override the file+extension, if needed:++$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt++   Some notes about the various output formats:++* Menu:++* CSV output::+* HTML output::+* JSON output::+* SQL output::+++File: hledger.info,  Node: CSV output,  Next: HTML output,  Up: Output format++5.2.1 CSV output+----------------++   * In CSV output, digit group marks (such as thousands separators) are+     disabled automatically.+++File: hledger.info,  Node: HTML output,  Next: JSON output,  Prev: CSV output,  Up: Output format++5.2.2 HTML output+-----------------++   * HTML output can be styled by an optional 'hledger.css' file in the+     same directory.+++File: hledger.info,  Node: JSON output,  Next: SQL output,  Prev: HTML output,  Up: Output format++5.2.3 JSON output+-----------------++   * This is not yet much used; real-world feedback is welcome.++   * Our JSON is rather large and verbose, since it is a faithful+     representation of hledger's internal data types.  To understand the+     JSON, read the Haskell type definitions, which are mostly in+     https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.+     hledger-web's OpenAPI specification may also be relevant.++   * hledger represents quantities as Decimal values storing up to 255+     significant digits, eg for repeating decimals.  Such numbers can+     arise in practice (from automatically-calculated transaction+     prices), and would break most JSON consumers.  So in JSON, we show+     quantities as simple Numbers with at most 10 decimal places.  We+     don't limit the number of integer digits, but that part is under+     your control.  We hope this approach will not cause problems in+     practice; if you find otherwise, please let us know.  (Cf #1195)+++File: hledger.info,  Node: SQL output,  Prev: JSON output,  Up: Output format++5.2.4 SQL output+----------------++   * This is not yet much used; real-world feedback is welcome.++   * SQL output is expected to work at least with SQLite, MySQL and+     Postgres.++   * For SQLite, it will be more useful if you modify the generated 'id'+     field to be a PRIMARY KEY. Eg:++     $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...++   * SQL output is structured with the expectations that statements will+     be executed in the empty database.  If you already have tables+     created via SQL output of hledger, you would probably want to+     either clear tables of existing data (via 'delete' or 'truncate'+     SQL statements) or drop tables completely as otherwise your+     postings will be duped.+++File: hledger.info,  Node: Commodity styles,  Next: Colour,  Prev: Output format,  Up: Output++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: Colour,  Next: Box-drawing,  Prev: Commodity styles,  Up: Output++5.4 Colour+==========++In terminal output, some commands can produce colour when the terminal+supports it:++   * if the '--color/--colour' option is given a value of 'yes' or+     'always' (or 'no' or 'never'), colour will (or will not) be used;+   * otherwise, if the 'NO_COLOR' environment variable is set, colour+     will not be used;+   * otherwise, colour will be used if the output (terminal or file)+     supports it.+++File: hledger.info,  Node: Box-drawing,  Next: Paging,  Prev: Colour,  Up: Output++5.5 Box-drawing+===============++In terminal (text) output, to minimise the risk of display problems,+table borders are drawn using only ascii characters by default.++   To see tables with prettier unicode box-drawing characters, add the+'--pretty' flag.  This will also show outer borders and inter-column+borders.+++File: hledger.info,  Node: Paging,  Next: Debug output,  Prev: Box-drawing,  Up: Output++5.6 Paging+==========++When showing long output in the terminal, hledger will try to use the+pager specified by the 'PAGER' environment variable, or 'less', or+'more'.  (A pager is a helper program that shows one page at a time+rather than scrolling everything off screen).  Currently it does this+only for help output, not for reports; specifically,++   * when listing commands, with 'hledger'+   * when showing help with 'hledger [CMD] --help',+   * when viewing manuals with 'hledger help' or 'hledger --man'.++   Note the pager is expected to handle ANSI codes, which hledger uses+eg for bold emphasis.  For the common pager 'less' (and its 'more'+compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment+variables to make this work.  If you use a different pager, you might+need to configure it similarly, to avoid seeing junk on screen (let us+know).  Otherwise, you can set the 'NO_COLOR' environment variable to 1+to disable all ANSI output (see Colour).+++File: hledger.info,  Node: Debug output,  Prev: Paging,  Up: Output++5.7 Debug output+================++We intend hledger to be relatively easy to troubleshoot, introspect and+develop.  You can add '--debug[=N]' to any hledger command line to see+additional debug output.  N ranges from 1 (least output, the default) to+9 (maximum output).  Typically you would start with 1 and increase until+you are seeing enough.  Debug output goes to stderr, and is not affected+by '-o/--output-file' (unless you redirect stderr to stdout, eg:+'2>&1').  It will be interleaved with normal output, which can help+reveal when parts of the code are evaluated.  To capture debug output in+a log file instead, you can usually redirect stderr, eg:++hledger bal --debug=3 2>hledger.log+++File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top++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.++   *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'/'--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 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 virtual postings,  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 virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and subaccounts,  Up: Balance assertions++8.12.7 Assertions and virtual postings+--------------------------------------++Balance assertions always consider both real and virtual postings; they+are not affected by the '--real/-R' flag or 'real:' query.+++File: hledger.info,  Node: Assertions and auto postings,  Next: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions++8.12.8 Assertions and auto postings+-----------------------------------++Balance assertions _are_ affected by the '--auto' flag, which generates+auto postings, which can alter account balances.  Because auto postings+are optional in hledger, accounts affected by them effectively have two+balances.  But balance assertions can only test one or the other of+these.  So to avoid making fragile assertions, either:++   * assert the balance calculated with '--auto', and always use+     '--auto' with that file+   * or assert the balance calculated without '--auto', and never use+     '--auto' with that file+   * or avoid balance assertions on accounts affected by auto postings+     (or avoid auto postings entirely).+++File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and auto postings,  Up: Balance assertions++8.12.9 Assertions and precision+-------------------------------++Balance assertions compare the exactly calculated amounts, which are not+always what is shown by reports.  Eg a commodity directive may limit the+display precision, but this will not affect balance assertions.  Balance+assertion failure messages show exact amounts.+++File: hledger.info,  Node: Posting comments,  Next: 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, which you can then search or pivot on.++   A tag is a word, optionally hyphenated, immediately followed by a+full colon, in the comment of a transaction, a posting, or an account+directive.  Eg: '2024-01-01 a transaction ; foo:' Note this is an+exception to the usual rule that things in comments are ignored.++   You can write multiple tags on one line, separated by comma.  Or you+can write each tag on its own comment line (no comma needed in this+case).++   For example, here are five different tags: one on the+'assets:checking' account, two on the transaction, and two on the+'expenses:food' posting:++account assets:checking         ; accounttag:++2017/1/16 bought groceries      ; transactiontag-1:+    ; transactiontag-2:+    assets:checking        $-1+    expenses:food           $1  ; postingtag:, another-posting-tag:++   Postings also inherit tags from their transaction and their account.+And transactions also acquire tags from their postings (and postings'+accounts).  So in the example above, the expenses posting effectively+has all five tags (by inheriting from the account and transaction), and+the transaction also has all five tags (by acquiring from the expenses+posting).++* Menu:++* Tag names::+* Special tags::+* Tag values::+++File: hledger.info,  Node: Tag names,  Next: Special tags,  Up: Tags++8.15.1 Tag names+----------------++Most non-whitespace characters are allowed in tag names.  Eg '😀:' is a+valid tag.++   You can list the tag names used in your journal with the tags+command:+'hledger tags [NAMEREGEX]'++   In commands which use a query, you can match by tag name.  Eg:+'hledger print tag:NAMEREGEX'++   You can declare valid tag names with the tag directive and then check+them with the check command.+++File: hledger.info,  Node: Special tags,  Next: Tag values,  Prev: Tag names,  Up: Tags++8.15.2 Special tags+-------------------++Some tag names have special significance to hledger.  There's not much+harm in using them yourself, but some could produce an error message,+particularly the 'date:' and 'type:' tags.  They are explained+elsewhere, but here is a quick list for reference:++   Tags you can set to influence hledger's behaviour:++ date                   -- overrides a posting's date+ date2                  -- overrides a posting's secondary date+ type                   -- declares an account's type++   Tags hledger adds to indicate generated data:++ t                      -- appears on postings generated by timedot letters+ 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+ generated-transaction  -- appears on generated periodic txns (with --verbose-tags)+ generated-posting      -- appears on generated auto postings (with --verbose-tags)+ modified               -- appears on txns which have had auto postings added (with --verbose-tags)+Not displayed, but queryable:+ _generated-transaction -- exists on generated periodic txns (always)+ _generated-posting     -- exists on generated auto postings (always)+ _modified              -- exists on txns which have had auto postings added (always)++   Tags hledger uses internally:++ _conversion-matched    -- exists on postings which have been matched with a nearby @/@@ cost annotation+++File: hledger.info,  Node: Tag values,  Prev: Special tags,  Up: Tags++8.15.3 Tag values+-----------------++Tags can have a value, which is any text after the colon up until a+comma or end of line, with surrounding whitespace removed.  Ending at+comma allows us to write multiple tags on one line, but also means that+tag values can not contain commas.++   Eg in the following posting, the three tags' values are "value 1",+"value 2", and "" (empty) respectively:++    expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz++   Multiple tags with the same name are additive rather than overriding:+when the same tag name is seen again with a new value, the new+name:value pair is added to the tags.  It is not possible to override a+previous tag's value or remove a tag.++   You can list all the values used for a particular tag in the journal+with+'hledger tags TAGNAME --values'++   You can match on tag values with a query like+'tag:NAMEREGEX=VALUEREGEX'+++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, hledger will+report an error if any transaction uses an account name that has not+been declared by an account directive.  Some notes:++   * The declaration is case-sensitive; transactions must use the+     correct account name capitalisation.+   * The account directive's scope is "whole file and below" (see+     directives).  This means it affects all of the current file, and+     any files it includes, but not parent or sibling files.  The+     position of account directives within the file does not matter,+     though it's usual to put them at the top.+   * Accounts can only be declared in 'journal' files, but will affect+     included files of all types.+   * It's currently not possible to declare "all possible subaccounts"+     with a wildcard; every account posted to must be declared.+++File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive++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.+++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:++  1. A record matcher is a word or single-line text fragment or regular+     expression ('REGEX'), which hledger will try to match+     case-insensitively anywhere within the CSV record.+     Eg: 'whole foods'++  2. A field matcher is preceded with a percent sign and CSV field name+     ('%CSVFIELD REGEX').  hledger will try to match these just within+     the named CSV field.+     Eg: '%date 2023'++   The regular expression is (as usual in hledger) a POSIX extended+regular expression, that also supports GNU word boundaries ('\b', '\B',+'\<', '\>'), and nothing else.  If you have trouble, see "Regular+expressions" in the hledger manual+(https://hledger.org/hledger.html#regular-expressions).++* Menu:++* What matchers match::+* Combining matchers::+* Match groups::+++File: hledger.info,  Node: What matchers match,  Next: Combining matchers,  Up: Matchers++9.14.1 What matchers match+--------------------------++With record matchers, it's important to know that the record matched is+not the original CSV record, but a modified one: separators will be+converted to commas, and enclosing double quotes (but not enclosing+whitespace) are removed.  So for example, when reading an SSV file, if+the original record was:++2023-01-01; "Acme, Inc.";  1,000++   the regex would see, and try to match, this modified record text:++2023-01-01,Acme, Inc.,  1,000+++File: hledger.info,  Node: Combining matchers,  Next: Match groups,  Prev: What matchers match,  Up: Matchers++9.14.2 Combining matchers+-------------------------++When an if block has multiple matchers, they are combined as follows:++   * By default they are OR'd (any of them can match)+   * When a matcher is preceded by ampersand ('&', at the start of the+     line) it will be AND'ed with the previous matcher (all in the+     AND'ed group must match)+   * _Added in 1.32_ When a matcher is preceded by an exclamation mark+     ('!'), it is negated (it must not match).++   Note currently there is a limitation: you can't use both '&' and '!'+on the same line (you can't AND a negated matcher).+++File: hledger.info,  Node: Match groups,  Prev: Combining matchers,  Up: Matchers++9.14.3 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.++* 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.+++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.  Remember these can also be+prefixed with *'not:'* to convert them into a negative match.++   *'acct:REGEX'* or *'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.++   *'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.++   *'code:REGEX'*+Match by transaction code (eg check number).++   *'cur:REGEX'*+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX. (For a partial+match, use '.*REGEX.*').  Note, to match special characters which are+regex-significant, you need to escape them with '\'.  And for characters+which are significant to your shell you may need one more level of+escaping.  So eg to match the dollar sign:+'hledger print cur:\\$'.++   *'desc:REGEX'*+Match transaction descriptions.++   *'date:PERIODEXPR'*+Match dates (or with the '--date2' flag, secondary dates) within the+specified period.  PERIODEXPR is a period expression with no report+interval.  Examples:+'date:2016', 'date:thismonth', 'date:2/1-2/15',+'date:2021-07-27..nextquarter'.++   *'date2:PERIODEXPR'*+Match secondary dates within the specified period (independent of the+'--date2' flag).++   *'depth:N'*+Match (or display, depending on command) accounts at or above this+depth.++   *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg)+Match with a boolean combination of queries (which must be enclosed in+quotes).  See Combining query terms below.++   *'note:REGEX'*+Match transaction notes (the part of the description right of '|', or+the whole description if there's no '|').++   *'payee:REGEX'*+Match transaction payee/payer names (the part of the description left of+'|', or the whole description if there's no '|').++   *'real:, real:0'*+Match real or virtual postings respectively.++   *'status:, status:!, status:*'*+Match unmarked, pending, or cleared transactions respectively.++   *'type:TYPECODES'*+Match by account type (see Declaring accounts > Account types).+'TYPECODES' is one or more of the single-letter account type codes+'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match+their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain+kinds of account alias can disrupt account types, see Rewriting accounts+> Aliases and account types.++   *'tag:REGEX[=REGEX]'*+Match by tag name, and optionally also by tag value.  (To match only by+value, use 'tag:.=REGEX'.)++   When querying by tag, note that:++   * Accounts also inherit the tags of their parent accounts+   * Postings also inherit the tags of their account and their+     transaction+   * Transactions also acquire the tags of their postings.++   (*'inacct:ACCTNAME'*+A special query term used automatically in hledger-web only: tells+hledger-web to show the transaction register for an account.)+++File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries++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.+++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 each FILE argument since it+was last run, and appends them to the main journal.++   Or with '--dry-run', it just print the transactions that would be+added.++   Or with '--catchup', it just marks all of the FILEs' current+transactions as already imported.++   This is one of the few hledger commands that writes to the journal+file (see also 'add').  It only appends; existing data will not be+changed.++   The input files are specified as arguments, so to import one or more+CSV files to your main journal, you will run 'hledger import bank.csv'+or perhaps 'hledger import *.csv'.++   Note you can import from any file format, though CSV files are the+most common import source, and these docs focus on that case.  The+target file (main journal) should be in journal format.++* Menu:++* Date skipping::+* Import testing::+* Importing balance assignments::+* Import and commodity styles::+++File: hledger.info,  Node: Date skipping,  Next: Import testing,  Up: import++26.2.1 Date skipping+--------------------++'import' tries to import only the transactions which are new since the+last import, ignoring any that it has seen in previous runs.  So if your+bank's CSV includes the last three months of data, you can download and+'import' it every month (or week, or day) and only the new transactions+will be imported each time.++   It works as follows: for each imported 'FILE',++   * It tries to read the latest date previously seen, from+     '.latest.FILE' in the same directory+   * Then it processes 'FILE', ignoring transactions on or before that+     date++   And after a successful import, unless '--dry-run' was used, it+updates the '.latest.FILE'(s) for next time.  This is a simple system+that works for most real-world CSV files; it assumes the following are+true, or true enough:++  1. the name of the input file is stable across successive downloads+  2. new items always have the newest dates+  3. item dates are stable across downloads+  4. the order of same-date items is stable across downloads.++   Tips:++   * To help ensure a stable file name, remember you can use a CSV rules+     file as an input file.++   * If you have a bank whose CSV dates or ordering occasionally change,+     you can reduce the chance of this happening in new transactions by+     importing more often.  (If it happens in old transactions, that's+     harmless.)++   Note this is just one kind of "deduplication": not reprocessing the+same dates across successive runs.  'import' doesn't detect other kinds+of duplication, such as the same transaction appearing multiple times+within a single run, or a new transaction that looks identical to a+transaction already in the journal.  (Because these can happen+legitimately in real-world data.)++   Here's a situation where you need to run 'import' with care: say you+download but forget to import 'bank.1.csv', and a week later you+download 'bank.2.csv' with some overlapping data.  You should not+process both of these as a single import ('hledger import bank.1.csv+bank.2.csv'), because the overlapping transactions would not be+deduplicated.  Instead, import one file at a time, using the same+filename each time:++$ mv bank.1.csv bank.csv; hledger import bank.csv+$ mv bank.2.csv bank.csv; hledger import bank.csv++   Normally you don't need to think about '.latest.*' files, but you can+create or modify them to catch up to a certain date, or delete them to+mark all transactions as new.  Their format is a single ISO-format+'YYYY-MM-DD' date, optionally repeated on multiple lines, meaning "I+have seen the transactions before this date, and this many of them on+this date".++   'hledger print --new' also uses and updates these '.latest.*' files,+but it is less often used.++   Related: CSV > Working with CSV > Deduplicating, importing.+++File: hledger.info,  Node: Import testing,  Next: Importing balance assignments,  Prev: Date skipping,  Up: import++26.2.2 Import testing+---------------------++With '--dry-run', the transactions that will be imported are printed to+the terminal, without updating your journal or state files.  The output+is valid journal format, like the print command, so you can re-parse it.+Eg, to see any importable transactions which CSV rules have not+categorised:++$ hledger import --dry bank.csv | hledger -f- -I print unknown++   or (live updating):++$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'++   Note: when importing from multiple files at once, it's currently+possible for some .latest files to be updated successfully, while the+actual import fails because of a problem in one of the files, leaving+them out of sync (and causing some transactions to be missed).  To+prevent this, do a -dry-run first and fix any problems before the real+import.+++File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: Import testing,  Up: import++26.2.3 Importing balance assignments+------------------------------------++Entries added by import will have their posting amounts made explicit+(like 'hledger print -x').  This means that any balance assignments in+imported files must be evaluated; but, imported files don't get to see+the main file's account balances.  As a result, importing entries with+balance assignments (eg from an institution that provides only balances+and not posting amounts) will probably generate incorrect posting+amounts.  To avoid this problem, use print instead of import:++$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE++   (If you think import should leave amounts implicit like print does,+please test it and send a pull request.)+++File: hledger.info,  Node: Import and commodity styles,  Prev: Importing balance assignments,  Up: import++26.2.4 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: 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+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, beancount, csv, tsv, 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+  -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 always included in the running balance ('--historical' mode is+always on).++   This is a more "real world", bank-like view than the 'register'+command (which shows individual postings, possibly from multiple+accounts, not necessarily in historical mode).  As a quick rule of+thumb: - use 'aregister' for reviewing and reconciling real-world+asset/liability accounts - use 'register' for reviewing detailed+revenues/expenses.++   'aregister' requires one argument: the account to report on.  You can+write either the full account name, or a case-insensitive regular+expression which will select the alphabetically first matched account.++   When there are multiple matches, the alphabetically-first choice can+be surprising; eg if you have 'assets:per:checking 1' and+'assets:biz:checking 2' accounts, 'hledger areg checking' would select+'assets:biz:checking 2'.  It's just a convenience to save typing, so if+in doubt, write the full account name, or a distinctive substring that+matches uniquely.++   Transactions involving subaccounts of this account will also be+shown.  'aregister' ignores depth limits, so its final total will always+match a balance report with similar arguments.++   Any additional arguments form a query which will filter the+transactions shown.  Note some queries will disturb the running balance,+causing it to be different from the account's real-world running+balance.++   An example: this shows the transactions and historical running+balance during july, in the first account whose name contains+"checking":++$ hledger areg checking date:jul++   Each 'aregister' line item shows:++   * the transaction's date (or the relevant posting's date if+     different, see below)+   * the names of all the other account(s) involved in this transaction+     (probably abbreviated)+   * the total change to this account's balance from this transaction+   * the account's historical running balance after this transaction.++   Transactions making a net change of zero are not shown by default;+add the '-E/--empty' flag to show them.++   For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted.  If you want to+ensure perfect alignment, at the cost of more time and memory, use the+'--align-all' flag.++   This command also supports the output destination and output format+options.  The output formats supported are 'txt', 'csv', 'tsv' (_Added+in 1.32_), 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)+  -O --output-format=FMT    select the output format. Supported formats:+                            txt, csv, tsv, 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+     --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+  -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+     --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+  -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+     --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+  -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+     --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+  -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)+     --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).+     --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)+     --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)+  -r --related              show postings' siblings instead+  -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+     --invert               display all amounts with reversed sign+     --transpose            transpose rows and columns+     --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+  -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::+* 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: Some useful balance reports,  Prev: Budget report,  Up: balance++29.1.15 Balance report layout+-----------------------------++The '--layout' option affects how balance reports show multi-commodity+amounts and commodity symbols, which can improve readability.  It can+also normalise the data for easy consumption by other programs.  It has+four possible values:++   * '--layout=wide[,WIDTH]': commodities are shown on a single line,+     optionally elided to WIDTH+   * '--layout=tall': each commodity is shown on a separate line+   * '--layout=bare': commodity symbols are in their own column, amounts+     are bare numbers+   * '--layout=tidy': data is normalised to easily-consumed "tidy" form,+     with one row per data value++   Here are the '--layout' modes supported by each output format 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: Some useful balance reports,  Prev: Balance report layout,  Up: balance++29.1.16 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"+++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:+http://bugs.hledger.org), or on the #hledger chat or hledger mail list+(https://hledger.org/support).++   Some known issues and limitations:++   The need to precede add-on command options with '--' when invoked+from hledger is awkward.  (See Command options, Constructing command+lines.)++   A UTF-8-aware system locale must be configured to work with non-ascii+data.  (See Unicode characters, Troubleshooting.)++   On Microsoft Windows, depending whether you are running in a CMD+window or a Cygwin/MSYS/Mintty window and how you installed hledger,+non-ascii characters and colours may not be supported, and the tab key+may not be supported by 'hledger add'.  (Running in a WSL window should+resolve these.)++   When processing large data files, hledger uses more memory than+Ledger.++* Menu:++* Troubleshooting::+++File: hledger.info,  Node: Troubleshooting,  Up: BUGS++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).+   * 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+Ref: #part-1-user-interface4499+Node: Input4499+Ref: #input4609+Node: Text encoding5591+Ref: #text-encoding5705+Node: Data formats6271+Ref: #data-formats6406+Node: Standard input7995+Ref: #standard-input8135+Node: Multiple files8384+Ref: #multiple-files8523+Node: Strict mode9121+Ref: #strict-mode9231+Node: Commands9955+Ref: #commands10057+Node: Add-on commands11124+Ref: #add-on-commands11226+Node: Options12342+Ref: #options12443+Node: Special characters18737+Ref: #special-characters18874+Node: Single escaping shell metacharacters19037+Ref: #single-escaping-shell-metacharacters19278+Node: Double escaping regular expression metacharacters19881+Ref: #double-escaping-regular-expression-metacharacters20192+Node: Triple escaping for add-on commands20718+Ref: #triple-escaping-for-add-on-commands20978+Node: Less escaping21622+Ref: #less-escaping21776+Node: Unicode characters22100+Ref: #unicode-characters22265+Node: Regular expressions23764+Ref: #regular-expressions23927+Node: hledger's regular expressions27023+Ref: #hledgers-regular-expressions27182+Node: Argument files28568+Ref: #argument-files28715+Node: Config files29221+Ref: #config-files29336+Node: Output31438+Ref: #output31540+Node: Output destination31667+Ref: #output-destination31798+Node: Output format32223+Ref: #output-format32369+Node: CSV output33854+Ref: #csv-output33970+Node: HTML output34073+Ref: #html-output34211+Node: JSON output34305+Ref: #json-output34443+Node: SQL output35428+Ref: #sql-output35544+Node: Commodity styles36279+Ref: #commodity-styles36419+Node: Colour37157+Ref: #colour37275+Node: Box-drawing37679+Ref: #box-drawing37797+Node: Paging38081+Ref: #paging38195+Node: Debug output39148+Ref: #debug-output39254+Node: Environment39917+Ref: #environment40041+Node: PART 2 DATA FORMATS40608+Ref: #part-2-data-formats40751+Node: Journal40751+Ref: #journal40860+Node: Journal cheatsheet43229+Ref: #journal-cheatsheet43356+Node: Comments49443+Ref: #comments49571+Node: Transactions50387+Ref: #transactions50510+Node: Dates51524+Ref: #dates51631+Node: Simple dates51676+Ref: #simple-dates51792+Node: Posting dates52292+Ref: #posting-dates52410+Node: Status53379+Ref: #status53480+Node: Code55145+Ref: #code55248+Node: Description55480+Ref: #description55611+Node: Payee and note56167+Ref: #payee-and-note56273+Node: Transaction comments57258+Ref: #transaction-comments57411+Node: Postings57774+Ref: #postings57905+Node: Debits and credits58937+Ref: #debits-and-credits59084+Node: The two space delimiter59547+Ref: #the-two-space-delimiter59704+Node: Account names60112+Ref: #account-names60242+Node: Amounts61916+Ref: #amounts62044+Node: Decimal marks62945+Ref: #decimal-marks63072+Node: Digit group marks64049+Ref: #digit-group-marks64202+Node: Commodity64684+Ref: #commodity64813+Node: Costs65801+Ref: #costs65896+Node: Balance assertions68053+Ref: #balance-assertions68206+Node: Assertions and ordering69290+Ref: #assertions-and-ordering69479+Node: Assertions and multiple included files70018+Ref: #assertions-and-multiple-included-files70278+Node: Assertions and multiple -f files70778+Ref: #assertions-and-multiple--f-files71023+Node: Assertions and costs71420+Ref: #assertions-and-costs71629+Node: Assertions and commodities72070+Ref: #assertions-and-commodities72285+Node: Assertions and subaccounts73729+Ref: #assertions-and-subaccounts73955+Node: Assertions and virtual postings74399+Ref: #assertions-and-virtual-postings74637+Node: Assertions and auto postings74769+Ref: #assertions-and-auto-postings74999+Node: Assertions and precision75644+Ref: #assertions-and-precision75826+Node: Posting comments76093+Ref: #posting-comments76256+Node: Transaction balancing76633+Ref: #transaction-balancing76792+Node: Tags78635+Ref: #tags78754+Node: Tag names80097+Ref: #tag-names80204+Node: Special tags80592+Ref: #special-tags80724+Node: Tag values82237+Ref: #tag-values82347+Node: Directives83219+Ref: #directives83346+Node: Directives and multiple files84676+Ref: #directives-and-multiple-files84854+Node: Directive effects85621+Ref: #directive-effects85775+Node: account directive88777+Ref: #account-directive88933+Node: Account comments90227+Ref: #account-comments90378+Node: Account error checking90886+Ref: #account-error-checking91079+Node: Account display order92268+Ref: #account-display-order92456+Node: Account types93466+Ref: #account-types93607+Node: alias directive97240+Ref: #alias-directive97401+Node: Basic aliases98451+Ref: #basic-aliases98582+Node: Regex aliases99326+Ref: #regex-aliases99483+Node: Combining aliases100373+Ref: #combining-aliases100551+Node: Aliases and multiple files101827+Ref: #aliases-and-multiple-files102031+Node: end aliases directive102610+Ref: #end-aliases-directive102829+Node: Aliases can generate bad account names102978+Ref: #aliases-can-generate-bad-account-names103226+Node: Aliases and account types103811+Ref: #aliases-and-account-types104003+Node: commodity directive104699+Ref: #commodity-directive104873+Node: Commodity directive syntax106286+Ref: #commodity-directive-syntax106471+Node: Commodity error checking107922+Ref: #commodity-error-checking108103+Node: decimal-mark directive108397+Ref: #decimal-mark-directive108579+Node: include directive108976+Ref: #include-directive109140+Node: P directive110052+Ref: #p-directive110197+Node: payee directive111086+Ref: #payee-directive111235+Node: tag directive111708+Ref: #tag-directive111863+Node: Periodic transactions112320+Ref: #periodic-transactions112485+Node: Periodic rule syntax114474+Ref: #periodic-rule-syntax114652+Node: Periodic rules and relative dates115297+Ref: #periodic-rules-and-relative-dates115563+Node: Two spaces between period expression and description!116074+Ref: #two-spaces-between-period-expression-and-description116351+Node: Auto postings117035+Ref: #auto-postings117183+Node: Auto postings and multiple files120195+Ref: #auto-postings-and-multiple-files120391+Node: Auto postings and dates120600+Ref: #auto-postings-and-dates120866+Node: Auto postings and transaction balancing / inferred amounts / balance assertions121041+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions121384+Node: Auto posting tags121887+Ref: #auto-posting-tags122146+Node: Auto postings on forecast transactions only122782+Ref: #auto-postings-on-forecast-transactions-only123005+Node: Other syntax123252+Ref: #other-syntax123368+Node: Balance assignments124024+Ref: #balance-assignments124180+Node: Balance assignments and costs125552+Ref: #balance-assignments-and-costs125764+Node: Balance assignments and multiple files125974+Ref: #balance-assignments-and-multiple-files126204+Node: Bracketed posting dates126397+Ref: #bracketed-posting-dates126581+Node: D directive127095+Ref: #d-directive127263+Node: apply account directive128868+Ref: #apply-account-directive129048+Node: Y directive129735+Ref: #y-directive129895+Node: Secondary dates130723+Ref: #secondary-dates130877+Node: Star comments132208+Ref: #star-comments132368+Node: Valuation expressions132900+Ref: #valuation-expressions133077+Node: Virtual postings133199+Ref: #virtual-postings133376+Node: Other Ledger directives134823+Ref: #other-ledger-directives135019+Node: Other cost/lot notations135585+Ref: #other-costlot-notations135758+Node: CSV138347+Ref: #csv138438+Node: CSV rules cheatsheet140430+Ref: #csv-rules-cheatsheet140557+Node: source142355+Ref: #source142476+Node: separator143356+Ref: #separator143467+Node: skip144007+Ref: #skip144113+Node: date-format144657+Ref: #date-format144776+Node: timezone145500+Ref: #timezone145621+Node: newest-first146626+Ref: #newest-first146762+Node: intra-day-reversed147339+Ref: #intra-day-reversed147491+Node: decimal-mark147939+Ref: #decimal-mark148078+Node: fields list148417+Ref: #fields-list148554+Node: Field assignment150225+Ref: #field-assignment150367+Node: Field names151444+Ref: #field-names151573+Node: date field152776+Ref: #date-field152892+Node: date2 field152940+Ref: #date2-field153079+Node: status field153135+Ref: #status-field153276+Node: code field153325+Ref: #code-field153468+Node: description field153513+Ref: #description-field153671+Node: comment field153730+Ref: #comment-field153883+Node: account field154176+Ref: #account-field154324+Node: amount field154894+Ref: #amount-field155041+Node: currency field157733+Ref: #currency-field157884+Node: balance field158141+Ref: #balance-field158271+Node: if block158664+Ref: #if-block158783+Node: Matchers160191+Ref: #matchers160303+Node: What matchers match161100+Ref: #what-matchers-match161247+Node: Combining matchers161687+Ref: #combining-matchers161853+Node: Match groups162390+Ref: #match-groups162516+Node: if table163284+Ref: #if-table163404+Node: balance-type165285+Ref: #balance-type165412+Node: include166112+Ref: #include166237+Node: Working with CSV166681+Ref: #working-with-csv166826+Node: Rapid feedback167233+Ref: #rapid-feedback167364+Node: Valid CSV167816+Ref: #valid-csv167960+Node: File Extension168692+Ref: #file-extension168863+Node: Reading CSV from standard input169427+Ref: #reading-csv-from-standard-input169649+Node: Reading multiple CSV files169813+Ref: #reading-multiple-csv-files170042+Node: Reading files specified by rule170289+Ref: #reading-files-specified-by-rule170515+Node: Valid transactions171686+Ref: #valid-transactions171883+Node: Deduplicating importing172511+Ref: #deduplicating-importing172704+Node: Setting amounts173740+Ref: #setting-amounts173909+Node: Amount signs176267+Ref: #amount-signs176435+Node: Setting currency/commodity177332+Ref: #setting-currencycommodity177534+Node: Amount decimal places178708+Ref: #amount-decimal-places178912+Node: Referencing other fields179965+Ref: #referencing-other-fields180176+Node: How CSV rules are evaluated181073+Ref: #how-csv-rules-are-evaluated181288+Node: Well factored rules182741+Ref: #well-factored-rules182907+Node: CSV rules examples183231+Ref: #csv-rules-examples183364+Node: Bank of Ireland183429+Ref: #bank-of-ireland183564+Node: Coinbase185026+Ref: #coinbase185162+Node: Amazon186209+Ref: #amazon186332+Node: Paypal188051+Ref: #paypal188157+Node: Timeclock195801+Ref: #timeclock195906+Node: Timedot198070+Ref: #timedot198193+Node: Timedot examples201314+Ref: #timedot-examples201420+Node: PART 3 REPORTING CONCEPTS203591+Ref: #part-3-reporting-concepts203755+Node: Time periods203755+Ref: #time-periods203889+Node: Report start & end date204028+Ref: #report-start-end-date204180+Node: Smart dates205504+Ref: #smart-dates205657+Node: Report intervals207447+Ref: #report-intervals207603+Node: Date adjustments208021+Ref: #date-adjustments208181+Node: Start date adjustment208241+Ref: #start-date-adjustment208403+Node: End date adjustment209144+Ref: #end-date-adjustment209302+Node: Period headings209889+Ref: #period-headings210049+Node: Period expressions210822+Ref: #period-expressions210963+Node: Period expressions with a report interval212727+Ref: #period-expressions-with-a-report-interval212961+Node: More complex report intervals213175+Ref: #more-complex-report-intervals213420+Node: Multiple weekday intervals215291+Ref: #multiple-weekday-intervals215480+Node: Depth216302+Ref: #depth216404+Node: Queries216700+Ref: #queries216802+Node: Query types218398+Ref: #query-types218519+Node: Combining query terms221753+Ref: #combining-query-terms221930+Node: Queries and command options223493+Ref: #queries-and-command-options223698+Node: Queries and account aliases223947+Ref: #queries-and-account-aliases224152+Node: Queries and valuation224272+Ref: #queries-and-valuation224429+Node: Pivoting224634+Ref: #pivoting224748+Node: Generating data226525+Ref: #generating-data226657+Node: Forecasting228325+Ref: #forecasting228450+Node: --forecast228981+Ref: #forecast229112+Node: Inspecting forecast transactions230082+Ref: #inspecting-forecast-transactions230284+Node: Forecast reports231415+Ref: #forecast-reports231588+Node: Forecast tags232524+Ref: #forecast-tags232684+Node: Forecast period in detail233144+Ref: #forecast-period-in-detail233338+Node: Forecast troubleshooting234232+Ref: #forecast-troubleshooting234400+Node: Budgeting235303+Ref: #budgeting235426+Node: Amount formatting235863+Ref: #amount-formatting236005+Node: Commodity display style236107+Ref: #commodity-display-style236261+Node: Rounding237948+Ref: #rounding238103+Node: Trailing decimal marks238553+Ref: #trailing-decimal-marks238732+Node: Amount parseability239486+Ref: #amount-parseability239642+Node: Cost reporting241067+Ref: #cost-reporting241209+Node: Recording costs241870+Ref: #recording-costs242006+Node: Reporting at cost243597+Ref: #reporting-at-cost243772+Node: Equity conversion postings244362+Ref: #equity-conversion-postings244576+Node: Inferring equity conversion postings247007+Ref: #inferring-equity-conversion-postings247270+Node: Combining costs and equity conversion postings248022+Ref: #combining-costs-and-equity-conversion-postings248332+Node: Requirements for detecting equity conversion postings249247+Ref: #requirements-for-detecting-equity-conversion-postings249569+Node: Infer cost and equity by default ?250769+Ref: #infer-cost-and-equity-by-default250998+Node: Value reporting251206+Ref: #value-reporting251348+Node: -V Value252087+Ref: #v-value252219+Node: -X Value in specified commodity252414+Ref: #x-value-in-specified-commodity252615+Node: Valuation date252764+Ref: #valuation-date252941+Node: Finding market price253724+Ref: #finding-market-price253935+Node: --infer-market-prices market prices from transactions255104+Ref: #infer-market-prices-market-prices-from-transactions255386+Node: Valuation commodity258148+Ref: #valuation-commodity258368+Node: --value Flexible valuation259581+Ref: #value-flexible-valuation259780+Node: Valuation examples261424+Ref: #valuation-examples261624+Node: Interaction of valuation and queries263556+Ref: #interaction-of-valuation-and-queries263796+Node: Effect of valuation on reports264273+Ref: #effect-of-valuation-on-reports264476+Node: PART 4 COMMANDS272171+Ref: #part-4-commands272314+Node: Help commands274387+Ref: #help-commands274532+Node: help274560+Ref: #help274649+Node: demo276237+Ref: #demo276326+Node: User interface commands277370+Ref: #user-interface-commands277539+Node: ui277564+Ref: #ui277656+Node: web277689+Ref: #web277783+Node: Data entry commands277817+Ref: #data-entry-commands277986+Node: add278015+Ref: #add278109+Node: import280470+Ref: #import280570+Node: Date skipping281731+Ref: #date-skipping281854+Node: Import testing284632+Ref: #import-testing284795+Node: Importing balance assignments285638+Ref: #importing-balance-assignments285845+Node: Import and commodity styles286494+Ref: #import-and-commodity-styles286674+Node: Basic report commands286903+Ref: #basic-report-commands287077+Node: accounts287204+Ref: #accounts287314+Node: codes290077+Ref: #codes290201+Node: commodities291099+Ref: #commodities291239+Node: descriptions291343+Ref: #descriptions291485+Node: files291810+Ref: #files291932+Node: notes292107+Ref: #notes292223+Node: payees292619+Ref: #payees292738+Node: prices293403+Ref: #prices293522+Node: stats294295+Ref: #stats294410+Node: tags296036+Ref: #tags-1296136+Node: Standard report commands297343+Ref: #standard-report-commands297528+Node: print297648+Ref: #print297756+Node: print explicitness300094+Ref: #print-explicitness300235+Node: print amount style301014+Ref: #print-amount-style301182+Node: print parseability302252+Ref: #print-parseability302422+Node: print other features303171+Ref: #print-other-features303348+Node: print output format303869+Ref: #print-output-format304015+Node: aregister307154+Ref: #aregister307287+Node: aregister and posting dates310934+Ref: #aregister-and-posting-dates311079+Node: register311835+Ref: #register311973+Node: Custom register output318794+Ref: #custom-register-output318923+Node: balancesheet320270+Ref: #balancesheet320425+Node: balancesheetequity324906+Ref: #balancesheetequity325073+Node: cashflow329912+Ref: #cashflow330062+Node: incomestatement334340+Ref: #incomestatement334477+Node: Advanced report commands338804+Ref: #advanced-report-commands338982+Node: balance339012+Ref: #balance339120+Node: balance features343901+Ref: #balance-features344041+Node: Simple balance report345977+Ref: #simple-balance-report346162+Node: Balance report line format347787+Ref: #balance-report-line-format347989+Node: Filtered balance report350147+Ref: #filtered-balance-report350339+Node: List or tree mode350666+Ref: #list-or-tree-mode350834+Node: Depth limiting352179+Ref: #depth-limiting352345+Node: Dropping top-level accounts352946+Ref: #dropping-top-level-accounts353146+Node: Showing declared accounts353456+Ref: #showing-declared-accounts353655+Node: Sorting by amount354186+Ref: #sorting-by-amount354353+Node: Percentages355023+Ref: #percentages355182+Node: Multi-period balance report355730+Ref: #multi-period-balance-report355930+Node: Balance change end balance358482+Ref: #balance-change-end-balance358691+Node: Balance report types360119+Ref: #balance-report-types360300+Node: Calculation type360798+Ref: #calculation-type360953+Node: Accumulation type361502+Ref: #accumulation-type361682+Node: Valuation type362603+Ref: #valuation-type362791+Node: Combining balance report types363792+Ref: #combining-balance-report-types363986+Node: Budget report365824+Ref: #budget-report365986+Node: Using the budget report368129+Ref: #using-the-budget-report368302+Node: Budget date surprises370405+Ref: #budget-date-surprises370605+Node: Selecting budget goals371769+Ref: #selecting-budget-goals371972+Node: Budgeting vs forecasting372717+Ref: #budgeting-vs-forecasting372894+Node: Balance report layout374394+Ref: #balance-report-layout374579+Node: Wide layout375532+Ref: #wide-layout375667+Node: Tall layout377937+Ref: #tall-layout378092+Node: Bare layout379243+Ref: #bare-layout379398+Node: Tidy layout381307+Ref: #tidy-layout381442+Node: Some useful balance reports382851+Ref: #some-useful-balance-reports383026+Node: roi384111+Ref: #roi384211+Node: Spaces and special characters in --inv and --pnl386358+Ref: #spaces-and-special-characters-in---inv-and---pnl386596+Node: Semantics of --inv and --pnl387084+Ref: #semantics-of---inv-and---pnl387321+Node: IRR and TWR explained389171+Ref: #irr-and-twr-explained389329+Node: Chart commands392582+Ref: #chart-commands392740+Node: activity392763+Ref: #activity392852+Node: Data generation commands393260+Ref: #data-generation-commands393434+Node: close393466+Ref: #close393572+Node: close --migrate396058+Ref: #close---migrate396183+Node: close --close397822+Ref: #close---close397964+Node: close --open398200+Ref: #close---open398339+Node: close --assert398449+Ref: #close---assert398593+Node: close --assign398814+Ref: #close---assign398960+Node: close --retain399486+Ref: #close---retain399637+Node: close customisation400382+Ref: #close-customisation400559+Node: close and balance assertions402026+Ref: #close-and-balance-assertions402221+Node: close examples403548+Ref: #close-examples403687+Node: Retain earnings403785+Ref: #retain-earnings403942+Node: Migrate balances to a new file404288+Ref: #migrate-balances-to-a-new-file404512+Node: More detailed close examples405640+Ref: #more-detailed-close-examples405836+Node: rewrite405862+Ref: #rewrite405972+Node: Re-write rules in a file408434+Ref: #re-write-rules-in-a-file408595+Node: Diff output format409744+Ref: #diff-output-format409925+Node: rewrite vs print --auto411017+Ref: #rewrite-vs.-print---auto411175+Node: Maintenance commands411731+Ref: #maintenance-commands411902+Node: check411940+Ref: #check412039+Node: Basic checks413022+Ref: #basic-checks413140+Node: Strict checks413975+Ref: #strict-checks414116+Node: Other checks414850+Ref: #other-checks414990+Node: Custom checks416705+Ref: #custom-checks416825+Node: diff417160+Ref: #diff417270+Node: test418367+Ref: #test418463+Node: PART 5 COMMON TASKS419239+Ref: #part-5-common-tasks419398+Node: Getting help419472+Ref: #getting-help419621+Node: Constructing command lines420381+Ref: #constructing-command-lines420562+Node: Starting a journal file421219+Ref: #starting-a-journal-file421401+Node: Setting LEDGER_FILE422603+Ref: #setting-ledger_file422775+Node: Setting opening balances423732+Ref: #setting-opening-balances423913+Node: Recording transactions427054+Ref: #recording-transactions427223+Node: Reconciling427779+Ref: #reconciling427911+Node: Reporting430168+Ref: #reporting430297+Node: Migrating to a new file434282+Ref: #migrating-to-a-new-file434432+Node: BUGS434731+Ref: #bugs434825+Node: Troubleshooting435704+Ref: #troubleshooting435804  End Tag Table